Simple:Press Documentation

Plugin: Watches

Plugin Description

Plugin: Watches – This Simple:Press plugin allow users to receive notice whenever they are on the forum of new posts to interesting topics they have selected. The Watches plugin does not send an email to users on new posts to watched topics.

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

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Watches” section in the “Available Plugins – Install Simple:Press Plugins” panel under the forum Admin menu path Forum > Plugins > Available Plugins. From this panel the Simple:Press plugin can be activated or deleted by the admin.
  • When properly installed, a new folder in the forum plugin folder named “watches” containing this plugin’s files.

Activating this plugin provides:

  • A change to the new “Watches” section in the “Available Plugins – Install Simple:Press Plugins” panel under the Admin menu path Forum > Plugins > Available Plugins so the plugin can be deactivated, or uninstalled.
    • There are no administrative options associated with this plugin.
    • The “Getting Started” link should be selected to view the pertinent information regarding the plugin.
  • For forum users with the “Can watch topics within a forum” permission:
    • In the “Add Topic” creation template a new “Watch this topic” check box in the “Options” section that the topic creator can select by clicking on to watch the topic. The check box is selected when it contains a green check mark.
    • In the “Add Reply” creation template a new “Watch this topic” check box in the “Options” section that the reply post creator can select by clicking on to watch the topic. The check box is selected when it contains a green check mark.
    • When displaying a topic not currently being watched by the user, a new “Watch” button that if clicked, results in that topic being watched by the user. The button is located at the very bottom of the topic below any reply posts.
    • When displaying a topic currently being watched by the user, a new “Stop Watching” button that if clicked, results in that topic no longer being watched by the user. The button is located at the very bottom of the topic below any reply posts.
    • In the header of the forum pages, a new “Watching” button linked to the new “Review watched topics” popup window where a forum user can view the list of topics that user is watching.
      • Within the “Watching” button there is an indicator of the number of watched topics that have new posts within them.
      • Arguments in the template tag that controls this button can be changed to display the list of topics on a regular page rather than on a popup.
    • A new “Review watched topics” popup window where a forum user can view the list of topics that user is watching.
      • The window can be accessed by clicking the new “Watching” button in the forum page header.
        • Arguments in the template tag that controls this button can be changed to display the list of topics on a regular page rather than on a popup.
      • A “New” button associated with a listed watched topic indicates how many new posts are in the watched topic.
    • A new “Watches” tab and “Manage Watches” sub-tab in their profile where the topics they are watching are listed and where the user can stop watching all or just individual topics.
      • Users can access their “Watches” tab by clicking the “Profile” button in the forum page header.
        • Hovering the cursor over the “Profile” button displays the message, “Edit your profile”.
  • A new entry “Watches (by Topic)” under the “Users” menu item in the Forum Admin menu that is linked to the new “Users – Topic Watches” Admin panel where the forum Admin can use filters to be shown various lists of topics being watched.
    • The new menu item is accessed from the Admin menu at Forum > Users.
  • A new “Users – Topics Watches” Admin panel where the forum Admin can use filters to be shown various lists of topics being watched.
    • The new Admin panel is accessed from the Admin menu at Forum > Users > Watches (by Topic).
  • A new Admin display panel “Manage Users – Watches by Topic” showing the watches information after the forum Admin has specified both the “watches” filtering desired and has clicked the “Show Watches” button on the “Users – Topic Watches” Admin panel.
    • If desired, all the watches for a given topic can be deleted on this panel by the forum Admin.
  • A new entry “Watches (by User)” under the “Users” menu item in the Forum Admin menu that is linked to the new “Users – User Watches” Admin panel where the forum Admin can view the various topics being watched by individual users.
    • The new menu item is accessed from the Admin menu at Forum > Users.
  • A new Admin display “Users – User Watches” showing the topics watched by individual users and where the forum Admin can delete all the watches for a given user.
    • The display is accessed from the Admin menu at Forum > Users > Watches (by User).
  • A new permission “Can watch topics within a forum” that must be enabled by the forum Admin in the permission sets for usergroups being allowed to watch topics.
    • A permission set is edited from the forum Admin menu at Forum > Permissions > Manage Permission Sets by clicking on the “Edit Permission” button associated with the permission set.

