Simple:Press Documentation

Plugin: Subscriptions

Plugin Description

The Simple:Press Subscriptions (Subscriptions – Topic and Forum) plugin allows users to subscribe to interesting topics and receive notices of new replies directly in their email.

Note: Subscribing to topics is not the same as Watching a topic. The Watches plugin information is available at Watches.

Plugin Features

Installing this plugin adds:

  • a new “Subscriptions” section to the Plugin Management panel under the forum Admin menu entry “Plugins” > “Available Plugins”. From this panel the Subscriptions plugin can be activated, deactivated, uninstalled, deleted, and its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections. The Options link goes to the new Components – Subscriptions panel where the options the admin is allowing are set.

Activating this plugin provides:

  • a new sub-menu “Subscriptions” entry under the forum Admin menu entry “Components” linked to the new Components-Subscriptions panel where the options the admin is allowing are set. Detailed “Help” links are provided and should be consulted.
  • a new subscriptions permission in each permission set under the forum Admin menu entry “Permissions” > “Manage Permission Sets” to be set by the admin if the usergroups assigned the permission set are to be allowed to subscribe to forums (if enabled) and topics.
  • a new CRON under the forum Admin menu item “Toolbox” > “CRON Inspector” for use if the email digest feature is enabled or forced by the forum admin with:
    • a new CRON Schedule with “Description” of “SP Subscription Digest Interval” with the interval (in time) between sending digest emails.
    • a new Active CRON with “Hook” named “sph_subs_digest_cron” that uses the “SP Subscription Digest Interval” to send digest emails at the specified time.
  • a subscribe/unsubscribe button at the bottom of each topic just above the footer in the Topic View.
  • a subscribe/unsubscribe radio button in a topic’s reply editor in the Topic View.
  • a subscribe/unsubscribe button on each forum in the Group View if the forum admin has allowed the option to subscribe to forums.
  • a Subscription Icon (may appear as a Heart with “This topic has subscriptions” displayed when the cursor is hovering over the icon) associated with each topic in the forum that has subscriptions.
  • a Subscription New Posts button (may appear as a Heart and displaying “Subscribed:” and a number along with the words “Review subscribed topics” shown when the cursor is hovered over the button) in the forum header that shows the number of new messages in the user’s subscribed topics linked to a page showing all the user’s subscribed topics, and allows unsubscribing to any one of them or all of them at once. Once the button is clicked and the subscribed topic list is shown, the number in the button becomes “0” until new posts are made.
  • a new “Subscriptions”tab on the user’s forum profile page with sub-menu items that when selected allows choices to:
    • use the “Subscription Option:” button to set the preferences for the Subscription Options including ones the admin has allowed such as individual emails when new posts are made to subscribed topics or a periodic digest email with a link to each of the new posts.
    • use the “Topic Subscriptions” button to list of all the user’s subscribed topics with the ability for the user to unsubscribe from a single topic or multiple topics at once.
    • use the “Forum Subscriptions” button to list of all the user’s subscribed forums with the ability for the user to subscribe or unsubscribe from individual forums.

Plugin Requirements

Requires Simple:Press version 5.5.7 and above.

The plugin must be installed, activated, its options set up, and permissions set before it is operational.

As part of the installation, a “Subscription” section is added to the Plugin Management panel under the forum Admin menu – Plugins/Available Plugins. From this panel the Subscriptions plugin can be activated, deactivated, uninstalled, deleted, and its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections. The Options link goes to the new Subscriptions Options panel where the options are set.

Some of the plugin’s template tags are included in all current themes. If the default positions and layouts are acceptable, nothing need be done. Template tag sp_SubscriptionsUnreadTopics() is not included in the current themes nor are the hooks listed below contained in sp-subscriptions-options-form.php, sp-subscriptions-manage-form.php and sp-subscriptions-forum-form.php. If sp_SubscriptionsUnreadTopics() or any of the hooks in the three (3) files are to be added to one of the themes, or if template tag changes are going to be made, it is recommended that a Custom or Child Theme is created first before installing this plugin. Information on Child Themes is located on our Creating a Child Theme page. Information on creating and installing themes is located on our Creating a Custom Theme page.

Installation and Activation

Please see Using Plugins on how to obtain and install the Simple:Press Subscriptions plugin.

As mentioned there the default location for Simple:Press plugin folders is …/wp-content/sp-resources/forum-plugins. If this path is changed, it is important to note that the plugin’s folder and its content need to reside in the forum plugins folder wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Activation is accomplished from the Admin Dashboard panel menu by selecting “Forum” and then “Plugins” from the drop down Forum Admin menu. On the Simple:Press Administration panel select the “Subscriptions” plugin on the “Plugin Management” panel and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options”. To deactivate the plugin, click on “Deactivate”. The “Deactivate/Uninstall/Options” label changes to “Activate/Delete”.

