Simple:Press Documentation

Plugin: Topic Description

Plugin Description

Plugin: Topic Description – This Simple:Press plugin allows users to add an optional topic description when creating new topics.

Plugin Features

Installing this Simple:Press plugin adds:

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

Activating this plugin provides:

  • A change to the new “Topic Description” section in the Plugin Management panel under the Admin menu path Forum > Plugins > Available Plugins so the plugin can be deactivated, or uninstalled.
    • There are no options for this plugin.
    • The “Getting Started” link associated with the “Deactivate/Uninstall” selections should be selected to view the pertinent information regarding the plugin.
  • In the “Add Topic” post form immediately under the “Topic name” text input box, a new “Topic description” text input box where an optional, possibly more detailed description can be added to the new topic.
  • When viewing the list of topics in Forum View, a topic having a ‘topic description’ has the contents of the “Topic description” text box from the “Add Topic” form displayed right under the Topic Title.
  • In Topic View when viewing a topic having a ‘topic description’, the contents of the “Topic description” text box from the “Add Topic” form is displayed right under the Topic Title. The text occurs from the ‘sp_TopicHeaderName()’ call.

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

Plugin Requirements

Simple:Press version 5.5.5 and above is required.

As part of the installation, a “Topic Description” section is added to the Plugin Management panel under the admin menu Forum > Plugins > Available Plugins. From this panel the plugin can be activated, deactivated, uninstalled, or deleted.

  • There are no options that need be set up for this plugin.

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

The plugin has one (1) template tag, ‘sp_TopicDescription()’, incorporated into standard supplied Simple:Press themes.

  • 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 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 “topic-description“.
  • 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 “topic-description.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 “Topic Description” 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

After installing and activating, there are no Administrative Options to be set for this plugin.

There are no new permissions that must be set in the permission sets because of this plugin.

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 Topic Description 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 “Topic Description” 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 “Topic Description” 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

All members that can create a topic will also be able to assign the topic a description. The entry area where the description is entered is directly underneath the topic title in the “Add Topic” form.

  • Adding a Topic Description to a New Topic Post
  • Navigate to a forum or a topic in a forum and click the “Add Topic” button to display the “Add Topic” form.
  • Along with adding the topic name and filling in the text of the topic, click inside the text input box below “Topic description” to add a description of the topic if desired.
    • Adding a “Topic description” is optional and is not required in the topic post.
  • After completing the sections of the new topic post, click on the “Submit Topic” button at the bottom of the form to submit the topic post.
  • The “topic description” will be shown with the Topic Title in both the Forum View and the Topic View pages.

Plugin Special Notes

None

 

Template Tags Used in the Plugin

There is one (1) template tags available for this plugin that allow further customization of the plugin’s usage or otherwise customize the website. ‘sp_TopicDescription()‘is incorporated into standard supplied Simple:Press themes.

  • If the location of the template tag in the themes as well as the argument and parameter values for the template tags are acceptable, nothing need be done.
  • If any item relating to the template tag are to be modified or if the other template tags are 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 tags 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 to modify aspects of the plugin.
In file ‘sp-topic-description-components.php‘:

  • apply_filters(‘sph_topic_description_label’, __(‘Topic description’, ‘sp-topic-description’)) – Allows modification of the label for the Topic Description text input box in the “Add Topic” form, “Topic description’, before it is output/returned.
  • apply_filters(‘sph_topic_description’, $temp) – Allows modification of the contents of the topic description used along with the topic name in the Topic View before it is output/returned.

Plugin and Template Tag Changelog

Since Simple:Press version 5.2.

Codex page template tags sync’d to code version 5.6.3 and plugin version 1.2.8.



Individual Template Tags


 

sp_TopicDescription

Description

sp_TopicDescription() – This template displays the topic description.

Usage

sp_TopicDescription($args=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spTopicDescription%ID%’
‘tagClass’ => ‘spTopicDescription’
‘echo’ => 1

tagId‘: CSS ID for the Div. The %ID% is replaced by the topic ID.
tagClass‘: CSS Class for the Div.
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.

Special Notes

In standard supplied Simple:Press themes this template tag is included in the Forum View (‘spForumView.php’) file.
The exceptions are:

  • the Reboot and Barebones theme where the template tag is not included in the ‘spForumView.php’ file, but is included in the ‘spForumViewDesktop.php’ and ‘spForumViewMobile.php’ files.
  • the iForum theme where the template tag is also included in the ‘spForumSubView.php’.

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.

The template tag can be placed elsewhere in the forum pages if that better fits the site’s theme. If the template tag is to be modified or its location on a page changed, 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-topic-description-tag.php’ located in the plugin’s Template Tag folder.

Examples

Using the defaults display the contents of the ‘Topic description’ text input box from the “Add Topic” form when the post was originated. Call the function conditionally.

if (function_exists('sp_TopicDescription')) sp_TopicDescription();

 

Actions and Hooks Used in the sp_TopicDescription Template Tag

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


More Topics In SimplePress: Plugins


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