Plugin Requirements

Simple:Press version 5.5.7 and above is required.

The Simple:Press plugin must be installed and activated before it is operational.

  • As part of the installation, a “Watches” section is added to the “Available Plugins – Install Simple:Press Plugins” panel under the admin menu Forum > Plugins > Available Plugins. From this panel the plugin can be activated, deactivated, uninstalled or deleted using its “Activate/Delete” and “Deactivate/Uninstall” selections.
    • There are no options associated with this plugin.

There is one (1) new permission added to the permission sets due to this plugin that must be set up.

  • “Can watch topics within a forum”

The plugin has three (3) template tags with two (2) of them, ‘sp_WatchesReviewButton()’, and ‘sp_WatchesWatchButton()’ incorporated into standard supplied Simple:Press themes. Template tag ‘sp_WatchesUnreadTopics()’ is not incorporated.

  • If the location of the template tag in the themes as well as the argument and parameter values for the template tag are acceptable, nothing need be done.
  • If any item relating to the template tag is to be modified or if the other template tag is to be added to a theme, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases the template tag should be called conditionally, if (function_exists(‘ ‘)) so that if the plugin is deactivated or does not exist, the website will continue to operate.

Plugin Installation and Activation

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

  • Whatever method is used to add the Simple:Press plugin, the folder that should have been added to the forum plugin folder is named “watches“.
  • If using the “Simple:Press Upload Plugin – Upload a Simple:Press Plugin” panel at the forum Admin menu Forum > Plugins > Plugin Uploader, the folder to browse for after downloading it from the Simple:Press site is “watches.zip” before clicking the “Upload Now” button.

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 > Plugins > Available Plugins from the drop down forum Admin menu. On the “Available Plugins – Install Simple:Press Plugins” panel select the Watches plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall” with a “Get Started” Link.

  • The “Getting Started” link associated with the “Deactivate/Uninstall” selections should be selected to view the pertinent information regarding the plugin.

To deactivate the plugin, click on “Deactivate”. The “Deactivate/Uninstall” label changes to “Activate/Delete”.
To re-activated the plugin, click on on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall”.

Plugin Administrative Options

There are no administrative options required but the permission allowing forum users/members to use this feature must be enabled in the associated permission sets.

From the Forum Admin menu on the left of admin pages, select Forum > Permissions > Manage Permission Sets to see the permission sets available.

  • Assigning New Permissions
    • “Can watch topics within a forum” permission
    • Allowing users to watch topics in forums is controlled by their group permissions.
    • Each usergroup that is to have this ability must have the permission turned on.
    • This is accomplished from the Simple:Press Administration panel Admin menu by clicking/opening Forum > Permissions > Manage Permission Sets.
    • Select “Edit Permission” for the permission set to be updated to view the “Permissions – Manage Permissions” panel.
    • Under “General” click the check box next to “Can watch topics within a forum” to set/enable the permission. When enabled, the check box contains a green check mark.
    • Click “Update Permission” at the bottom of the page to have the selection saved.
    • At a later time clicking the check box when it has a green check mark removes the check mark and will remove the permission when followed by clicking “Update Permission” to save the revised selection.
    • Repeat these steps on each usergroup to have this permission.

To be complete for multilingual forums, the language translation files for this plugin should be installed or downloaded/properly placed in the appropriate forum-language folder for SP plugins using one of the procedures below in the “Plugin Language Translation” section of this page.

Plugin Language Translation

A plugin may not have language translation files, but in general each Simple:Press plugin has its own language translation files each with multiple pages for translating the forum plugin’s message strings.

Forum Plugin translation files are to reside in a unique forum folder location as defined by the “Simple:Press Plugin Language Files” entry on the “Integration – Storage Locations” forum Admin panel available through the forum Admin menu at Forum > Integration > Storage Locations.

  • The default location for forum plugin translation files is the folder “…/wp-content/sp-resources/forum-language/sp-plugins”.

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

