bbPress Notify (No-Spam) Digests Documentation

Logo for bbpnns Digests

bbPress Notify (No-Spam) Digests, bbpnns-digests for short, is an add-on for bbpnns that enables your users to receive a single email containing a list of topics and replies sent over the selected period. Keep reading to learn more about it.

If you don’t have your copy yet, you can get it here.

Installation

The bbpnns Digests Add-on can be installed like any other WordPress plugin. Follow the steps below after downloading the zip file from The Downloads Section of My Accounts.

Via the Admin:

  • Go to Admin > Plugins > Add New;
  • Click Upload Plugin;
  • Click Browse and select the downloaded Zip file;
  • Click Install Now;
  • Click Activate;

Via FTP:

  • Unzip the downloaded Zip file in your local computer;
  • Upload the unzipped directory into your wp-content/plugins/ directory;
  • Go to Admin > Plugins;
  • Click Activate in the row of the uploaded plugin;

⇪Top

Dependencies

WordPress v.3.5+, bbPress v.2.5+, and bbPress Notify (No-Spam) v.1.9+.

Getting Started

Once you’ve installed the zip file and activated the plugin, you’ll see new tab in the bbpnns screen, accessible at Admin -> bbPress Notify (No-Spam) -> Settings .

Global Options

This panel lets you configure default settings for new users and the look and feel of the Digests email. It is comprised of the following sections:

  1. Default Digests Frequency
  2. Default Instant Forum Notifications
  3. Default Digest Type
  4. Update All Users
  5. Digest Email Subject
  6. Digest Email Body

⇪Top

Default Digests Frequency
Default Digests Frequency
The Default Frequency Setting

This setting tells bbpnns-digest what frequency to give newly registered users. Supported values are: Off, Daily, Weekly, and Monthly.

Default Instant Forum Notifications
Default Instant Forum Notifications Preference
The Default Instant Forum Notifications Setting

The Instant Forum Notifications option controls whether users get the regular messages the moment they’re created or not. If this is not checked, then the add-on will stop bbpnns from messaging the user, and will only keep a record of the message for when the time comes to send the digests.

The default setting is what gets applied to newly registered users.

Note that this is only takes effect if the user’s Frequency is not ‘Off’.

Default Digest Type
Default Digest Type
The Default Digest Type Setting

As of Digests version 2.0, users can choose to receive digests having either condensed or full content. Default is condensed.

Update All Users
Update All Users
The Update All users tool

Digests v2.0 also introduces the Update All Users tool. This is especially helpful when you have just installed the Digests add-on and want to apply all default settings to existing users.

Digest Email Subject
The Digest Subject Line Setting
The Digest Subject Line Setting

This controls the subject of the Digest message. On top of the regular bbpnns tags, Digests also supports the following:

[frequency], [Frequency], and [FREQUENCY]

Note that the difference between [frequency], [Frequency], and [FREQUENCY] is just the case. e,g. “weekly”, “Weekly”, and “WEEKLY”, respectively.

Digest Email Body
The Digest Email Body Editor
The Digest Email Body Editor

This controls the body of the Digest message. On top of the regular bbpnns tags and the subject tags, the body needs the special [digest-list] tag.

This is a placeholder for the user’s actual digest, whether it be the Condensed or Full version.

User Options

Out of the box, users can change their preferences in one of 2 places:

  • The WordPress Profile Screen
  • The bbPress Profile Screen (under Subscriptions and Edit)

Editable options are the Forum Digest Preference (enabled/disabled), the Frequency, and whether to receive Instant Forum Notifications.

Digest User Preferences
WordPress Profile Screen Options
bbPress Subscriptions Screen
The bbPress Subscriptions Screen
Digests bbPress Edit Screen
The bbPress Profile Screen in Edit Mode

Testing Mailouts