Plugin Administrative Options

After activating the Subscriptions plugin it’s various options should be set in the Simple:Press forum Admin “Components – Subscriptions” page. Access the page by either:

  • Going to the admin menu entry “Forum” >”Components” and selecting the sub-menu “Subscriptions” item.
  • Going to the admin menu entry “Forum” > “Plugins” and selecting the sub-menu “Available Plugins” item. Scrolling down the “Available Plugins – Install Simple:Press Plugins” page to the “Subscriptions” section and clicking on the “Options” link.
  • Note: for the options on the “Components – Subscriptions” page:
    • Click on its radio button to select the option. The radio button turns green when selected.
    • Click on its radio button if already green to deselect the option. The radio button turns gray when not selected.
    • When all the desired options have been selected/changed, click on the “Update” button at the bottom of the page to save the settings.
  • Auto subscribe members to all topics they post in
    • This option gives you the ability to auto subscribe members to all topics they post in.
Warning: auto subscribing members is the same as opt out (vs opt in) and is considered bad practice. If you enable this option, be sure of what you are doing and consider a disclaimer or notice to your users so they know their options. This option will affect the default setting for new users.
  • Allow members to subscribe to forums in addition to topics
    • If enabled members can elect to subscribe to a forum when viewing the forum in the Group View or in their Profile settings under the Subscriptions > Forum Subscriptions tab.
    • They can opt in to receive an email for EVERY post in the subscribed forum. Members can select how they wish to receive notification on in their Profile settings under the Subscriptions – Subscriptions Options tab.
Warning: Allowing members to subscribe to forums may be a heavy strain on the website server if its a busy forum.
  • Include post content in standard subscription emails
    • This option will include the post’s content in the individual email sent to the user for each new post in their subscribed topics/forums.
  • Enable subscription digests
    • This option enables subscription digest emails for users. When activated a member will see an option on their profile settings to receive notifications in digest form.
    • A user will be able to select receiving an email notification on every post for subscribed forums and/or topics or receiving a single email with links to all subscribed topics at the digest frequency specified in that panel.
  • Set frequency of digest (if enabled)
    • Select between “Daily digest” or “Weekly digest” emails. This selection is only meaningful if the digest email option has been selected.
  • Force digest emails
    • This option forces all users to receive digest emails. This option takes precedence over the “Enable subscription digests” option. Users will not see an option to get individual emails.
  • Include post content in digest emails
    • This option will include each post’s content in the digest email sent to the user.
Warning: on a busy site, including post content in digest emails may make for huge emails.

After setting up the administrative options, the ability for users to subscribe to topics (or forums, if enabled) must enabled by setting the new permission.

  • Assigning Permissions
    • Allowing users to subscribe to topics (or forums) is controlled by their group permissions.
    • Each member group that is to have the ability to subscribe must have the permission turned on.
    • This is accomplished from the Administration panel menu by navigating to Forum – Permissions and selecting “Manage Permissions Sets” in its sub-menu.
    • Select “Edit Permission” for the permission set to be updated to view the “Permissions – Manage Permissions” panel.
    • Under “General” click the radio button next to “Can subscribe to forums (if enabled) and topics” to set/enable the permission.
    • When enabled, the radio button is green in color. Click “Update Permission” at the bottom of the permission set to have the selection saved.
    • At a later time clicking the radio button when it is green removes the green color and will remove the permission when followed by clicking “Update Permission” to save the revised selection.

Plugin Language Translation

A plugin’s message strings can be translated from English to other languages and then the translation displayed if language translation files are available. Some plugins may not have such files.

Information regarding downloading language files, “mo’ language file placement, and translation (language localization) is found at Localization.

More information is available regarding translation files at Simple:Press Translations. On the base page, select the “Getting Started Guide” link for basics about it’s use. On that page, select the “register a username here” link to obtain a password to the site. Use the “Contact Form” link to request the desired language if it is not currently available. The “Contact Form” link may also be used to volunteer to be a validator for a translation project.

The Subscriptions plugin’s available language translation files with translation statistics, and message translations can be viewed at Subscriptions Translations. Select the Version link to see the languages available. Select the link for the desired language to see forum messages and their available translations. If available, export the file for the selected language to its proper forum language sub-folder as a “mo” file using the export link at the bottom of the page displaying the actual message translations for the language selected.

The default location for Simple:Press plugin language files is …/wp-content/sp-resources/forum-language/sp-plugins. If this path is changed, it is important to note that the plugin’s language file needs to reside in the language sub-folder for sp plugins wherever it has been moved and however it has been renamed. See Storage Locations for more information.