WARNING: On the Localization page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.

More information is available regarding translation files at Simple:Press Translations. which is the repository for Simple:Press language translation files. 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.

This plugin’s available language translation files with translation statistics, and message translations can be viewed at Watches within the repository for Simple:Press language translation files.

  • Installing this Simple:Press Plugin’s Language Translation “.mo” files
    The plugin’s language translations files for each language can be correctly located in two ways.

    • Using the Admin Word:Press “Site Language” and Simple:Press “Language Translation” Features
      WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
        • Under the “Language Translation Selection Sequences” heading, the “Coordinated Language Translation File Download Using the Simple:Press ‘Language Translation’ Selection” section, follow the instructions at “Adding its Translation File(s) After Downloading/Activating a Simple:Press Theme or Simple:Press Plugin”.
          • Follow the instructions to select the “Site Language” and then get to the admin page with the “Integration – Language Translations” section where there should be an entry for “Watches” along with an “Install” button.
          • Click on the “Install” button for this plugin to install the language translation file for the current “Site Language” language.
            • Note: If the message “No Translation Project Exists” is displayed rather than the “Install” button, a translation file for that language could not be found in GlotPress at this time. Consider posting in the Simple:Press forum if it is felt there needs to be one added.
          • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
          • As called out in the section, continue to change the “Site Language” language and repeat the process until all desired translation files for this plugin have been installed.

       

    • Manually Finding and Storing Simple:Press Plugin’s Language Translation ‘mo’ files
    • WARNING: On the Localization codex page, the Language Translation “.mo” Files Overview should be reviewed and well understood for naming convention and language translation file placement.
    • After reviewing the material discussed under the “Language Translation Selection Sequences” heading, the “Manual Installation of Simple:Press Language Translation Files section, follow the steps outlined at “Finding and Storing ANY Simple:Press Plugin’s Language Translation ‘mo’ files”.
    • Each time through the process at the step, “Scroll down the list and click on the name of the plugin whose language files are being sought to see the translation file Version Number available”, substitute “Watches” for the phrase “the name of the plugin whose language files are being sought”.
    • Be sure to verify the locale (filename) for the “.mo” file matches the language code for the language as referenced in the “Warning” above. If it does not, change it to match.
    • Repeat the steps for each language it is desired to have a translation file (french, spanish, etc.) for the plugin on the website.

Plugin Usage

Forum Admins can view a list of the forum topics being watched by users or a the list of users with the topics they are watching.

  • Viewing and/or Deleting Watches by Topic
  • In the Admin menu, navigate to Forum > Users and click the “Watches (by Topic)” sub-menu entry to display the “User – Topic Watches” Admin panel.
  • In the “User – Topic Watches” Admin panel’s “Select filters” section under “Filter by all, groups, or forums”, select the check box to the left of filter desired: “All”, “Groups”, or “Forums”.
    • The check box is selected if it contains a green check mark.
  • If “Groups” is selected, in the “Select Groups” selection window that appears under the list of check boxes click on the name(s) of the forum group(s) whose watched topics are to be viewed .
    • A group is selected if it is highlighted.
    • Additional groups can be selected by holding down the “shift” or “Control/(Ctrl)” key on the keyboard while clicking on the group name.
  • If “Forums” is selected, in the “Select forum” selection window that appears under the list of check boxes click on the name(s) of the forum(s) whose watched topics are to be viewed.
    • A forum is selected if it is highlighted.
    • Additional forums can be selected by holding down the “shift” or “Control/(Ctrl)” key on the keyboard while clicking on the forum name.
  • Click on the “Show Watches” button at the bottom of the panel to view the selected watched topics in the “Manage Users – Watches by Topic” Admin panel.
  • If desired, the forum Admin can delete all the watches of a topic listed by clicking on the “garbage can” icon under the “Manage” column associated with the topic.
  • Viewing, Searching and/or Deleting Watches by User
  • In the Admin menu, navigate to Forum > Users and click the “Watches (by User)” sub-menu entry to display the “User – User Watches” Admin panel.
  • In the “User – User Watches” Admin panel the forum users with watches are listed along with all the topics they are watching.
  • If desired, the forum Admin can search for the watches list of a single forum user by putting the users “Display Name” in the text input box to the left of the “Search” button and clicking the “Search” button.
  • If desired, the forum Admin can delete all the watches of a user listed by clicking on the “garbage can” icon under the “Manage” column associated with the user.

