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.


Table of Contents


Installing

Installation is simple – just follow the regular WordPress plugin installation steps. Either upload the zip file via Admin -> Plugins -> Add New, or unzip it and upload the whole folder via FTP.

Dependencies

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

Getting Started

Once you’ve installed the zip file and activated the plugin, you’ll see a few extra fields under Admin -> Settings -> Forums -> Email Notifications.

Admin Options

  1. Default Digests Frequency
  2. Default Instant Forum Notifications
  3. Digest Email Subject
  4. Digest Email Body

Let’s go over these by parts. We start with the options under Admin -> Forums -> Email Notifications.

Default Digests Frequency

Default Digests Frequency

By default, when a new user registers to your site, no digest options are set up. They continue to receive the email notifications as they come along. This option lets you select which option should be set to the user as soon as he steps through the door.

Default Instant Forum Notifications

The Instant Forum Notifications option controls whether people get the regular messages the moment they’re created or not. If this is not checked, then the Digests plugin 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.

Digest Email Subject

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], [FREQUENCY], and the special [digest-list] tag.

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

Digest Email Body

Digest Email Body

This is where you set up the email message. As you can see in the screenshot, the available tags are the same as the ones used in the the Email Subject line, with the addition of [digest-list].

The [digest-list] tag gets replaced with the actual digest HTML. You cannot edit the format of the digest itself, but you CAN hook into the filter bbpnns_digest_format_forum_posts to override the default digest formatting. More details in the section Under the Hood.

This is what the default mailout looks like.

⇪Top

You’ll also see the following under the WordPress and bbPress User Profile screens:

User Options

  1. Forum Digest Preferences
  2. Instant Forum Notifications

Forum Digest Preferences

This is where your user can change the Digests preferences. A setting of “Off” effectively turns off Digests functionality for that user, as if it weren’t installed at all. Normally, this means that the user will receive immediate notifications every time a new topic or reply is posted.

There are 3 places where the preferences are displayed/edited: the WordPress Profile screen, the main bbPress Profile screen (under Subscriptions), and the bbPress Profile screen in edit mode.

Forum Digest Preferences in WP Profile

The WordPress Profile Screen


The bbPress main Profile screen


The bbPress Profile Screen in Edit Mode

Instant Forum Notifications

This is a special setting, which allows the user to have their cake and eat it, too. Aside from getting Digests in the frequency they specify, they’ll also receive the immediate notifications as if Digests were set to ‘Off’. Instant Forum Notifications is unchecked by default.

It’s accessible in the same 3 places as the Forum Digest Preferences. See the images below.

Instant Forum Notifications in the WordPress Profile screen

⇪Top

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, 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 I’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 is part of the roles selected to be notified, or that Override Core Subscriptions are turned on (these are bbPNNS settings). If a user is NOT part of a role that is set to be notified and Overrides are off, they will NOT see any fields for this plugin at all.

As mentioned before, wp-cron can be a bit iffy, especially if you don’t have many visits to your website. I’ve used 2 solutions to ensure that cron jobs (mine and any others) get triggered in a timely manner: Improved Cron, and setting up a real cron job.

⇪Top

Under the Hood

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

Queuing Messages

  1. When a new topic/reply is created, bbPNNS fetches all the users for the roles selected under Admin -> Forums -> Email Notifications.
  2. bbpnns-digest 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. The recipient list is also filtered by bbpnns-digests, and any users who are set to digests different than ‘off’ are removed from the list of recipients.
  4. Users who have ‘Instant Forum Notifications’ checked are added back into the recipients array.
  5. The regular notification emails are sent out to the filtered list.

At this stage, a user may or may not have received an immediate notification, depending on their settings. No digest emails have been sent out.

Mailing Digests

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

  1. bbpnns-digest checks if the schedule is daily, weekly, or monthly;
  2. It pulls up users who have the applicable frequency;
  3. It looks for those users under {$wpdb->prefix}bbpnns_digest_queue, 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.

Overriding the Digests HTML

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
  5. post_type (will be either the topic or reply post_type, however you have it set)
  6. timestamp

If this filter exists, none of the other formatting filters will be called. Have a look at the file bbpnns-digest/includes/view/digest_list.class.php to see how it works.

bbpnns_digest_topic_li_entry

Use bbpnns_digest_topic_li_entry filter to format the whole <li> 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 <li> 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().

Parameters (bbpnns_digest_post_url):

  • $default_topic_url
  • $forum_id
  • $topic_object

Parameters (bbpnns_digest_topic_entry):

  • $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 <li> 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. Use this filter to change the URL to your liking.

Parameters:

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

⇪Top

F.A.Q.

– I’m using BuddyPress and my users can’t see the Digest options in the BuddyPress 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 does is hijack the bbPress screen and replace it with its own.

