Simple:Press Documentation

Plugin: Keywords

Plugin Description

Plugin: Keywords – This Simple:Press plugin notifies Forum Users of new posts that contain keywords of interest that they have selected.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Keywords” 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 “keywords” containing this plugin’s files.

Activating this plugin provides:

  • A change to the new “Keywords” 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, uninstalled, or have its Options set up.
    • The Options link goes to the new “Keywords” forum Admin panel where the plugin’s administrative options are set up.
    • The “Getting Started” link associated with the “Deactivate/Uninstall/Options” selections should be selected to view the pertinent information regarding the plugin.
  • A new “Keywords” forum Admin panel where its options are set up.
      • The default type of notification, number of keywords a user can specify, and the minimum number of characters in a keyword are specified..
      • The “Help” link should be used for assistance in setting up the options.
    • The “Keywords” forum Admin panel can also be accessed under the Admin menu path Forum > Components > Keywords
  • A new Active CRON under the forum Admin menu at Forum > Toolbox > CRON Inspector with “Hook” named “sph_keywords_cron” that uses the “daily” Cron Schedule as a default to scan new posts for keywords and send notifications to users at the specified time.
  • A new tab “Keywords” in the user’s profile where the keywords to trigger notifications are input in the forum user.
  • After the plugin has been setup, users have specified keywords, and the Keyword CRON runs finding a keyword, a notification with a link to the post is send to the user who specified the keyword.

There are no new permissions added to the permission sets due to this plugin.

Plugin Requirements

Simple:Press version 5.5.8 and above is required.

The Simple:Press plugin must be installed, activated, and its options set before it is operational.

  • As part of the installation, a “Keyword” 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, deleted, or its options set using its “Activate/Delete” and “Deactivate/Uninstall/options” selections.
    • The Options link goes to the new “Keyword” forum Admin panel where its options must be set up.

There are no new permissions added to the permission sets due to this plugin that must be set up.

The plugin has no (0) template tags so there are no recommendations made regarding developing Child Themes or Custom Themes to accommodate changes to template tags.

Plugin Installation and Activation

Please see Using Plugins 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 “keywords“.
  • 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 “keywords.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 “Keywords” plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options” with a “Get Started” Link.

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

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

Plugin Administrative Options

After activation, a) on the aforementioned “Available Plugins – Install Simple:Press Plugins” panel, click “Options” on the “Keywords” plugin section or b) under the “Components” entry on the forum menu on the left side forum admin page click the “Keywords” sub-menu item to get the “Keywords” panel with the “Keyword Options” section.

    • “Keyword Options” Inputs

In this section specifics of the plugin options are set up.

      • Select Default Type of Notification to Users for Keyword Usage

In this option the default type of notification that the users will receive when the keywords they have selected are used in a post. The users can override the default and can select their preference in their profile.

        • If the default type of notification is a forum notification shown to the users when they are logged in, click on the check box next to “Notification” if there isn’t already a green check mark in it.
          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark from the original check box.
        • If the default type of notification is Private Message, click on the check box next to “Private Message (requires PM plugin)” if there isn’t already a green check mark in it.

Note: The Simple:Press Forum “Private Messaging” plugin must be installed and active if this selection is to be used.

          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark from the original check box.
        • If the default type of notification is Email, click on the check box next to “Email” if there isn’t already a green check mark in it.
          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark from the original check box.
        • If there are no other options to select on the panel, click on the “Update ” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

      • “Number of Keywords” Allowed Selection

In this option the maximum number of keywords that users can be watching is selected. Zero (0) will not limit the number of keywords. Zero is not recommended because it will increase the amount of processing time required to scan new posts for keywords.

Note: Scanning and notification of keywords in new posts does not occur in realtime. Via CRON job, new posts will be scanned every hour (by default) for keyword matches followed by notifications then going out to users.
        • In the text input box to the right of “Number of keywords users can be notified of (O is no limit – not recommended):” enter the maximum number of keyword a user is allowed to follow. The default is set at 10.
        • If there are no other options to select on the panel, click on the “Update ” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

      • “Minimum Number of Characters” Allowed Selection

In this option the minimum number of characters that users must input for a keyword is selected. Zero will not limit the number of characters which then could be as low as one (1). Zero is highly not recommended because it will significantly increase the amount of processing time required to scan new posts for keywords.

        • In the text input box to the right of “Minimum number of characters in a keyword (0 is no limit – highly not recommended):” enter the minimum number of characters allowed for a keyword. The default is set at 4.
        • If there are no other options to select on the panel, click on the “Update ” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

To be complete for multilingual forums, the language translation files for this plugin, “Private Post” 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 Keywords 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 “Keywords” 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 “Keywords” 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 use the plugin to set up its options.
Forum Users and Admins can specify the keywords in forum posts that cause them to be notified. These choices are:

    • Specifying User “Keywords” Options
    • On the forum page, click on the “Profile” button to display the “Profile” page.
    • On the profile page, click on the “Keywords” tab to display the “Keywords Options” page.

 

      • Specifying “Keyword Notification Method”

In this option the users can select the type of notification to receive when the keywords they have selected are used in a post. The users can override the default setting selected by the forum Admin.

        • If the type of notification desired is a forum notification shown to them when they are logged in, click on the check box next to “Notification” if there isn’t already a green check mark in it.
          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark in original check box.
        • If the desired type of notification is Private Message, click on the check box next to “Private Message (requires PM plugin)” if there isn’t already a green check mark in it.