Plugin Usage

  • Note: for the selections where radio buttons are used:
    • Click on its radio button to select the option. The radio button turns green when selected.
    • Click on its radio button if already green to deselect the option. The radio button turns gray when not selected.
    • When all the desired options have been selected/changed, click on the nearby update button (which may have a variety of names, such as “Update”, “Update Subscription Options”, “Submit Reply” etc.) to save the settings.
  • User with permission subscribing to a topic/topics
    • Note: Only logged in users can subscribe to topics or forums. When the subscription has completed, a popup notification appears indicating “Subscription added” or “Subscription options updated” depending on specific subscription method used.
    • In Topic View, click the “Subscribe” button below the bottom of topic section and just before the footer.
    • In topic View when replying to a topic:
      • click the radio button adjacent to “Subscribe to this topic” just under the reply text input section, or
      • click the “Subscribe” button below the bottom of the reply text input section and just before the footer.
    • From all forum pages click the “Profile” button in the page header and then select the “Subscriptions” tab followed by selecting “Subscription Options”.
      • Select the radio button (if gray in color) adjacent to “Auto subscribe to topics I post in” to select the option.
      • Select the radio button (if grey in color) adjacent to “Auto subscribe to topics I post start” to select the option.
  • User with permission subscribing to a forum
    • Note: Only logged in users can subscribe to topics or forums. When the subscription has completed, a popup notification appears indicating “Subscription added” or “Subscription options updated” depending on specific subscription method used.
    • In Group View click the Subscription Icon (in its subscribe state may appear as a Heart with an “+” (plus sign) and “Subscribe to this forum” displayed when the cursor is hovering over the icon) associated with the forum. A popup notification appears indicating “Subscription added.” After the “Subscription CRON” has run, the Subscription Icon might have an “x” instead of the “+” and hovering the cursor over the Subscription Icon will display “Unsubscribe from this forum.”
    • From all forum pages click the “Profile” button in the page header and then select the “Subscriptions” tab followed by selecting “Forum Subscriptions” tab.
      • Select the radio button (if gray in color) adjacent to name of the forum to be subscribed. The radio button turns green in color when selected.
      • Select the radio button (if already green in color) adjacent to name of the forum to be unsubscribed. The radio button turns gray in color when deselected.
  • User with permission unsubscribing from a topic/topics

    • Note: Only logged in users can unsubscribe to topics or forums. When the unsubscribe has completed, a popup notification appears indicating “Subscription removed” or “Subscription options updated” depending on specific unsubscribe method used.
    • In Topic View, click the “Unsubscribe” button below the bottom of topic section and just before the footer.
    • In topic View when replying to a topic:
      • click the radio button adjacent to “Unsubscribe from this topic” just under the reply text input area, or
      • click the “Unsubscribe” button below the bottom of reply section and just before the footer.
    • From all forum pages click the “Profile” button in the page header and then select the “Subscriptions” tab followed by selecting “Subscription Options”.
      • Select the radio button (if already green in color) adjacent to “Auto subscribe to topics I post in” to deselect the option.
      • Select the radio button (if already green in color) adjacent to “Auto subscribe to topics I post start” to deselect the option.
    • From all forum pages click the Subscription New Posts button (may appear as a Heart and displaying “Subscribed:” and a number along with the words “Review subscribed topics” shown when the cursor is hovered over the button) in the forum header to display all the subscribed topics.
      • Click the “Unsubscribe” button associated with a specific topic to remove the subscription from the topic only.
      • Click the “Remove All Subscriptions” button to remove all the subscriptions at one time.
  • User with permission unsubscribing from a forum
    • Note: Only logged in users can unsubscribe to topics or forums. When the unsubscribe has completed, a popup notification appears indicating “Subscription removed” or “Subscription options updated” depending on specific unsubscribe method used.
    • In Group View click the Subscription Icon (in its unsubscribe state may appear as a Heart with an “x” and “Unsubscribe from this forum” displayed when the cursor is hovering over the icon) associated with the forum. A popup notification appears indicating “Subscription removed.” After the “Subscription CRON” has run, the Subscription Icon might have a “+” instead of the “x” and hovering the cursor over the Subscription Icon will display “Subscribe to this forum.”
  • Checking new posts to subscribed topics
    • From all forum pages click the Subscription New Posts button (may appear as a Heart and displaying “Subscribed:” and a number along with the words “Review subscribed topics” shown when the cursor is hovered over the button) in the forum header to display all the subscribed topics.

Plugin Special Notes

Note: Subscribing to topics is not the same as Watching a topic. The Watches plugin information is available at Watches.

Template Tags Used in the Plugin