Digest mailouts can be sent in 3 different intervals: daily, weekly, and monthly. The exact time when each one is sent will vary according to a few factors such as when the plugin was last activated and how often your site is accessed. This is mainly because bbpnns-digests uses WordPress cron jobs to send out the messages. When you activate the plugin, it creates the 3 cron jobs (one for each frequency), scheduled to run at their respective times in the future. However, by default, wp-cron only really fires when your site is accessed by a visitor.

There are a few ways to circumvent this, which we’ll cover soon enough.

Seeing/Triggering Scheduled Mailouts

The first step to figuring out if your mailouts are going to work is to see if they are actually scheduled. I use a plugin for that: WP Crontrol. Not only does it show me the scheduled jobs, but it lets me modify them and execute them whenever I want to, too. I strongly recommend it.

It’s also important to make sure that the user belongs to one or more of the roles selected to be notified, or that Authors are set to receive notices of their own posts, or that Override Core Subscriptions are turned on (these are all bbpnns settings). If none of those settings are set, they will NOT see any fields for this plugin at all.

If you’re running your initial set up on your staging site (you are using a staging site, right?), I recommend triggering the actions via WP Crontrol manually. Go to Admin > Tools > Cron Events and look for these three jobs:  
  1. bbpnns_digest_notify_daily
  2. bbpnns_digest_notify_weekly
  3. bbpnns_digest_notify_monthly
 
