bbPress Notify (No-Spam) Digests Documentation

bbpnns Digest

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. Digest Email Subject
  4. 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’.

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 Digest. Currently the default format is a list of topic titles (with links) followed by a summary of number of replies to each topic. See the F.A.Q.s below on how to modify the digest list to your preference.

Sample Digests Email
Sample Digest Email

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.

WordPress Profile Screen Options
WordPress Profile Screen Options
The bbPress Subscriptions Screen
The bbPress Subscriptions Screen
The bbPress Edit Profile 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

    We’re working on a better way to override the Digests HTML, but until that’s done, this is what you can do instead:

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

    Subscribe to Our Newsletter