There are five (5) template tags available for this plugin that allow further customization of the plugin’s usage or otherwise customize the website. The Template Tag can be viewed by selecting its link below.

Action and Hooks Used in the Plugin

There are Actions and Hooks available in the Plugin’s Template Tags. The Template Tag’s Action and Hooks can be viewed by selecting its link below.

There are other Actions and Hooks available for this plugin.

In file sp-subscriptions-forum-form.php, these can modify the display contents of the user’s profile Subscriptions tab’s Forum Subscriptions page viewable by clicking the “Forum Subscriptions” button.

  • apply_filters(‘sph_profile_subscriptions_forum’, $msg) – Allows modification of the display code for the forum subscriptions message “On this panel, you can manage your forum subscriptions.” just prior to being output/returned. $msg contains the message.
  • apply_filters(‘sph_ProfileForumSubscriptionsFormTop’, $out, $userid) – Allows modification of the display code associated with any forum subscription information in the top of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormTop’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the top of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileForumSubscriptionsFormBottom’, $out, $userid) – Allows modification of the display code associated with any forum subscription information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormBottom’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileForumSubscriptionsForm’, $out, $userid) – Allows modification of any of the display code associated with the page just prior to being output/returned.

In file sp-subscriptions-manage-form.php, these can modify the display contents of the profile Subscriptions tab’s Topic Subscriptions page viewable by clicking the “Topic Subscriptions” button.

  • apply_filters(‘sph_profile_subscriptions_topic’, $msg) – Allows modification of the display code for the topic subscriptions message “On this panel, you can manage your topic subscriptions.” just prior to being output/returned. $msg contains the message.
  • apply_filters(‘sph_ProfileTopicSubscriptionsFormTop’, $out, $userid) – Allows modification of the display code associated any topic subscriptions information in the top of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormTop’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the top of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileTopicSubscriptionsFormBottom’, $out, $userid) – Allows modification of the display code associated with any topic subscription information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormBottom’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileTopicSubscriptionsForm’, $out, $userid) – Allows modification of any of the display code associated with the page just prior to being output. The are two (2) occurrences in the file.

In file sp-subscriptions-options-form.php, these can modify the display contents of the profile Subscriptions tab’s Options page viewable by clicking the “Subscriptions Options” button.

  • apply_filters(‘sph_profile_subscriptions_options’, $msg) – Allows modification of the display code for the subscription options message “On this panel, you may set your Subscription Options preferences” just prior to being output/returned. $msg contains the message.
  • apply_filters(‘sph_ProfileFormTop’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the top of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileSubscriptionsOptionsFormTop’, $out, $userid) – Allows modification of the display code associated with any subscription option information in the top of page just prior to being output/returned.
  • apply_filters(‘sph_ProfileUserSubsAutoSub’, $tout) – Allows modification of the display code for the “Auto subscribe to topics I post in” message and radio button status just prior to being output/returned.
  • apply_filters(‘sph_ProfileUserSubsAutoStart’, $tout) – Allows modification of the display code for the “Auto subscribe to the topics I start” message and its radio button status just prior to being output.
  • apply_filters(‘sph_ProfileUserSubsDigest’, $tout) – Allows modification of the display code for the “Receive subscription notifications in digest form (daily):” message and its radio button status just prior to being output/returned if digest subscriptions are enabled.
  • apply_filters(‘sph_ProfileSubscriptionsOptionsFormBottom’, $out, $userid) – Allows modification of the display code associated with any subscription option information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormBottom’, $out, $userid, $thisSlug) – Allows modification of the display code associated with any profile information in the bottom of the page just prior to being output/returned.
  • apply_filters(‘sph_ProfilePostingOptionsForm’, $out, $userid) – Allows modification of any of the display code associated with the page just prior to being output/returned.

In file sp-subscriptions-components.php, these can modify the contents of the Profile Subscription Options, Post form display, Topic form display, and the Subscription Notification email.

    • apply_filters(‘sph_ProfileUserSubsAutoSubUpdate’, true) – Allows modification of the user’s auto subscription options selections from the profile Subscriptions, Subscription Option page just prior to the results being evaluated.
    • apply_filters(‘sph_subs_subscribe_label’, __(‘Subscribe to this topic’, ‘sp-subs’)) – Allows modification of the display code for the label shown next to the check box for subscribing to a post when creating or replying to a topic. The default label is “Subscribe to this topic”.
      • Example of Usage

Change text shown next to check box to “Email me with any new posts on this topic”.

add_filter('sph_subs_subscribe_label', 'change_subs_text');