Forum users with the permission “Can watch topics with a forum” can select topics to watch, be notified when watched topics have new posts in them, browse the topics they are watching, review the list of topics they are watching, and select topics to stop watching.

Note:
Only users that are logged in can watch topics.
  • Watching a Topic When Starting a Topic
  • Navigate to a forum and click the “Add Topic” button to display the “Add Topic” form.
  • Sometime during the development of the post, scroll down to the “Options” section of the form.
  • Click in the check box to the left of “Watch this topic” to select this topic to be watched.
    • The check box is selected if it contains a green check mark.
  • After completing the sections of the “Add Topic” form, click the “Submit Topic” button at the very bottom of the form to submit the topic.
  • Watching a Topic When Replying to a Topic
  • Navigate to a topic within a forum and click the “Add Reply” button to display the “Add Reply” form.
  • Sometime during the development of the post, scroll down to the “Options” section of the form.
  • Click in the check box to the left of “Watch this topic” to select this topic to be watched.
    • The check box is selected if it contains a green check mark.
  • After completing the sections of the “Add Reply” form, click the “Submit Reply” button at the very bottom of the form to submit the topic.
  • Watching a Topic When Viewing a Topic
  • Navigate to a topic not being watched within a forum and scroll to the bottom of the topic below any possible reply posts where the “Watch” button is displayed.
  • Click in the “Watch” button to select this topic to be watched.
    • The “Topic Added” message is displayed at the top of the screen.
  • Viewing the List of Watched Topics and Selecting a Watched Topic to View
  • Click on the “Watching” button in the header of the forum page to display the “Review watched topics” popup screen (or regular page if so configured) with the list of all topics being watched.
    • Viewing the Watched Topic
    • Click on the title of the topic to be viewed to have the watched topic displayed.
  • Notification of New Posts in Watched Topics and Viewing New Posts
  • Within the “Watching” button in the forum page header is the indicator of new posts to watched topics.
  • When there are new unread posts, a number (1, 2, etc.) is displayed to the right of “Watching:” in the “Watching” button to indicate the number of watched topics with new posts.
  • Click on the “Watching” button in the header of the forum page to display the “Review watched topics” popup screen (or regular page if so configured) with the list of all topics being watched.
    • Viewing the New Posts Within Watched Topics
    • Watched topics with new posts have a “New” button to the right of the topic title on the “Review watched topics” screen instead of the “End” button, and within the “New” button a number (1, 2, etc.) indicating the number of new posts within the topic.
    • Click on the “New” button associated with the watched topic to see the new post or the first new post if there are multiple new posts to the watched topic.
  • Start the above process over by clicking on the “Watching” button in the forum page header to view new posts in other watched topics.
  • Stop Watching a Topic or All Topics from the List of Watched Topics
  • Click on the “Watching” button in the header of the forum page to display the “Review watched topics” popup screen (or regular page if so configured) with the list of all topics being watched.
    • Stop Watching a Single Topic
    • Click on the “End” (or “Stop Watching) button to the right of the title of the watched topic to no longer be watched.
      • The section for the topic no longer being watched is removed from the “Review watched topics” screen.
    • Stop Watching All Topics
    • Click on the “REMOVE ALL WATCHES” button near the top of the “Review watched topics” screen.
      • All the topics are removed from the “Review watched topics” popup screen.
  • Stop Watching a Topic When Viewing That Topic
  • Navigate to a topic that is being watched within a forum.
  • Scroll to the bottom of the topic below any possible reply posts where the “Stop Watching” button is displayed.
  • Click in the “Stop Watching” button to stop watching this topic.
    • The “Topic Watch Removed” message is displayed at the top of the screen.
  • Stop Watching a Topic When Replying to That Topic
  • Navigate to a topic that is being watched within a forum and click the “Add Reply” button to display the “Add Reply” form.
  • Sometime during the development of the post, scroll down to the “Options” section of the form.
  • Click in the check box to the left of “Stop watching this topic” to select this topic to no longer be watched.
    • The check box is selected if it contains a green check mark.
  • After completing the sections of the “Add Reply” form, click the “Submit Reply” button at the very bottom of the form to submit the topic.
  • Stop Watching a Topic, Multiple Topics or All Topics from the “Manage Watches” Panel in a User’s Profile
  • Click on the “Profile” button in the forum page header for the logged in user to go to his/her profile.
  • Click on the “Watches” tab and “Manage Watches” sub-tab to display the “Manage Watches” panel with a list of all the watched topics of the logged in user.
    • Stop Watching a Topic or Multiple Topics
    • Click in the check box to the left of the topic title for each/every topic that is to no longer be watched.
      • The topic is selected to no longer be watched if its check box contains a green check mark.
    • Click on the “STOP WATCHING CHECKED” button at the bottom of the panel to stop watching the checked topics.
      • The selected watched topics are removed from the list and the “Watches updated” message is displayed at the top of the screen.
    • Stop Watching All Topics
    • Click on the “STOP WATCHING All” button at the bottom of the panel to stop watching all topics.
      • All the watched topics are removed from the list and the “All topic watches stopped” message is displayed at the top of the screen.