In order for the user to be able to update the options, I had to write an extra bridge plugin to make all my bbPress add-ons work nicely with BuddyPress. As an added bonus, the bridge also adds Groups compliance to the add-ons (so that only people of a given group will receive notifications from that group’s forum).

– Why couldn’t you bundle up BuddyPress functionality with your Digests plugin?

I could not build it into the Digests or Opt-Out add-ons because it would bloat the code and not everyone uses BuddyPress. I also offer a bridge for MemberPress and plan to release a bridge for Ultimate Member soon, as well as any other membership plugins that become popular.

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

Yes, it can. There are several filters available to override it. 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.

10 thoughts on “bbPress Notify (No-Spam) Digests Documentation

  1. “When a new topic/reply is created, bbPNNS fetches all the users for the roles selected under Admin -> Forums -> Email Notifications.”

    There are two lists of user roles – Notifications about new topics are sent to, and Notifications about replies are sent to.

    Which do I need to check to enable digests to be sent to the people who have digests enabled?

  2. I have two comments. One is that it would more helpful trying to get a real sense of how the emails look if you used different topic names than you have it now. For example, under Replies,

    Test new topic >> Reply To: Test new topic

    I honestly don’t get it. Why does it say “Test new topic” twice? Is the person replying using the same header for their reply as the name of the forum topic?

    My second comment is that it seems you originally created this for admin notifications but realized that there was another group of users who might like to use this, like me, who simply are looking for a solution to make bbPress more notification friendly for the forum users – that is, allowing users to subscribe to a digest of content.

    If that is the case, I could offer some feedback on how you could tweak this to make it more friendly for that use, perhaps leading to more sales. In my case, your paid plugin almost gets it but is confusing to the word “OFF” next to digest, because in my use case the person would still be receiving every notifications for every post and reply unless they used the other plugin of yours that allows turning this off.

    A quick improvement might be to replace “Off” with something like, “No Digest”. Better, but still not ideal.

    Ultimately, if you could tweak what you have already created, you could create a plugin that allows users to start out getting nothing, but if they wanted to, they could use one dropdown menu to select an email notification option – every post and reply; a daily digest, weekly digest, monthly digest; only when someone replies to a post I started or subscribed to. Man that would really nail it. That is what my client wants and I can see that being a desired solution for many.

    cheers,

    David Tierney
    http://designsbytierney.com

    • Hi David,

      Thanks for taking the time to reach out! It’s always good to get suggestions for improvement.

      Regarding the topic name in the sample screenshot, Test New Topic is the name of the topic, and Reply To: Test New Topic is the default reply title that bbPress assigns to replies. I’ll change it to something clearer in the sample screenshot.

      Digests is an add-on to bbPress Notify (No-Spam), which was indeed written as an admin notification tool. It was modified to service regular users due to many requests.

      The ‘OFF’ settings means that the Digests are not in effect. When I wrote it, I also had a hard time thinking of a better descriptor, and ended up keeping it that way. One thing your comment brought to my attention, however, is that there’s a typo in the front end description. I’ll fix that, too.

      I like your suggestion of centralizing all options in a single location. It does make sense, but will require some major modifications. Would you care to add it to the wish list forum so people can weigh in on it?

      Cheers,
      Vinny

  3. I found the wish list but it says I have to be logged in and I don’t have an account with your system nor do I see a way to join. I am just a passer byer who was looking for a solution for a client and found your plugins. I seem to have been able to comment here because it is connected to my WP account from 8 years ago.

    • Hi David,

      Sorry for the late reply. Things have been pretty hectic lately (I guess that’s a good thing 🙂 ). I’ve turned on anonymous posting in the forums for now.

      Cheers,
      Vinny

  4. Hey Vinny, when customizing the digest html, is it possible to show a conditional based on frequency? I want to show expanded content for daily subscribers while monthly subscribers should keep getting a more condensed version. Thanks!

    • Hi Gigi,

      At ths time, there currently aren’t any conditional shortcodes, nor can you set different templates for different frequencies using the admin. It can be done using a couple of filters, though. I started explaining how but found it’s too convoluted to explain in a comment.

      I’ll put this in my todo list for a future release, but if you really need this urgently, let me know via email or skype and I’ll help you set it up.

      Cheers,
      Vinny

  5. Is there any language localization support? What is your refund policy in case this product does not meet my needs. Thank you.

    • Hi Erick,

      We provide .pot files which you can use to translate to your language. The subscription is for updates and support. If you are not satisfied with the plugin functionality, please let me know and I’ll try to accommodate your requests. Or, if you prefer, I’ll cancel your subscription and give you a full refund. However, if you choose to keep using it after that, it will not get any further updates.

      Cheers,
      Vinny

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.