Note: The Simple:Press Forum “Private Messaging” plugin must be installed and active if this selection is to be used.

          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark in original check box.
        • If the desired type of notification is Email, click on the check box next to “Email” if there isn’t already a green check mark in it.
          • The check box is selected if it has a green check mark in it.
          • The check box is not selected if it is blank. De-select a check box containing a green check mark by clicking on another check box to remove the check mark in original check box.
        • If there are no other options to select on the tab, click on the “Update Keywords Options ” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

      • Specifying “Keywords”

In this option the users can specify the keywords when found in new posts will cause the user to be notified. The users are limited to the maximum number of keywords and the minimum number of characters for a keyword as specified by the forum Admin.

        • In the text input box to the right of “Keywords to be notified when used in post (comma separated):” input the keywords to cause notifications.
          • The keywords are to be separated by a comma (,) only. Do not put a space ( ) after the comma. For example, “Wimberley,Blanco,flood”.
          • The keyword search is NOT case sensitive so “Wimberley” is the same as “wimberley’.
        • If there are no other options to select on the tab, click on the “Update Keywords Options ” button at the bottom of the page to save the settings. Otherwise, proceed to the next option(s) to select.

 

Forum Users electing to receive Forum Notifications will see notifications in the header of the forum pages when they are logged in.

      • Viewing The Post
        • In the forum page header the notification will be enclosed in a border. The message “You have a post that matched keywords: {keyword(s) matched are shown} (view post) (Remove Notice)”
        • In the notification click on the “(view post)” link to see the post containing the keyword(s).
        • When on the post’s page, click on the Browser’s Back Arrow to return to the page displaying the keyword notification.

 

      • Clearing Keyword Plugin Forum Notifications
        • In the forum page header the notification will be enclosed in a border. The message “You have a post that matched keywords: {keyword(s) matched are shown} (view post) (Remove Notice)”
        • In the notification click on “(Remove Notice)” to remove the notification.

 

Notifications do not occur instantaneously when a post is made with the keyword in it. The Keyword CRON ‘sph_keywords_cron’ must run for the new posts to be scanned for keywords before the appropriate notification is sent to the user specifying the keyword.

Plugin Special Notes

Keywords in posts made by the user specifying the keyword will not result in notifications to that user.

Template Tags Used in the Plugin

There are no (0) template tags available for this plugin that allows further customization of the plugin’s usage or otherwise customize the website.

Action and Hooks Used in the Plugin

There are no Actions and Hooks available in the Plugin’s Template Tags because there are no template tags.
There are other Actions and Hooks available for this plugin.

      • The following Actions and Hooks are in file

‘sp-keywords-options-form.php’

      • used to make the “Keywords Options” panel on the users’ profiles.

      • apply_filters(‘sph_profile_keywords_options’, $msg)- Allows modification of the display code for the keywords message “On this panel, you may set your Keywords Options.” 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_ProfileKeywordsOptionsFormTop’, $out, $userid) – Allows modification of the display code associated with any keywords options information in the top of the page just prior to being output/returned.
      • apply_filters(‘sph_ProfileUserKeywordNotification’, $tout, $userid, $thisSlug) – Allows modification of the display code associated with any keyword notification information (Keyword Notification Methods) in the page just prior to being output/returned.
      • apply_filters(‘sph_ProfileUserKeywords’, $tout, $userid, $thisSlug) – Allows modification of the display code associated with instructions to users regarding inputting keywords just prior to being output/returned.
      • apply_filters(‘sph_ProfileKeywordsOptionsFormBottom’, $out, $userid) – Allows modification of the display code associated with any keyword 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_ProfileKeywordsOptionsForm’, $out, $userid) – Allows modification of any of the display code associated with the page just prior to being output/returned.

The following Actions and Hooks are in file ‘sp-keywords-components.php’.

      • apply_filters(‘sph_ProfileUserKeywordsUpdate’, true)- Primarily designed for hiding the Keywords element of the profile form, if desired, but could be used for modification of the keywords being saved after the user has input them or other purposes. This hook was designed to be similar to the hooks in “Plugin: Profile Display Control” for hiding or showing profile elements.
      • apply_filters(‘sph_keywords_notification_msg’, $message, $user_id) – Allows modification of the display code associated with the keyword message, “You have a post that matched keywords …” just prior to being output/returned when the notification type is forum notification.
      • apply_filters(‘sph_keywords_pm_title’, $title, $user_id) – Allows modification of the title for the keywords Private Message notification just prior to the title being created.
      • apply_filters(‘sph_keywords_pm_message’, $message, $user_id) – Allows modification of the message content for a keywords Private Message notification just prior to the message being created.
      • apply_filters(‘sph_notifications_email_msg’, $message, $user_id) – Allows modification of the message content for a keywords Email notification just prior to the message being created.
      • apply_filters(‘sph_keywords_email_replyto’, ”, $user_id) – Allows modification of the “reply” information in a keywords Email notification just prior to the reply information being created.
      • apply_filters(‘sph_keywords_email_subject’, $title, $user_id) – Allows modification of the “subject or title” of a keywords Email notification just prior to the subject or title being created.

Plugin and Template Tag Changelog

Since Simple:Press version 5.5.7.

Codex page sync’d to code version 5.5.7 and plugin version 1.0.

More Topics In SimplePress: Plugins


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