bbPress Notify (No-Spam) Digests Documentation | UseStrict Consulting

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.

Contents

Installation
Dependencies
Getting Started
- Global Options
- User Options
Testing Mailouts
- Seeing/Triggering Scheduled Mailouts
Under The Hood
F.A.Q.

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;

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:

Default Digests Frequency
Default Instant Forum Notifications
Default Digest Type
Update All Users
Digest Email Subject
Digest Email Body

Default Digests Frequency

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

Default Instant Forum Notifications

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

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

Update All Users

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

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

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.

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:

bbpnns_digest_notify_daily
bbpnns_digest_notify_weekly
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.

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.
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.
If the digester does not have Instant Forum Notifications selected, then they are dropped from bbpnns’ recipient list.
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:

WP Cron triggers one or more of the digest actions – remember, there’s one for each frequency.
bbpnns-digests pulls up users who have the applicable frequency;
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;
Once it sends out the message, it removes all applicable rows from the table.
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.
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.
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:

Create a directory to place the templates: /path/to/themes/your-child-theme/bbpnns-digest
Find the desired template file under your WordPress /path/to/plugins/bbpnns-digest/templates;
Copy it to the directory created in step #1 above
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:

notification_id
user_id
forum_id
post_id – the ID of the topic or reply
post_type (will be either the topic or reply post_type)
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.

I'm using BuddyPress/Memberpress/Ultimate Member and my users can't see the Digest options in the User Profile page.

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.

I don't like the way the digests message looks. Can it be changed?

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.

How do I change the default order of the digest items?

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;
}

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.

Contents

Installation
Dependencies
Getting Started
- Global Options
- User Options
Testing Mailouts
- Seeing/Triggering Scheduled Mailouts
Under The Hood
F.A.Q.

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;

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:

Default Digests Frequency
Default Instant Forum Notifications
Default Digest Type
Update All Users
Digest Email Subject
Digest Email Body

Default Digests Frequency

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

Default Instant Forum Notifications

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

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

Update All Users

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

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

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.

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:

bbpnns_digest_notify_daily
bbpnns_digest_notify_weekly
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.

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.
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.
If the digester does not have Instant Forum Notifications selected, then they are dropped from bbpnns’ recipient list.
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:

WP Cron triggers one or more of the digest actions – remember, there’s one for each frequency.
bbpnns-digests pulls up users who have the applicable frequency;
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;
Once it sends out the message, it removes all applicable rows from the table.
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.
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.
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:

Create a directory to place the templates: /path/to/themes/your-child-theme/bbpnns-digest
Find the desired template file under your WordPress /path/to/plugins/bbpnns-digest/templates;
Copy it to the directory created in step #1 above
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:

notification_id
user_id
forum_id
post_id – the ID of the topic or reply
post_type (will be either the topic or reply post_type)
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.

I'm using BuddyPress/Memberpress/Ultimate Member and my users can't see the Digest options in the User Profile page.

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.

I don't like the way the digests message looks. Can it be changed?

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.

How do I change the default order of the digest items?

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;
}