function change_subs_text($msg) {
$msg = 'Email me with any new posts on this topic';
return $msg;
}
    • apply_filters(‘sph_subs_unsubscribe_label’, __(‘Unsubscribe from this topic’, ‘sp-subs’)) – Allows modification of the display code for the label shown next to the check box for unsubscribing to a post when creating or replying to a topic. The default label is “Unsubscribe to this topic”.
      • Example of Usage

Change text shown next to check box to “Do Not email me with any new posts on this topic”.

add_filter('sph_subs_unsubscribe_label', 'change_unsubs_text');

function change_unsubs_text($msg) {
$msg = 'Do Not email me with any new posts on this topic';
return $msg;
}
  • apply_filters(‘sph_subscriptions_forum_list’, sp_get_activity_value(SPACTIVITY_SUBSFORUM, $forum[0]->forum_id), $newpost) – Allows modification of the forum subscription new post data for the subscription email.
  • apply_filters(‘sph_subscriptions_topic_list’, sp_get_activity_value(SPACTIVITY_SUBSTOPIC, $topic[0]->topic_id), $newpost) – Allows modification of the topic subscription new post data for the subscription email.
  • apply_filters(‘sph_subscriptions_combined_list’, $users, $newpost) – Allows modification of the combined list of forum and topic subscription new post data.
  • apply_filters(‘sph_subs_post_content’, $post_content, $newpost) – Allows modification to the content of the subscription email’s topic content just prior to being output/returned. Default is to include the complete post text in the email. This filter is available in plugin versions 1.1.7 and above.
      • Example of Usage

    Add filter to remove all topic post content.

    add_filter('sph_subs_post_content', 'filter_subs_content',10,2);
    
    function filter_subs_content($post_content, $newpost) {
    $post_content= '';
    return $post_content;
    }

    Add filter to truncate topic post content with additional text to say they can read the complete post in the forum. Note: If post content is not empty (blank) the text “Post:” is automatically added before the topic content is displayed.

    add_filter('sph_subs_post_content', 'filter_subs_content',10,2);
    
    function filter_subs_content($post_content, $newpost) {
    if (strlen($post_content) > 100) $post_content = substr($post_content, 0, 100).'- Read complete post in the forum';
    return $post_content;
    }
  • apply_filters(‘sph_subscriptions_notification’, $msg, $newpost) – Allows modification to the content of the subscription email just prior to being output/returned. $newpost will contain the email content text. This lets plugins hook into the email.
  • apply_filters(‘sph_subscriptions_notify_self’, false, $newpost[‘userid’]) – Allows option to notify self.
  • apply_filters(‘sph_subscriptions_email_to’, $email, $newpost, $user) – Allows modification to the user email address where the notification will be sent just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_notification_email’, $msg, $newpost, $user, ‘sub’) – Allows modification to the content of the subscription email just prior to being output/returned. This lets plugins hook into the email by individual user.
  • apply_filters(‘sph_subscriptions_email_replyto’, ”, $newpost) – Allows modification to the content of the subscription email just prior to being output/returned. The second argument can be changed to contain different email ‘reply to’.
  • apply_filters(‘sph_subscriptions_email_subject’, __(‘Forum Post’, ‘sp-subs’).’ – ‘.get_option(‘blogname’).’: [‘.$newpost[‘topicname’].’]’, $newpost, $user) – Allows modification to the subscription email subject just prior to being output/returned. The default email subject is the Blog’s name and the topic name.
  • apply_filters(‘sph_subs_group_status_icon’, $out) – Allows modification to icon displayed just prior to being output/returned. Used twice in the file once for the group status icon and once for the subscription forum status icon. Without modification the icon output/returned is either from file sp_SubscriptionsUnsubscribeForum.png or sp_SubscriptionsSubscribeForum.png.

In file sp-subscriptions-digest.php, these can modify the contents of the Subscription Digest email.

  • apply_filters(‘sph_subscriptions_digest_notify_self’, false, $newpost[‘userid’]) – Allows option to notify self.
  • apply_filters(‘sph_subscriptions_digest_list’, $users) – Allows modification of the digest content for a topic just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_header’, $msg, $id) – Allows modification of the digest header just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry_forum’, stripslashes($topic[‘forum’]) – Allows modification of the forum entry for the post in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry_topic’, stripslashes($topic[‘topic’]), $topic) – Allows modification of the topic entry for the post in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry_url’, urldecode($topic[‘permalink’]), $topic) – Allows modification of the URL entry for the post in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry_divider’, ‘——————————————————————————–‘, $topic) – Allows modification of the divider between entries in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry_content’, $post_content, $topic) – Allows modification of the content entry for the post in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_entry’, $thismsg, $topic, $id, $usedtopics[$id][$topic[‘topicid’]]) – Allows modification of the digest entry for the post in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_footer’, $footer, $id) – Allows modification of the footer in the digest just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_email_to’, $email, $id, $topic) – Allows modification to the user digest email address where the notification will be sent just prior to being output/returned.
  • apply_filters(‘sph_subscriptions_digest_email’, $msg, $id, $topic) – Allows modification to the content of the subscription digest email just prior to being output/returned. This lets plugins hook into the email by individual user.
  • apply_filters(‘sph_subscriptions_digest_email_replyto’, ”, $id, $topic) – Allows modification to the content of the subscription digest email just prior to being output/returned. The second argument can be changed to contain different email ‘reply to’.
  • apply_filters(‘sph_subscriptions_digest_email_subject’, get_option(‘blogname’).’: ‘.__(‘Subscription Digest’, ‘sp-subs’), $id, $topic) – Allows modification to the subscription email subject just prior to being output/returned. The default email subject is the Blog’s name and ‘Subscription Digest’.