Plugin Special Notes

Watching topics is not the same as Subscribing to a topic. The Subscription plugin information is available at Subscriptions.

 

Template Tags Used in the Plugin

The plugin has three (3) template tags with two (2) of them, ‘sp_WatchesReviewButton()’, and ‘sp_WatchesWatchButton()’ incorporated into standard supplied Simple:Press themes. Template tag ‘sp_WatchesUnreadTopics()’ is not incorporated.

  • If the location of the template tag in the themes as well as the argument and parameter values for the template tag are acceptable, nothing need be done.
  • If any item relating to the template tag is to be modified or if the other template tag is to be added to a theme, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin.
  • In all cases the template tag should be called conditionally, if (function_exists(‘ ‘)) so that if the plugin is deactivated or does not exist, the website will continue to operate.

The Template Tags can be viewed by selecting their 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-watches-components.php’ within the functions used to add the watch or stop watching labels to “Options’ sections of the “Add Reply” and “Add Topic” post creation forms:

  • apply_filters(‘sph_watches_watch_label’, __(‘Watch this topic’, ‘sp-watches’)) – Allows modification of the display code for the label, “Watch this topic” in the “Options” section of the “Add Reply” post form just prior to being output/returned.
  • apply_filters(‘sph_watches_end_watch_label’, __(‘Stop watching this topic’, ‘sp-watches’)) – Allows modification of the display code for the label, “Stop watching this topic” in the “Options” section of the “Add Reply” post form just prior to being output/returned.
  • apply_filters(‘sph_watches_watch_label’, __(‘Watch this topic’, ‘sp-watches’)) – Allows modification of the display code for the label, “Watch this topic” in the “Options” section of the “Add Topic” post form just prior to being output/returned.

