Simple:Press Documentation

Plugin: Topic Status

Plugin Description

Plugin: Topic Status – With this Simple:Press plugin a current status can be assigned to topics from lists that are created.

Plugin Features

Once the sets of status lists are defined, a set can be assigned to a forum allowing the forum’s topics to take on the statuses in the set. The topic’s status can be changed to another status in the set as the topic’s situation changes. A set can be assigned to multiple forums.

For example, if the forum is used as a support tool, a new topic could be flagged as ‘New’. The first response could change the state to ‘Unresolved’ and when the problem is dealt with, ‘Resolved’. If it is not to be addressed, “Ignored” could be assigned.

Installing this Simple:Press plugin adds:

  • A new “Topic Status” 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 “topic-status” containing the “Language & Theme Selection” plugin files.

Activating this plugin provides:

  • A change to the new “Topic Status” 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 “Components – Topic Status” 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 “Components – Topic Status” forum Admin panel where its options are set up.
      • The Topic Status Sets section allows naming and specifying the menu select-able status categories for each status set.
      • Different Topic Status Sets can be set up to customize the set to an individual forum or related forums.
      • The “Help” link should be used for assistance in setting up the options.
    • The “Components – Topic Status” forum Admin panel can also be accessed under the Admin menu path Forum > Components > Topic Status.
  • For users with the permission to “Change the status of a topic” in the create reply to topic post form near the bottom in the “Options” section, a new entry “Select Topic Status” is shown with the current topic status displayed in the window.
    • Selecting the down arrowhead to the right of the window provides a dropdown menu where the available status options can be selected
  • To the right of the word “Status:” the status of the topic is shown in the topic’s header in Topic View where all the posts in the topic are shown.
  • Hovering over the topic’s status provides a popup tooltip with the message “Search for other topics with this status”.
    • Clicking on the topic’s status provides a window with a list of the other topics in the forum with the same topic status.

There is one new permission added to the permission sets due to this plugin.

  • The permission “Can change the status of a topic” is must be set/enabled for users to change the status of a topic.

Plugin Requirements

Requires Simple:Press version 5.5.7 and above.

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

As part of the installation, a “Topic Status” section is added to the Plugin Management panel under the forum Admin menu – Plugins/Available Plugins. From this panel the Topic Status plugin can be activated, deactivated, uninstalled, and its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections. The Options link goes to the new Topic Status Options panel where topic status sets are created with individual status phrases for each set.

The Options panel alone can also be seen under the forum Admin menu – Components/Topic Status.

The plugin’s template tags are included in all current themes. If the default positions and layouts are acceptable, nothing need be done. 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.

Plugin Installation and Activation

Please see Using Plugins for additional information on obtaining and installing the Topic Status plugin.

As mentioned there the default location for 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 menu. On the Simple:Press Administration page select the “Topic Status” 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