Plugin and Template Tag Changelog

Since Simple:Press version 5.0.

Codex page sync’d to code version 5.5.3 and plugin version 1.4.7.



Individual Template Tags


 

sp_SubscriptionsReviewButton

Description

sp_SubscriptionsReviewButton() – This template creates a subscription review click-able icon that shows any new posts a member may be subscribed to and allows the member to access a list of his subscribed topics. This template tag only works on the forum page.

Usage

sp_SubscriptionsReviewButton($args=”, $Label=”, $tooltip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spSubscriptionsReviewButton’
‘tagClass’ => ‘spSubscriptionsReviewButton’
‘labelClass’ => ‘spInRowLabel’
‘iconClass’ => ‘spIcon’
‘icon’ => ‘sp_SubscriptionsReviewButton.png’
‘first’ => 0
‘popup’ => 1
‘linkId’ => ‘spSubscriptionsLink’
‘mobileMenu’ => 0

‘tagId’: CSS ID for Div.
‘tagClass’: CSS Class for Div.
‘labelClass’: CSS Class for the label.
‘iconClass’: CSS Class for the icon.
‘icon’: Filename of the file to display for the icon.
‘first’: Flag to indicate whether to add a “first post” column along with the normal “last post” column in the search results or not. One (1) is true and causes a “first post” column to be added to the output. Zero (0) is false and results in only the normal “last post” column being output.
‘popup’: Flag to indicate whether to show the list of subscribed topics in popup or on the same page. A one (1) will show the list in a popup window. A zero (0) will show the list on the same page.
‘linkId’: CSS ID for the link to the user’s list of subscribed topics.
‘mobileMenu’: Flag to indicate whether to compile the target into the mobile action list for mobile device display or keep it as a separate button/link for desktop display. One (1) is true and the target is compiled into the mobile action list. Zero (0) is false and it is left as a separate button/link for desktop display.

$label – Text shown as the label of the icon.
Type:
(string) (optional)
Default:
None

$toolTip – Text displayed when the cursor hovers over the icon.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag functions requires the usage of the sp-subscriptions-review-button-tag.php file located in the plugin’s template-tag folder. Included in the file is a description of it’s usage and options.

This template tag only works on the forum page.

In standard supplied Simple:Press themes this is used in the header (spHead.php) files and is set up as a conditional in case the plugin is not present.

Examples

If the ‘sp_SubscriptionsReviewButton’ function exists, display the Subscription review button with the label “Subscribed” and “Review subscribed topics” shown when the cursor hovers over the button.

if (function_exists('sp_SubscriptionsReviewButton')) sp_SubscriptionsReviewButton('tagClass=spButton spRight', __sp('Subscribed:'), __sp('Review subscribed topics'));

 

Actions and Hooks Used in the sp_SubscriptionsReviewButton Template Tag

  • apply_filters(‘sph_SubscriptionsReviewButton_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_SubscriptionsReviewButton’, $out) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_SubscriptionsSubscribeButton

Description

This template creates a button for subscribing or unsubscribing to Topics.

Usage

sp_SubscriptionsSubscribeButtonTag($args=”, $subscribeLabel=”, $unsubscribeLabel=”, $subscribeToolTip=”, $unsubscribeToolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Defaults:
‘tagClass’ => ‘spSubscriptionsSubscribeButton’
‘tagId’ => ‘spSubscriptionsSubscribeButton’
‘labelClass’ => ‘spInRowLabel’
‘iconClass’ => ‘spIcon’
‘subscribeIcon’ => ‘sp_SubscriptionsSubscribeButton.png’
‘unsubscribeIcon’ => ‘sp_SubscriptionsUnsubscribeButton.png’
‘mobileMenu’ => 0

‘tagClass’: CSS Class for the Div.
‘tagId’: Id for the Div.
‘labelClass’: CSS Class for the label.
‘iconClass’: CSS Class for the icon
‘subscribeIcon’: Filename of the file to use for the Subscribe button icon.
‘unsubscribeIcon’: Filename of the file to use for the Unsubscribe button icon.
‘mobileMenu’: Flag to indicate whether to compile the target into the mobile action list for mobile device display or keep it as a separate button/link for desktop display. One (1) is true and the target is compiled into the mobile action list. Zero (0) is false and it is left as a separate button/link for desktop display.

$subscribeLabel – Label to display on the Subscribe icon.
Type:
(string) (optional)
Default:
None
$unsubscribeLabel – Label to display on the Unsubscribe icon.
Type:
(string) (optional)
Default:
None
$subscribeToolTip – Text displayed when the cursor hovers over the Subscribe icon.
Type:
(string) (optional)
Default:
None
$unsubscribeToolTip – Text displayed when the cursor hovers over the Unsubscribe icon.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag functions requires the usage of  the sp-subscriptions-subscribe-button-tag.php file located in the plugin’s template-tag folder included in the file is a description of it’s usage and options. The template tag is provided in the spFoot.php file of templates.

Note: This tag will only show up when on a topic view forum page. It can’t be used elsewhere on the website.

Examples

sp_SubscriptionsSubscribeButton('tagClass=spButton spLeft', __sp('Subscribe'), __sp('Unsubscribe'), __sp('Subscribe to this topic'), __sp('Unsubscribe from this topic'));

 

Actions and Hooks Used in the sp_SubscriptionsSubscribeButton Template Tag

  • apply_filters(‘sph_SubscriptionsSubscribeButton_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_SubscriptionsSubscribeButton’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_SubscriptionsUnreadTopics

Description

sp_SubscriptionsUnreadTopics() – This is a template tag to display the number of unread subscribed topics.

Usage

sp_SubscriptionsUnreadTopicsTag($display=true);

Arguments

$display – Flag indicating whether or not to display or return the unread count data. One (1) is true and default text is output/displayed with the unread count data. Zero (0) is false resulting in the default text and the new unread count not being displayed, but the unread count being returned to the caller. Nothing is displayed and 0 returned for guests.
Type:
(string) (optional)
Default:
True = 1

Special Notes

This template tag functions requires the usage of the sp-subscriptions-topics-tags.php file located in the plugin’s template-tag folder. Included in the file is a description of it’s usage and options. It is not currently provided in any themes. If it is to be used, have it conditionally displayed so the website will continue to function if the Subscription plugin is deactivated.

Examples

If using the Simple:Press Unified theme, in the forum header conditionally display the default text “You have ‘$count’ unread subscribed topics.” where ‘$count’ is replaced by the logged in user’s number of unread subscribed topics. A portion of the original content of the Unified theme’s spHeader.php file is shown immediately below:

	sp_MemberButton('tagClass=spButton spRight', __sp('Members'), __sp('View the members list'));
				
		sp_InsertBreak('direction=right');				

		sp_LastVisitLabel('tagClass=spLabelSmall spRight', __sp('Last visited %LASTVISIT%'));

The file is modified with “if (function_exists(‘sp_SubscriptionsUnreadTopics’)) sp_SubscriptionsUnreadTopics($display=true);” in the excerpt shown immediately below to add the default text and to show the logged in user’s number of unread subscriptions.

	sp_MemberButton('tagClass=spButton spRight', __sp('Members'), __sp('View the members list'));
				
		sp_InsertBreak('direction=right');
		if (function_exists('sp_SubscriptionsUnreadTopics')) sp_SubscriptionsUnreadTopics($display=true);				

		sp_LastVisitLabel('tagClass=spLabelSmall spRight', __sp('Last visited %LASTVISIT%'));

 

Actions and Hooks Used in the sp_SubscriptionsUnreadTopics Template Tag

  • None

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_SubscriptionsSubscribeForumButton

Description

sp_SubscriptionsSubscribeForumButton() – This template tag allows creation of buttons that users can click on to subscribe or unsubscribe to a forum.

Usage

sp_SubscriptionsSubscribeForumButton($args=”, $subscribeLabel=”, $unsubscribeLabel=”, $subscribeToolTip=”, $unsubscribeToolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Defaults:
‘tagClass’ => ‘spSubscriptionsSubscribeForumButton’
‘tagId’ => ‘spSubscriptionsSubscribeForumButton’
‘labelClass’ => ‘spInRowLabel’
‘iconClass’ => ‘spIcon’
‘subscribeIcon’ => ‘sp_SubscriptionsSubscribeForumButton.png’
‘unsubscribeIcon’ => ‘sp_SubscriptionsUnsubscribeForumButton.png’
‘mobileMenu’ => 0

‘tagClass’: CSS Class for the Div.
‘tagId’: CSS Id for the Div.
‘labelClass’: CSS Class for the label.
‘iconClass’: CSS Class for the icon
‘subscribeIcon’: Filename of the file to use for the Subscribe Forum button icon.
‘unsubscribeIcon’: Filename of the file to use for the Unsubscribe Forum button icon.
‘mobileMenu’: Flag to indicate whether to compile the target into the mobile action list for mobile device display or keep it as a separate button/link for desktop display. One (1) is true and the target is compiled into the mobile action list. Zero (0) is false and it is left as a separate button/link for desktop display.

$subscribeLabel – Label to display on the Subscribe Forum icon.
Type:
(string) (optional)
Default:
None
$unsubscribeLabel – Label to display on the Unsubscribe Forum icon.
Type:
(string) (optional)
Default:
None
$subscribeToolTip – Text displayed when the cursor hovers over the Subscribe Forum icon.
Type:
(string) (optional)
Default:
None
$unsubscribeToolTip – Text displayed when the cursor hovers over the Unsubscribe Forum icon.
Type:
(string) (optional)
Default:
None

Special Notes

For Subscription plugin Version: 1.2 and Simple:Press Versions: 5.2 and above.
This template tag allows creation of buttons that users can click on to subscribe or unsubscribe to a forum. It requires that the subscribe to forums option has been turned on in the Simple:Press Admin >Subscriptions settings. Not currently provided in themes.

Examples

An example of usage to display it as a  button (spButton) align it to the right side (spRight) with the test “Subscribe” or “UnSubscribe” displayed on the button. In addition to a tooltip popup displayed when hovered showing “Subscribe to this forum” or “Unsubscribe from this forum”   is:

sp_SubscriptionsSubscribeForumButton('tagClass=spSubscriptionsSubscribeForumButton spButton spRight', 'Subscribe', 'UnSubscribe','Subscribe to this forum', 'UnSubscribe from this forum');

 

Actions and Hooks Used in the sp_SubscriptionsSubscribeForumButton Template Tag

  • apply_filters(‘sph_SubscriptionsSubscribeForumButton_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_SubscriptionsSubscribeButton’, $out, $a) – Allows modification of the display code just prior to being output/returned. $out will contain the html display code.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


 

sp_ForumIndexSubscriptionIcon

Description

sp_ForumIndexSubscriptionIcon() – This template tag allows displaying a Forum Subscription Icon (In status icons area – standalone version)

Usage

sp_ForumIndexSubscriptionIcon($args=”, $subToolTip=”, $unSubToolTip=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Defaults:
‘tagId’ => ‘spForumIndexSubscriptionIcon%ID%’
‘tagClass’ => ‘spIcon’
‘subscribeIcon’ => ‘sp_SubscriptionsSubscribeForum.png’
‘unsubscribeIcon’ => ‘sp_SubscriptionsUnsubscribeForum.png’
‘echo’ => 1

‘tagId’: Id for the Div. %ID% is replaced by the forum ID.
‘tagClass’: CSS Class for the Div.
‘subscribeIcon’: Filename of the file to use for the Subscribe button icon.
‘unsubscribeIcon’: Filename of the file to use for the Unsubscribe button icon.
‘echo’: Flag to indicate whether to write out the generated html display code or just return the html display code. One (1) is true and causes the html display code to be written to the display. Zero (0) is false and causes the html display code to be returned instead of written out.

$subToolTip – Text displayed when the cursor hovers over the Subscribe icon.
Type:
(string) (optional)
Default:
None
$unsubToolTip – Text displayed when the cursor hovers over the Unsubscribe icon.
Type:
(string) (optional)
Default:
None

Special Notes

This template tag allows displaying a Forum Subscription Icon (In status icons area – standalone version). Its scope is the Forum sub loop. It is currently provided in the spGroupView.php file of the Unified theme.

Examples

If the function exists, conditionally display the Forum Subscription icon on the right with “Subscribe to this forum” shown when the cursor hovers over the “subscribe icon” and “Unsubscribe from this forum” shown when the cursor hovers over the “unsubscribe icon”.

if(function_exists('sp_ForumIndexSubscriptionIcon')) sp_ForumIndexSubscriptionIcon('tagClass=spIcon spRight', __sp('Subscribe to this forum'), __sp('Unsubscribe from this forum'));

 

Actions and Hooks Used in the sp_ForumIndexSubscriptionIcon Template Tag

  • apply_filters(‘sph_ForumIndexLockIcon_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.

Changelog

See Plugin and Template Tag Changelog for Template Tag changes and Codex page syncing to code versions.


More Topics In SimplePress: Plugins


Copyright © 2006-2019 Simple:Press. All Rights Reserved.