In file ‘sp-watches-manage-form.php’ used to display the “Manage Watches” panel under the “Watches” tab in a user’s profile:

  • apply_filters(‘sph_profile_watches_manage’, $msg) – Allows modification of the fields in the message, “Watches are topics that you have chosen to keep an eye on. You will not receive any notifications on new posts.” or add fields to the display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileManageWatchesFormTop’, $out, $userid) – Allows modification of top of the Manage Watches form display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormTop’, $out, $userid, $thisSlug) – Allows modification of the top of the overall form display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileManageWatchesForm’, $out, $userid) – Allows modification of the fields in the message, “You are not currently watching any topics” or add fields to the display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileManageWatchesFormBottom’, $out, $userid) – Allows modification of bottom of the Manage Watches form display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileFormBottom’, $out, $userid, $thisSlug) – Allows modification of the bottom of the overall form display code just prior to being output/returned.
  • apply_filters(‘sph_ProfileManageWatchesForm’, $out, $userid) – Allows modification of the total Manage Watches form display code just prior to being output/returned.

Plugin and Template Tag Changelog

Since Simple:Press version 5.5.0.

Codex page sync’d to code version 5.6.1 and plugin version 1.5.11.



Individual Template Tags


 

sp_WatchesReviewButton

Description

sp_WatchesReviewButton() – This template creates and displays a watches review button that shows the number of watched topics with new unread posts a member is watching and contains a link that allows the member to access the list of his/her watched topics.

Note: If the logged in user is displaying a watched topic when that topic has a new post added to it, the logged in user will NOT see an increase in the number of topics with new unread posts shown in this button.Because the user will immediately see the new post appended to the topic, the new post is not considered “unread” so no increase in the number of topics with “unread’ posts will occur.

Usage

sp_WatchesReviewButton($args =”, $label=”, $toolTip=”);

Arguments

Note: If the value of any of this function’s arguments/parameters or the placement of this function in standard supplied Simple:Press theme pages is to be changed, it is highly recommended that a Child Theme or a Custom Theme be developed to accept the changes.

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

tagId‘: CSS ID for the Div.
tagClass‘: CSS Class for the Div.
labelClass‘: CSS Class for the label being displayed.
iconClass‘: CSS Class for the icon being displayed.
icon‘: Filename of the file containing the icon being displayed.
first‘: Flag to indicate whether to display summary information from the first post in the watched topic in addition to the normal summary information from the last post in the topic. A one (1) is true and the summary information from the first and last post in the topic are displayed. A zero (0) is false and only the last post summary information is displayed.

Note: The effect of ‘first’ = 1 (one / true) can only be seen if a modification to the active theme’s ‘spListView.php‘ file is made to add a call to the ‘sp_ListFirstPost()‘ function if the function call is not already in the file. See the Special Notes section of this template tag for more information.

popup‘: Flag to indicate how to display watches. A one (1) is true and the watched topics are displayed in a popup. A zero (0) is false and the watched topics are displayed in a normal forum page.
linkId‘: CSS ID for the link.
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. A one (1) is true and the target is compiled into the mobile action list. A zero (0) is false and it is left as a separate button/link for desktop display.

$label – Text shown on next to Watching icon.
Type:
(string) (optional)
Default:
None

$toolTip – Text shown when hovering over Watching icon.
Type:
(string) (optional)
Default:
None

Special Notes

In standard supplied Simple:Press themes this function is included in the header ‘spHead.php’ file.

The exception is

  • the reboot theme where the template tag is not included in the ‘spHead.php’ file, but is included in the ‘spHeadDesktop.php’ and ‘spHeadMobile.php’ files.

The function is called conditionally, if (function_exists(‘ ‘)), so that if the plugin is deactivated or does not exist, the website will continue to operate.

If the template tag is to be modified, it is suggested a Custom or Child theme be made to accept the modified template tag. Please see discussion at Template Tags Used in the Plugin.

The function requires the use of file ‘sp-watches-review-button-tag.php’ located in the plugin’s “template-tag” folder.

In the standard supplied Simple:Press themes, the default items displayed for each watched topic on the ‘Review watched topics’ popup or page are:

  • the Forum Title where the post resides.
  • the Topic Title.
  • information about the last post in the topic consisting of:
    • the message “Last Post”.
    • the username of the author of the post.
    • an indicator of how long ago the post was made.

Setting ‘first’ equal to 1 (one / true) makes it possible to add:

  • information regarding the first (1st) post in the watched topic.
    • a message similar to “First Post”.
    • the username of the author of the post.
    • an indicator of how long ago the post was made.