From the aforementioned “Available Plugins” panel and “Plugin Management” section, click “Options” on the “Topic Status” plugin to get the “Topic Status” panel with “Components – Topic Status” section. From the “Components – Topic Status” section:

  • Configuring a Topic Status Sets
    • A ‘Topic Status Set’ is an optional list of flags – or ‘states’ that a topic can go through. Before the topic status can be added to a forum a set of flags must first be setup. As many sets as are needed can be set up.
    • First a topic status name is set up. This can be anything but it is recommended that it be kept fairly short and something obvious when revisited. If for support statuses then something like “Support Status Set” would be apropos.
    • After naming the 1st set the status phrases are input separated by commas. Enter them in the order they are to appear in the selection list. An example would be: New, Unresolved, Resolved, Ignored.
    • Once complete click on “Update” and your set will be saved.
  • Setting the Keys
    • After saving, select and open “Components” from the menu of the left.
    • Under “Components” select “Topic Status” to be shown the status phrases just entered and their order.
    • Keys must be defined for the set. Setting up keys allows for additional status entries to be inserted in the set at a later date or the status entries to be re-ordered, if needed, while maintaining the integrity of the data assigned to the topics.
    • It is STRONGLY RECOMMENDED to change the numeric keys that are shown to short alphanumeric ones before the status set is used.
    • Once set, the keys themselves should NEVER be changed to ensure that data integrity is maintained.
  • Setting Up Additional Sets and Keys
    • Additional status sets can be added using the blank “Topic Status Set” text boxes at the bottom of the “Components – Topic Status” page.
    • Enter set name for the new set.
    • Enter the status phases in order separated by commas.
    • Once complete, click on “Update” to save the set.
    • Repeat this process to define the keys for each new set desired.
    • NOTE: it may be necessary to get out of and back into “Components – Topic Status” page to see the new set with its keys to be customized.
  • Select forum for Topic Status
    • To use the Topic Status in one or more forums the Topic Status Sets must be assigned to each individual forum that will be using them.
    • Select and open “Forums” from the Admin menu on the left.
    • Under “Forums” select “Manage Groups And Forums” to be shown the available forums.
    • Find the forum to which a Topic Status Set is to be assigned, and select “Edit Forum” to have the “Forums-Manage Groups and Forums” sub-window appear with sections “Forum Details”, “Forum Options”, and “Extended Forum Options”.
    • In the “Extended Forum Options” section to the right of “Assign a topic status set to this forum”, click on the down indicator to the right of the text window to see a drop-down menu with the list of all the Topic Status Sets available. Select the Topic Status Set to be assigned to the forum.
    • Click on the “Update Forum” button on the bottom of the forum’s window to complete the assignment.
    • Assign a set to other forums by repeating the process for each forum.
  • Assign Permissions
    • Allowing users to change topic statuses is controlled by their group permission.
    • Each member group that are to have the ability to change a topic status must have that permission turned on.
    • This is accomplished from the Simple:Press Administration panel by clicking/opening “Permissions” and selecting “Manage Permissions Sets” in its sub-menu.
    • Select “Edit Permission” for the permission set to be updated, scroll down to “Tools” and click the radio button next to “Can change the status of a topic”.
    • When enabled, the radio button is green in color. Click “Update Permission” 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 Topic Status plugin’s available language translation files with translation statistics, and message translations can be viewed at Topic Status 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 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

  • Setting Topic Status
    • The topic status is set when creating a new topic and will be the default or 1st status in the set (“New” in the example) even if the user has permission to change the status and selects one of the other statuses from the “Select Topic Status” menu just below the input text section of the new topic.
      • The topic status created for users that don’t have permission to change statuses will be the first entry configured in the topic status set. This status would be “New” in the example.
    • Once set, the topic status can be changed, by users that have permission to do so, from the admin toolbar shown when viewing the topic in the list of topics in Forum view.
      • Hovering over the “balloon” on the left column of the topic allows the “Forum Toolset” icon (crossed screwdriver and wrench) to be displayed to the left of the “balloon” column.
      • Clicking the “Forum Toolset” icon provides a drop down menu with “Change Topic Status” in the list of selections.
      • Clicking the “Change Topic Status” selection provides a window where the existing Topic Status is shown (New in the example).
      • Clicking the down arrow to the right of the existing status provides the drop down menu allowing selection of a new Topic Status from the Topic Status Set list (say the 2nd status in the set which is Unresolved).
      • Clicking the “Save Status” box will result in the topic’s status being changed to the new status.
    • Older topics in the forum that many not have a Topic Status when viewed in the Forum view can have their status shown or changed by the same procedure immediately above, starting with hovering over the “balloon” associated with the topic to have the “Forum Toolset” icon displayed.
    • A topic’s status can also be changed when replying to a topic before submitting the reply.
      • If the user has permission to set or change a topic status, the words “Select Topic Status” with the current status displayed to its right will be displayed below the text input section of the new topic.
      • Clicking the down arrow to the right of the status results in a drop down menu being displayed containing the various status options in the set. Continuing the example above, the user would see: New, Unresolved, Resolved, Ignored.
      • Select the desired status from the menu.
      • Click “Submit Reply”.
  • Searching Topic Statuses
    • The topic status is shown for each topic when viewing the list in the forum view pages and for the topic in the topic view page.
    • In either forum view or topic view, hovering over the topic’s status will display “Search for other topics with this status”.
    • Clicking on the topic’s status will search and show all topic posts that have the same status.