Click Run Now for the job that you want to run and that will kick off the digests (as long as there are queued messages in the database.
Once you’re happy and you apply your changes to Production, you’ll need to make sure it runs on its own. As mentioned before, wp-cron can be a bit iffy, especially if you don’t have a lot of traffic. The best way to get WP to run its cron in a timely manner is to set up a real cron job. If you’re using cPanel, check out this tutorial by SiteGround*. If you’re hosting with WP-Engine, ask them to turn on their Alternate Cron. It’s their version of a real cron job, which will run every minute. Another really good solution is to use cron-job.org. * Affiliate link.

Under the Hood

Here’s a bit of a technical explanation of the Digests plugin and how it interacts with bbpnns.

  1. When a new topic/reply is created, bbpnns fetches all the users for the roles selected under Admin > bbPress Notify (No-Spam) > Settings > Topics or Replies tabs.
  2. bbpnns-digests pulls up all users having digests different than ‘off’ and inserts a row for each one in the table {$wpdb->prefix}bbpnns_digest_queue.
  3. If the digester does not have Instant Forum Notifications selected, then they are dropped from bbpnns’ recipient list.
  4. bbpnns resumes its mailout process to whoever is left in the recipient list.
At this stage, no digest messages have been sent out. They only get sent out when the scheduled action is triggered by wp-cron.

    Mailing Digests

    And then the time comes when one of our scheduled jobs gets triggered. This is what happens:

    1. WP Cron triggers one or more of the digest actions – remember, there’s one for each frequency.
    2. bbpnns-digests pulls up users who have the applicable frequency;
    3. It looks for those users under {$wpdb->prefix}bbpnns_digest_queue and {$wpdb->prefix}usermeta, and builds the digest list with the information found in the table;
    4. Once it sends out the message, it removes all applicable rows from the table.
    5. Note that due to the dynamic nature of digests contents (not all users may have the same digests), one message is sent to each user. This can take time, depending on the number of messages that need to be sent.
    6. If your host supports forking, Digests will run in batches of 5 emails at a time. This will help keep your process from being killed due to it taking too long to notify those hundreds of users.
    7. Alternatively you can consider using our Bulk Mailer Add-on, which can send up to 1000 messages in the time it takes to send one (Mailgun or Sendgrid account required).

    Overriding Digests HTML

    Digests v2.0 introduces the ability to override the Condensed or Full digests template. To do so, you’ll need to copy the original template into your child theme’s directory and make your modifications there as follows:

    1. Create a directory to place the templates: /path/to/themes/your-child-theme/bbpnns-digest
    2. Find the desired template file under your WordPress /path/to/plugins/bbpnns-digest/templates;
    3. Copy it to the directory created in step #1 above
    4. Edit it to your heart’s content.
    Each user’s digest data is populated into the $stash object. You’ll find a phpdoc comment at the top of each template file describing the structure of the object.
    There is also the legacy way of overriding the HTML, by using filters.

      You can choose to override the whole Digests HTML, or just a few pieces if it – namely the information displayed in the topic and reply list elements. The available filters are described below.

      bbpnns_digest_format_forum_posts

      Overriding the whole HTML can be achieved by hooking into bbpnns_digest_format_forum_posts with a method of your own. The parameters passed are an empty string and the contents of the queue table as an associative array:

      1. notification_id
      2. user_id
      3. forum_id
      4. post_id – the ID of the topic or reply
      5. post_type (will be either the topic or reply post_type)
      6. timestamp

      If this filter exists, none of the other formatting filters (below) will be called.

      bbpnns_digest_topic_li_entry

      Use bbpnns_digest_topic_li_entry filter to format the whole content for each topic. If this filter returns anything other than an empty string, that is what will be displayed for each post in the Digests message.

      Parameters:

      • $empty_string
      • $forum_id
      • $reply_object
      • $topic_object

      bbpnns_digest_post_url and bbpnns_digest_topic_entry

      If the bbpnns_digest_topic_li_entry filter did not get set, then the topic line can be customized. Use bbpnns_digest_post_url to customize the link href, and bbpnns_digest_topic_entry to customize the link text. Note that the output of bbpnns_digest_post_url will be escaped via esc_url().

      bbpnns_digest_post_url Parameters:

      • $default_topic_url
      • $forum_id
      • $topic_object

      bbpnns_digest_topic_entry Parameters:

      • $post_title filtered by ‘the_title’
      • $forum_id
      • $topic_object

      bbpnns_digest_reply_li_entry

      The bbpnns_digest_reply_li_entry filter works just like bbpnns_digest_topic_li_entry. Like its topic counterpart, if this is set, then the reply content will be whatever gets returned. This is the preferred method of changing the link text in replies.

      Parameters:

      • $empty_string
      • $forum_id
      • $reply_object
      • $topic_id

      bbpnns_digest_topic_url_in_reply

      As of Digests version 1.4.2, the reply link no longer points to the page with the standalone reply. Instead, it points to the topic page, with the reply ID in the fragment (e.g. http://domain.com/topics/topic-name#post-1234, where 1234 is the reply ID). Use this filter to change that behaviour.

      Parameters:

      • $default_url
      • $forum_id
      • $reply_object
      • $topic_id

      F.A.Q.

      bbpnns-digests comes with support for WordPress and bbPress Profile pages out of the box. This means that if you go to the bbPress user screen, you’ll be able to view and edit the options. What BuddyPress and the other membership plugins do is force the users to go to different profile screens.

      In order for the user to be able to update the digest options, you’ll need the appropriate bridge add-on.

      Yes, it can. While we’re still working on an easy way to override the HTML, there are several filters available to get the job done. Please see the section on Overriding the Digests HTML. If you’re not comfortable with writing PHP, do contact me for a free estimate. Just do NOT modify the core files or you’ll lose your changes with the next update.

      There’s a filter for that: bbpnns_queue_order_by. You can hook into it by adding the following snippet of code to your functions.php file.
      add_filter( 'bbpnns_queue_order_by', 'my_custom_digest_order', 10, 1 );
      
      function my_custom_digest_order( $order_by )
      {
          /**
           * Available fields are:
           * - q.notification_id
           * - q.user_id
           * - q.forum_id
           * - q.post_id
           * - q.post_type
           * - q.timestamp
           *
           * @see http://www.mysqltutorial.org/mysql-order-by 
           * for syntax and examples of order by.
           */
           $order_by = 'order by q.post_id DESC'; //
      
           return $order_by;
      }
      Logo for bbpnns Digests

      bbPress Notify (No-Spam) Digests Documentation

      bbPress Notify (No-Spam) Digests, bbpnns-digests for short, is an add-on for bbpnns that enables your users to receive a single email containing a list of topics and replies sent over the selected period. Keep reading to learn more about it.

      If you don’t have your copy yet, you can get it here.

      Installation

      The bbpnns Digests Add-on can be installed like any other WordPress plugin. Follow the steps below after downloading the zip file from The Downloads Section of My Accounts.

      Via the Admin:

      • Go to Admin > Plugins > Add New;
      • Click Upload Plugin;
      • Click Browse and select the downloaded Zip file;
      • Click Install Now;
      • Click Activate;

      Via FTP:

      • Unzip the downloaded Zip file in your local computer;
      • Upload the unzipped directory into your wp-content/plugins/ directory;
      • Go to Admin > Plugins;
      • Click Activate in the row of the uploaded plugin;

      ⇪Top

      Dependencies

      WordPress v.3.5+, bbPress v.2.5+, and bbPress Notify (No-Spam) v.1.9+.

      Getting Started

      Once you’ve installed the zip file and activated the plugin, you’ll see new tab in the bbpnns screen, accessible at Admin -> bbPress Notify (No-Spam) -> Settings .

      Global Options

      This panel lets you configure default settings for new users and the look and feel of the Digests email. It is comprised of the following sections:

      1. Default Digests Frequency
      2. Default Instant Forum Notifications
      3. Default Digest Type
      4. Update All Users
      5. Digest Email Subject
      6. Digest Email Body

      ⇪Top

      Default Digests Frequency
      Default Digests Frequency
      The Default Frequency Setting

      This setting tells bbpnns-digest what frequency to give newly registered users. Supported values are: Off, Daily, Weekly, and Monthly.

      Default Instant Forum Notifications
      Default Instant Forum Notifications Preference
      The Default Instant Forum Notifications Setting

      The Instant Forum Notifications option controls whether users get the regular messages the moment they’re created or not. If this is not checked, then the add-on will stop bbpnns from messaging the user, and will only keep a record of the message for when the time comes to send the digests.

      The default setting is what gets applied to newly registered users.

      Note that this is only takes effect if the user’s Frequency is not ‘Off’.

      Default Digest Type
      Default Digest Type
      The Default Digest Type Setting

      As of Digests version 2.0, users can choose to receive digests having either condensed or full content. Default is condensed.

      Update All Users
      Update All Users
      The Update All users tool

      Digests v2.0 also introduces the Update All Users tool. This is especially helpful when you have just installed the Digests add-on and want to apply all default settings to existing users.

      Digest Email Subject
      The Digest Subject Line Setting
      The Digest Subject Line Setting

      This controls the subject of the Digest message. On top of the regular bbpnns tags, Digests also supports the following:

      [frequency], [Frequency], and [FREQUENCY]

      Note that the difference between [frequency], [Frequency], and [FREQUENCY] is just the case. e,g. “weekly”, “Weekly”, and “WEEKLY”, respectively.

      Digest Email Body
      The Digest Email Body Editor
      The Digest Email Body Editor

      This controls the body of the Digest message. On top of the regular bbpnns tags and the subject tags, the body needs the special [digest-list] tag.

      This is a placeholder for the user’s actual digest, whether it be the Condensed or Full version.

      User Options

      Out of the box, users can change their preferences in one of 2 places:

      • The WordPress Profile Screen
      • The bbPress Profile Screen (under Subscriptions and Edit)

      Editable options are the Forum Digest Preference (enabled/disabled), the Frequency, and whether to receive Instant Forum Notifications.

      Digest User Preferences
      WordPress Profile Screen Options
      bbPress Subscriptions Screen
      The bbPress Subscriptions Screen
      Digests bbPress Edit Screen
      The bbPress Profile Screen in Edit Mode

      Testing Mailouts

      Digest mailouts can be sent in 3 different intervals: daily, weekly, and monthly. The exact time when each one is sent will vary according to a few factors such as when the plugin was last activated and how often your site is accessed. This is mainly because bbpnns-digests uses WordPress cron jobs to send out the messages. When you activate the plugin, it creates the 3 cron jobs (one for each frequency), scheduled to run at their respective times in the future. However, by default, wp-cron only really fires when your site is accessed by a visitor.

      There are a few ways to circumvent this, which we’ll cover soon enough.

      Seeing/Triggering Scheduled Mailouts

      The first step to figuring out if your mailouts are going to work is to see if they are actually scheduled. I use a plugin for that: WP Crontrol. Not only does it show me the scheduled jobs, but it lets me modify them and execute them whenever I want to, too. I strongly recommend it.

      It’s also important to make sure that the user belongs to one or more of the roles selected to be notified, or that Authors are set to receive notices of their own posts, or that Override Core Subscriptions are turned on (these are all bbpnns settings). If none of those settings are set, they will NOT see any fields for this plugin at all.

      If you’re running your initial set up on your staging site (you are using a staging site, right?), I recommend triggering the actions via WP Crontrol manually. Go to Admin > Tools > Cron Events and look for these three jobs:

      1. bbpnns_digest_notify_daily
      2. bbpnns_digest_notify_weekly
      3. bbpnns_digest_notify_monthly
      Click Run Now for the job that you want to run and that will kick off the digests (as long as there are queued messages in the database.

      Once you’re happy and you apply your changes to Production, you’ll need to make sure it runs on its own. As mentioned before, wp-cron can be a bit iffy, especially if you don’t have a lot of traffic. The best way to get WP to run its cron in a timely manner is to set up a real cron job. If you’re using cPanel, check out this tutorial by SiteGround*. If you’re hosting with WP-Engine, ask them to turn on their Alternate Cron. It’s their version of a real cron job, which will run every minute. Another really good solution is to use cron-job.org.

      * Affiliate link.

      Under the Hood

      Here’s a bit of a technical explanation of the Digests plugin and how it interacts with bbpnns.

      1. When a new topic/reply is created, bbpnns fetches all the users for the roles selected under Admin > bbPress Notify (No-Spam) > Settings > Topics or Replies tabs.
      2. bbpnns-digests pulls up all users having digests different than ‘off’ and inserts a row for each one in the table {$wpdb->prefix}bbpnns_digest_queue.
      3. If the digester does not have Instant Forum Notifications selected, then they are dropped from bbpnns’ recipient list.
      4. bbpnns resumes its mailout process to whoever is left in the recipient list.
      At this stage, no digest messages have been sent out. They only get sent out when the scheduled action is triggered by wp-cron.

        Mailing Digests

        And then the time comes when one of our scheduled jobs gets triggered. This is what happens:

        1. WP Cron triggers one or more of the digest actions – remember, there’s one for each frequency.
        2. bbpnns-digests pulls up users who have the applicable frequency;
        3. It looks for those users under {$wpdb->prefix}bbpnns_digest_queue and {$wpdb->prefix}usermeta, and builds the digest list with the information found in the table;
        4. Once it sends out the message, it removes all applicable rows from the table.
        5. Note that due to the dynamic nature of digests contents (not all users may have the same digests), one message is sent to each user. This can take time, depending on the number of messages that need to be sent.
        6. If your host supports forking, Digests will run in batches of 5 emails at a time. This will help keep your process from being killed due to it taking too long to notify those hundreds of users.
        7. Alternatively you can consider using our Bulk Mailer Add-on, which can send up to 1000 messages in the time it takes to send one (Mailgun or Sendgrid account required).

        Overriding Digests HTML

        Digests v2.0 introduces the ability to override the Condensed or Full digests template. To do so, you’ll need to copy the original template into your child theme’s directory and make your modifications there as follows:

        1. Create a directory to place the templates: /path/to/themes/your-child-theme/bbpnns-digest
        2. Find the desired template file under your WordPress /path/to/plugins/bbpnns-digest/templates;
        3. Copy it to the directory created in step #1 above
        4. Edit it to your heart’s content.
        Each user’s digest data is populated into the $stash object. You’ll find a phpdoc comment at the top of each template file describing the structure of the object.
        There is also the legacy way of overriding the HTML, by using filters.

          You can choose to override the whole Digests HTML, or just a few pieces if it – namely the information displayed in the topic and reply list elements. The available filters are described below.

          bbpnns_digest_format_forum_posts

          Overriding the whole HTML can be achieved by hooking into bbpnns_digest_format_forum_posts with a method of your own. The parameters passed are an empty string and the contents of the queue table as an associative array:

          1. notification_id
          2. user_id
          3. forum_id
          4. post_id – the ID of the topic or reply
          5. post_type (will be either the topic or reply post_type)
          6. timestamp

          If this filter exists, none of the other formatting filters (below) will be called.

          bbpnns_digest_topic_li_entry

          Use bbpnns_digest_topic_li_entry filter to format the whole content for each topic. If this filter returns anything other than an empty string, that is what will be displayed for each post in the Digests message.

          Parameters:

          • $empty_string
          • $forum_id
          • $reply_object
          • $topic_object

          bbpnns_digest_post_url and bbpnns_digest_topic_entry

          If the bbpnns_digest_topic_li_entry filter did not get set, then the topic line can be customized. Use bbpnns_digest_post_url to customize the link href, and bbpnns_digest_topic_entry to customize the link text. Note that the output of bbpnns_digest_post_url will be escaped via esc_url().

          bbpnns_digest_post_url Parameters:

          • $default_topic_url
          • $forum_id
          • $topic_object

          bbpnns_digest_topic_entry Parameters:

          • $post_title filtered by ‘the_title’
          • $forum_id
          • $topic_object

          bbpnns_digest_reply_li_entry

          The bbpnns_digest_reply_li_entry filter works just like bbpnns_digest_topic_li_entry. Like its topic counterpart, if this is set, then the reply content will be whatever gets returned. This is the preferred method of changing the link text in replies.

          Parameters:

          • $empty_string
          • $forum_id
          • $reply_object
          • $topic_id

          bbpnns_digest_topic_url_in_reply

          As of Digests version 1.4.2, the reply link no longer points to the page with the standalone reply. Instead, it points to the topic page, with the reply ID in the fragment (e.g. http://domain.com/topics/topic-name#post-1234, where 1234 is the reply ID). Use this filter to change that behaviour.

          Parameters:

          • $default_url
          • $forum_id
          • $reply_object
          • $topic_id

          F.A.Q.

          bbpnns-digests comes with support for WordPress and bbPress Profile pages out of the box. This means that if you go to the bbPress user screen, you’ll be able to view and edit the options. What BuddyPress and the other membership plugins do is force the users to go to different profile screens.

          In order for the user to be able to update the digest options, you’ll need the appropriate bridge add-on.

          Yes, it can. While we’re still working on an easy way to override the HTML, there are several filters available to get the job done. Please see the section on Overriding the Digests HTML. If you’re not comfortable with writing PHP, do contact me for a free estimate. Just do NOT modify the core files or you’ll lose your changes with the next update.

          There’s a filter for that: bbpnns_queue_order_by. You can hook into it by adding the following snippet of code to your functions.php file.
          add_filter( 'bbpnns_queue_order_by', 'my_custom_digest_order', 10, 1 );
          
          function my_custom_digest_order( $order_by )
          {
              /**
               * Available fields are:
               * - q.notification_id
               * - q.user_id
               * - q.forum_id
               * - q.post_id
               * - q.post_type
               * - q.timestamp
               *
               * @see http://www.mysqltutorial.org/mysql-order-by 
               * for syntax and examples of order by.
               */
               $order_by = 'order by q.post_id DESC'; //
          
               return $order_by;
          }