Note: The effect of ‘first’ = 1 (true) can only be seen if a modification to the theme’s ‘spListView.php‘ file is made to add the ‘sp_ListFirstPost()‘ function if the function call is not already in the file. See Example 2 below for details.

Examples

1. Using the defaults but with ‘tagClass’ of “spButton spRight” display the watches button with label of “Watching:” and the message “Review watched topics” displayed when hovering the cursor over the button. Have the function called conditionally.

if (function_exists('sp_WatchesReviewButton')) sp_WatchesReviewButton('tagClass=spButton spRight', __sp('Watching:'), __sp('Review watched topics'));

2). Using the child theme based on the “Default” theme, display the standard watches icon and label in the forum page header, but in addition add summary information regarding the first (1st) post with label of “First Post” in the watched topics shown in the “Review watched topics” popup.

A. If not already done, download the Default Child Framework and set it up as discussed in the Creating a Child Theme page. If not already done, copy the Default theme’s ‘spHead.php’ file over to the child theme and modify its “sp_WatchesReviewButton()’ call to add “&first=1” as shown below and save.

if (function_exists('sp_WatchesReviewButton')) sp_WatchesReviewButton('tagClass=spButton spRight&first=1', __sp('Watching:'), __sp('Review watched topics'));

B. If not already done, copy the Default theme’s ‘spListView.php’ file from the ‘template’ folder over to the child theme, and then in the file’s ‘list’ section find where the topic and last post information are being set up as shown immediately below.

sp_ListTopicName('', __sp('Browse the thread %NAME%'));
sp_ListLastPost('iconClass=spIcon spLeft&height=0px', __sp('Last Post'));

Modify it to add the call to ‘spListFirstPost()’ as shown below and save.

sp_ListTopicName('', __sp('Browse the thread %NAME%'));
sp_ListFirstPost('iconClass=spIcon spLeft&height=0px', __sp('First Post'));
sp_ListLastPost('iconClass=spIcon spLeft&height=0px', __sp('Last Post'));

 