Template Tags Used in the Plugin

There are two (2) Template Tags available for this plugin that allows you to further customize it’s usage or otherwise customize your website. The Template Tag can be viewed by selecting its link below.

Actions and Hooks Used in the Plugin

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

Plugin and Template Tag Changelog

Version 5.5.1 – ‘statusClass’ argument added to ‘sp_TopicIndexTopicStatus()’.
Version 5.6.0 – ‘label’ parameter added to ‘sp_TopicIndexTopicStatus()’

Codex page sync’d to code version 5.6.0.



Individual Template Tags

The two (2) Template Tags available for Plugin: Topic Status are detailed below.


sp_TopicIndexTopicStatus

Description

sp_TopicIndexTopicStatus() – Displays the Topic Status in each topic in the Forum View.

Usage

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

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spTopicIndexTopicStatus%ID%’
‘tagClass’ => ‘spTopicIndexStatus’
‘icon’ => ‘sp_TopicStatus.png’
‘iconClass’ => ‘spButton’
‘statusClass’ => ‘spButton’
‘echo’ => 1
‘get’ => 0

‘tagId’: CSS ID for the Div. %ID% is replaced by the topic ID.
‘tagClass’: CSS Class for the Div.
‘icon’: Filename of the file for the icon.
‘iconClass’: CSS Class for the icon.
‘statusClass’: CSS Class for the status. This allows for independent styling of the actual status text/button.
‘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.
‘get’: Flag to indicate whether to short circuit the template tag display process and simply return data or to proceed with normal HTML display code generation. One (1) is true and the template tag display process is not done and data is returned. Zero (0) is false and normal html display code generation happens.

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

$label – Text shown along with the Topic Status icon.
Type:
(string) (optional)
Default:
None

Special Notes

This function is supplied in the Topic Status members’ plugin. It is used in a theme’s Forum View.

Examples

In the Forum View near the right edge of the topic, display the topic status icon along with the current status of the topic. When hovering over the current status, display text of “Search for other topics with this status”. Call the function conditionally in case the plugin is deactivated or removed.

if (function_exists('sp_TopicIndexTopicStatus')) sp_TopicIndexTopicStatus('tagClass=spTopicIndexStatus spButton spStatusIcon spRight', __sp('Search for other topics with this status'));

Actions and Hooks Used in sp_TopicIndexTopicStatus Template Tag

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

Source Code

sp_TopicIndexTopicStatus() is located in …/topic-status/sp-topicstatus-template-tags.php.


sp_TopicStatus

Description

sp_TopicStatus() – Displays Topic Status Information .

Usage

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

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spTopicTopicStatus’
‘tagClass’ => ‘spTopicViewStatus’
‘icon’ => ‘sp_TopicStatus.png’
‘iconClass’ => ‘spButton’
‘echo’ => 1
‘get’ => 0

‘tagId’: CSS ID for the Div.
‘tagClass’: CSS Class for the Div.
‘Icon’: Filename of the file for the icon.
‘iconClass’: CSS Class for the 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.
‘get’: Flag to indicate whether to short circuit the template tag display process and simply return data or to proceed with normal HTML display code generation. One (1) is true and the template tag display process is not done and data is returned. Zero (0) is false and normal html display code generation happens.

$toolTip – Text shown when hovering over the topic’s status.
Type:
(string) (optional)
Default:
None

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

Special Notes

This function is supplied in the Topic Status members’ plugin. It is used in a theme’s Topic View.

Examples

In the Topic View within the left portion of the topic header, display the label “Status”, the topic status icon, and the current status for the topic. When hovering over the current status, display text of “Search for other topics with this status”. Call the function conditionally in case the plugin is deactivated or removed.

if (function_exists('sp_TopicStatus')) sp_TopicStatus('tagClass=spTopicViewStatus spButton spLeft', __sp('Search for other topics with this status'), __sp('Status: '));

Actions and Hooks Used in sp_TopicStatus Template Tag

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

Source Code

sp_TopicStatus() is located in …/topic-status/sp-topicstatus-template-tags.php.


More Topics In SimplePress: Plugins


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