Actions and Hooks Used in the sp_WatchesReviewButton Template Tag

  • apply_filters(‘sph_WatchesReviewButton_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_WatchesReviewButton’, $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_WatchesWatchButton

Description

sp_WatchesWatchButton() – This template creates and displays a button for watching or stop watching of topics.

Usage

sp_WatchesWatchButton($args=”, $watchLabel=”, $stopWatchLabel=”, $watchToolTip=”, $stopWatchToolTip=”);

Arguments

Note: If the value of any of this function’s arguments/parameters or the placement of this function in standard supplied Simple:Press theme pages is to be changed, it is highly recommended that a Child Theme or a Custom Theme be developed to accept the changes.

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagClass’ => ‘spWatchesWatchButton’
‘tagID’ => ‘spWatchesWatchButton’
‘labelClass’ => ‘spInRowLabel’
‘iconClass’ => ‘spIcon’
‘watchIcon’ => ‘sp_WatchesWatchButton.png’
‘stopWatchIcon’ => ‘sp_WatchesStopWatchButton.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.
watchIcon‘: Filename of the file containing the “Watch Topic” icon. This icon is displayed when the topic being displayed is not currently being watched by the user.
stopWatchIcon‘: Filename of the file containing the “Stop Watching Topic” icon. This icon is displayed when the topic being displayed is currently being watched by the user.
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.

$watchLabel – The label to show with the watch topic icon.
Type:
(string) (optional)
Default:
None

$stopWatchLabel – The label to show with the stop watching topic icon.
Type:
(string) (optional)
Default:
None

$watchToolTip – Message to display when the cursor is hovered over the watch topic icon.
Type:
(string) (optional)
Default:
None

$watchLabel – Message to display when the cursor is hovered over the stop watching topic icon.
Type:
(string) (optional)
Default:
None

Special Notes

In the standard supplied Simple:Press themes, this template tag is included in the footer (‘spFoot.php’) file.

The exception is

  • the reboot theme where the template tag is not included in the ‘spFoot.php’ file, but is included in the ‘spTopicViewDesktop.php’ and ‘spTopicViewMobile.php’ files.

The function is called conditionally, if (function_exists(‘ ‘)), so that if the plugin is deactivated or does not exist, the website will continue to operate.

If the template tag is to be modified, it is suggested a Custom or Child theme be made to accept the modified template tag. Please see discussion at Template Tags Used in the Plugin.

The function requires the use of file ‘sp-watches-watch-button-tag.php’ located in the plugin’s “template-tag” folder.

Examples

Using the defaults with “tagClass” of “spButton spLeft” display the watches watch button. When displaying the watch topic icon, display the label “Watch” and display the message “Watch this topic” when hovering the cursor over the icon. When displaying the stop watching topic icon, display the label “Stop Watching” and display the message “Stop watching this topic” when hovering the cursor over the icon. Have the function called conditionally.

		if (function_exists('sp_WatchesWatchButton')) sp_WatchesWatchButton('tagClass=spButton spLeft', __sp('Watch'), __sp('Stop Watching'), __sp('Watch this topic'), __sp('Stop watching this topic'));

 

Actions and Hooks Used in the sp_WatchesWatchButton Template Tag

  • apply_filters(‘sph_WatchesWatchButton_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_WatchesWatch’, $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_WatchesUnreadTopics

Description

sp_WatchesUnreadTopics() – This template displays the number of unread watched topics along with default text.

Note: If the logged in user is displaying a watched topic when that topic has a new post added to it, the logged in user will NOT see an increase in the number of topics with new unread posts shown in this button.Because the user will immediately see the new post appended to the topic, the new post is not considered “unread” so no increase in the number of topics with “unread’ posts will occur.

Usage

sp_WatchesUnreadTopics($display=true);

Arguments

Note: If this function is to be added into a standard supplied Simple:Press theme page, it is highly recommended that a Child Theme or a Custom Theme be developed to accept the changes.

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘display’ => ‘true’

display‘: Indicator of whether or not to display the number of watched topics with unread posts. If “true”, the number of watched topics having unread posts is displayed with the default text, “You have ‘X’ read watched topics.”, where ‘X’ is the number of topics with unread posts. If “false”, the default text is suppressed. If suppressed, the watched topics with new posts count is returned to the caller. Nothing is displayed and 0 is returned for guests.

Special Notes

This template tag is NOT included in standard supplied Simple:Press theme files.

If the template tag is to be added to a theme, it is suggested a Custom or Child theme be made to accept the template tag. Please see discussion at Template Tags Used in the Plugin.

If it is used, the function should be called conditionally, if (function_exists(‘ ‘)), so that if the plugin is deactivated or does not exist, the website will continue to operate.

The function requires the use of file ‘sp-watches-topics-tags.php’ located in the plugin’s “template-tag” folder.

Examples

Using the child theme based on the “Default” theme conditionally call this function in the header of forum pages using default values if not otherwise specified to display the default message, “You have ‘X’ unread watched topics to review.” Separate this function from the previous function by placing a ‘sp_InsertBreak()’ function before this function.

A. If not already done, download the Default Child Framework and set it up as discussed in the Creating a Child Theme page. If not already done, copy the Default theme’s ‘spHead.php’ file over to the child theme. In the ‘spHead.php’ file near the bottom of the ‘userInfo’ section after the ‘sp_MemberButton()” function call, add the ‘sp_InsertBreak()’ call and the conditionally called ‘sp_WatchesUnreadTopics()’ as shown below and save.

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

 

Actions and Hooks Used in the sp_WatchesUnreadTopics Template Tag

  • apply_filters(‘sph_WatchesUnreadTopics_args’, $a) – Allows modification of the arguments to the template tag. $a contains the parsed arguments.
  • apply_filters(‘sph_WatchesUnreadTopics’, $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.


More Topics In SimplePress: Plugins


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