Simple:Press Documentation

Plugin: Featured Topics and Posts

Plugin Description –

This Simple:Press plugin provides for highlighting a list of featured topics or posts in the forum or on other webpages.

Plugin Overview

  • Provides a new forum Admin panel for identifying topics and posts to be featured.
  • Provides new menu items in the “Forum Toolset” to “Feature this topic”/”Unfeature this topic” or “Feature this post”/”Unfeature this post”.
  • Provides two (2) template tags that can be added to pages throughout the website to list the Featured Topics or Featured Posts, respectively.
Note:
If a forum user does not have access to a specific forum, that user will not see the featured topics or posts listed from that forum.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Featured Topics and Posts” 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 “featured” containing the plugin’s files.

Activating this plugin provides:

  • A change to the new “Featured Topics and Posts” section in the “Available Plugins – Install Simple:Press Plugins” panel under the Admin menu path Forum > Plugins > Available Plugins so the Simple:Press plugin can be deactivated, uninstalled, or have its Options set up.
    • The Options link goes to the new “Featured Topics and Posts Plugin” forum Admin panel where the plugin’s options can be set.
    • The “Getting Started” link associated with the “Deactivate/Uninstall/Options” selections should be selected to view the pertinent information regarding the plugin.
  • A new forum Admin sub-menu entry, “Featured Topics/Posts” under “Components” in the forum Admin menu.
    • The “Featured Topics/Posts” sub-menu entry is linked to the “Featured Topics and Posts Plugin” forum Admin panel where the plugin options can be set up.
  • A new “Featured Topics and Posts Plugin” forum Admin panel with its “Featured Topics and Post Options” section where the list of featured topics and the list of featured posts can be selected using their IDs.
    • The “Featured Topics and Posts Plugin” forum Admin panel can be accessed from WP Admin menu at:
      • Forum > Components > Featured Topics/Posts
      • Forum > Plugins > Available Plugins > Featured Topics and Posts > Options
  • In forum view, new “Feature this topic” or “Unfeature this topic” entries in the “Forum Toolset” on topics where the forum Admin or forum Moderator can select the topic to the featured or unfeatured, respectively.
    • The “Forum Toolset” is accessed on forum Topics or Posts by hovering the cursor over the upper left hand corner of the topic or post to see the “Forum Toolset” icon (Crossed wrench and screwdriver) and the message “Open the forum toolset”, then clicking the icon to see the popup menu of available forum tools.
  • In topic view, new “Feature this post” or “Unfeature this post” entries in the “Forum Toolset” on posts where the forum Admin can select the post to be featured or unfeatured, respectively.
    • The “Forum Toolset” is accessed on forum Topics or Posts by hovering the cursor over the upper left hand corner of the topic or post to see the “Forum Toolset” icon (Crossed wrench and screwdriver) and the message “Open the forum toolset”, then clicking the icon to see the popup menu of available forum tools.
  • Two (2) new Template Tags which can be manually added to Simple:Press Child or Custom themes to list the featured topics and posts along with displaying information regarding those topics and posts on forum pages. The template tags can also be added to other webpages on the website.
    • ‘sp_FeaturedTopicsTag()’ displays featured topics
    • ‘sp_FeaturedPostsTag()’ displays featured posts

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

Plugin Requirements

Requires Simple:Press version 5.6.2 and above.

The topics and posts to be featured must already exist in the forums so that their Topic ID or Post ID, respectively, exist for listing or the forum toolset for the topic or post can be accessed by the forum Admin or forum Moderator.

This plugin must be installed, activated, and its options set before it is operational.

As part of the installation, an “Featured Topics and Posts” 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, deleted, or its options set using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections.

  • The Options link goes to the new “Featured Topics and Posts Plugin” forum Admin panel with its “Featured Topics and Posts Options” section.

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

The plugin has two (2) template tags, ‘sp_FeaturedTopicsTag()’ and ‘sp_FeaturedPostTag()’, neither of which is incorporated into standard supplied Simple:Press themes.

  • If the template tags are not to be added to Simple:Press themes, nothing need be done.
  • If either of the template tag is to be incorporated, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin rather than modifying a standard supplied Simple:Press theme.
  • 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.

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 “featured“.
  • 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 “featured.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 Featured Topics and Posts plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options” with a “Getting 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”.
To re-activated the plugin, click on on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options”.

 

Plugin Administrative Options

After activation, a) on the aforementioned “Available Plugins – Install Simple:Press Plugins” panel, click “Options” on the Featured Topics and Post plugin section or b) under the Components entry on the forum menu on the left side forum admin page click the Featured Topics/Posts sub-menu item to get the “Featured Topics and Posts Plugin” Admin panel with its “Featured Topics and Posts Options” section.

FeatureTopics

    • Featuring or Unfeaturing Topics and Posts Using their IDs

In this section featured topics and posts can be selected for or removed from listing on website pages. Displaying the featured topic/post information does required that the appropriate topic or post template tag has been manually added to a Simple:Press Child or Custom theme template or a webpage.

Note:
Naturally, this plugin requires that the topics and post already exist and have IDs in the forums for them to be featured.
Note:
If there are more topics or posts in the featured list than are allowed to be displayed in the featured topics/posts template tag by its arguments, the list will be truncated with the newer topics/posts being shown.
    • Go to the “Featured Topics and Post Options” section of the Admin panel.
      • Please click on the section’s “Help” link for more information on this section’s feature(s).
    • To made a topic list or post list to be featured, enter a comma separated list of topics IDs or post IDs in the appropriate input field.
      • To the right of “List of featured topic IDs:” for topics.
      • To the right of “List of featured post IDs:” for posts.
      • The order is not important as the template tag (or shortcode) will order the topics/posts with newer topics/posts shown first.
    • To unfeature a topic or post, remove the topic’s ID or the post’s ID from the appropriate input field (and possible its associated comma).
    • After all desired Topic and/or Post IDs have been entered or removed, click the “Update” button to save the selections.

The forum Admin and forum Moderators can mark topics and posts as “featured” using the “Forum Toolset” menu available on topics and posts in the forum.

    • Feature or Unfeature a Topic or Post from the Post’s “Forum Toolset”
Note:
Naturally, this plugin requires that the topics and post already exist in the forums for them to be featured.
    • Go to the topic within a forum or to the post within a topic which is to be featured.
    • Hover the cursor over the upper left corner of the topic or in the “user information” section of the post to the left of the date or the post author’s avatar to see the “Forum Toolset” icon (a crossed wrench and screwdriver) and the message, “Open the forum toolset”.
    • Click on the icon to see the popup “Forum Tools” menu with its available selections.
    • If the topic or post is not currently featured, click on the “Feature this topic” or “Feature this post” menu item to feature the topic or post, respectively.
      • The topic or post’s ID shows up with the other featured items on the “Featured Topics and Posts Plugin” forum Admin panel in the “Featured Topics and Posts Options” section in the listing box to the right of:
        • “List of featured topic IDs” for topics.
        • “List of featured post IDs” for posts.
    • If the topic or post is currently featured, click on the “Unfeature this topic” or “Unfeature this post” menu item to no longer feature the topic or post, respectively.
      • The topic or post’s ID is removed from the “Featured Topics and Posts Plugin” forum Admin panel in the “Featured Topics and Posts Options” section in the listing box to the right of:
        • “List of featured topic IDs” for topics.
        • “List of featured post IDs” for posts.

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 Featured Topics and Posts 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 “Featured Topics and Posts” 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 “Featured Topics and Posts” 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 and forum Moderators use this plugin to feature topics and posts in the forum as shown above in the Plugin Administrative Options section.

Forum Users do not use this plugin.

Plugin Special Notes

None

 

Template Tags Used in the Plugin

There are two (2) template tags available for this plugin that allow further customization of the plugin’s usage in themes or otherwise customize the website. Neither ‘sp_FeaturedTopicsTag()’ nor ‘sp_FeaturedPostsTag()’ are incorporated into standard supplied Simple:Press themes.

  • If the template tags are NOT to be added to Simple:Press themes, nothing need be done.
  • If one or more of the template tags is to be incorporated, it is recommended that a Child or Custom theme is created first to accept the changes prior to installing this plugin rather than modifying a standard supplied Simple:Press theme.
  • 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 Tag can be viewed by selecting its link below.

Action and Hooks Used in the Plugin

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

There are no other Actions and Hooks available for this plugin to modify aspects of the plugin.

Plugin and Template Tag Changelog

Since Simple:Press version 5.2.2.

Codex page template tags sync’d to code version 5.6.8 and plugin version 1.0.11.



Individual Template Tags


 

sp_FeaturedTopicsTag()

Description

sp_FeaturedTopicsTag() – This template displays the list of latest featured topics in the forum.

Usage

sp_FeaturedTopicsTag($args=”);

Arguments

$args – list of arguments for controlling the display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spFeaturedTopicsTag’
‘tagClass’ => ‘spListTag’
‘listId’ => ‘spListItemTag%ID%’
‘listClass’ => ‘spListItemTag’
‘linkClass’ => ‘spLinkTag’
‘textClass’ => ‘spTextTag’
‘avatarClass’ => ‘spAvatarTag’
‘listTags’ => 1
‘topicIds’ => ”
‘limit’ => 5
‘itemOrder’ => ‘FTUD’
‘linkScope’ => ‘forum’
‘beforeForum’ => __(‘Forum: ‘, ‘sp-featured’)
‘afterForum’ => ‘<br />’
‘beforeTopic’ => __(‘Topic: ‘, ‘sp-featured’)
‘afterTopic’ => ‘<br />’
‘beforeUser’ => __(‘By: ‘, ‘sp-featured’)
‘afterUser’ => ”
‘beforeDate’ => ‘&nbsp;-’
‘afterDate’ => ”
‘avatarSize’ => 25
‘niceDate’ => 1
‘postTip’ => 1
‘echo’ => 1

Note:

  • True must be expressed as a 1 and False as a zero.
  • All text items can include allowed html.

tagId‘: The unique CSS ID to be applied Div.
tagClass‘: The CSS Class to be applied to the Div for styling.
listId‘: The CSS ID to be applied to the list. The %ID% is replaced by the topic ID number.
listClass‘: The CSS Class to be applied to list for styling.
linkClass‘: The CSS Class to be applied to link for styling.
textClass‘: The CSS Class to be applied to text labels for styling
avatarClass‘: The CSS Class to be applied to avatar.
listTags‘: Flag to indicate whether to wrap the list in <ul> and <li> tags or use a div. A one (1) is true and the tags will be used. A zero (0) is false and a div will be used.
topicIds‘: A comma delimited list of topic ID’s. If topics ID’s are specified here and there are less than or equal the number allowed by the limit’ argument, the template tag display will contain only these topics. Otherwise the topic IDs in the featured topics admin panel will be used up to the number allowed by the ‘limit’ argument.
limit‘: The upper limit for number of topics to show in the list. This is a number.
itemOrder‘: Controls which components are displayed and also the order in which they are displayed. Use the following codes to construct this parameter. No spaces or other characters can be used. Upper case (Capital) letters must be used.

    • F – Displays the forum name

 

    • T – Displays the Topic name

 

    • A – Displays the topic author’s Avatar

 

    • U – Displays the topic author’s display name

 

    D – Displays the date of the post

linkScope‘: Controls what items are made into links (‘a’ tags): This is entered as text.

Note:
The Topic will ALWAYS be formed as a link.

The following options are available:

    • forum – Display the Forum name as a link as well as the Topic.

 

    all – Make the entire entry a link to the Topic.

beforeForum‘: The text to display before the forum title.
afterForum‘: The text to display after the forum title.
beforeTopic‘: The text to display before the topic title.
afterTopic‘: The text to display after the topic title.
beforeUser‘: The text to display before the topic author’s display name.
afterUser‘: The text to display after the topic author’s display name.
beforeDate: The text to display before the date.
afterDate‘: The text to display after the date.
avatarSize: The Pixel size for the topic author’s avatar if the avatar is being displayed. This is a number.
niceDate‘: Flag to indicate whether to display the date of the post in the “nicedate” format. One (1) is true and causes the post’s date to be displayed in “nicedate” format with the post. Zero (0) is false and causes the post’s date to not be displayed in the “nicedate” format with the post. Examples of the “nicedate” format are “1 week ago” and “5 days ago”.
postTip‘: Flag to indicate whether or not to display an extract from the topic in the tooltip message displayed when the cursor is hovered over the topic title link. One (1) is true causing the topic extract to be displayed. Zero (0) is false resulting in no topic extract being displayed.
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

This template tag is NOT in standard supplied Simple:Press themes.

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.

A possible location for the template tag in a Custom or Child theme is in the header, ‘spHead.php’ or ‘spHeadDesktop.php’ and ‘spHeadMobile.php’, depending on the Simple:Press parent theme.

If 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 maximum number of the featured topics displayed by this template tag is set by the value selected by the forum Admin in the ‘limit’ argument. If used in the header, it is recommended that the number of topics displayed be kept small.

The function requires the use of file ‘sp-featured-topics-tag.php’ located in the plugin’s Template Tag folder.

Examples

1). Using the defaults but with “tagClass” of “spFeaturedTopics spLeft”, display to the left the three (3) latest “featured topics” in the ‘userInfo’ section of the header of a Child theme based on the Simple:Press Default theme after the ‘sp_UserNotices()’ call. Call the function conditionally. Separate the call from the previous call by adding a ‘sp_InsertBreak()’ call.

a. If not already done, download the Simple:Press Default Child Theme Framework to contain the template tag modification, and set it up including providing a unique name as discussed in the Creating a Child Theme page.
b. If not already in existence, add a “templates” folder in the child theme folder to contain the file to be modified.
c. If not already done, copy the ‘spHead.php’ file from the Simple:Press Default Theme and place it in the Child Theme’s ‘template’ folder.
d. Modify the ‘spHead.php’ file header to identify it as part of the Child Theme, add the change listed below, and save the file.

sp_InsertBreak(); 
if (function_exists('sp_FeaturedTopicsTag')) sp_FeaturedTopicsTag('tagClass=spFeaturedTopics spLeft&limit=3');

When complete, the file’s modified section might look something like:

sp_UserNotices('', __sp('(Remove Notice)'));
sp_InsertBreak();
if (function_exists('sp_FeaturedTopicsTag')) sp_FeaturedTopicsTag('tagClass=spFeaturedTopics spLeft&limit=3');

e. Activate the uniquely named child theme on the site by clicking its “Activate Theme” button on the “Available Themes – Select Simple:Press Theme” forum Admin panel accessed from the forum Admin menu at Forum > Themes > Available Themes.

2). Keep everything else the same as in example 1, but change “itemOrder” to “FTAUD”, “limit” to “2”, and “afterDate” to the HTML separator “<hr />”.
The change becomes:

sp_InsertBreak(); 
if (function_exists('sp_FeaturedTopicsTag')) sp_FeaturedTopicsTag('tagClass=spFeaturedTopics spLeft&itemOrder=FTAUD&limit=2&afterDate=<hr />');

3). Use Shortcode with the default arguments to display featured topics.

[sp_featured_topics];

 

Actions and Hooks Used in the sp_FeaturedTopicsTag() Template Tag

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

Changelog

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


 

sp_FeaturedPostsTag()

Description

sp_FeaturedPostsTag() – This template displays the list of latest featured posts in the forum.

Usage

sp_FeaturedPostsTag($args=”);

Arguments

$args – list of arguments for controlling the display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spFeaturedPostsTag’
‘tagClass’ => ‘spListTag’
‘listId’ => ‘spListItemTag%ID%’
‘listClass’ => ‘spListItemTag’
‘linkClass’ => ‘spLinkTag’
‘textClass’ => ‘spTextTag’
‘avatarClass’ => ‘spAvatarTag’
‘listTags’ => 1
‘postIds’ => ”
‘limit’ => 5
‘itemOrder’ => ‘FTUD’
‘linkScope’ => ‘forum’
‘beforeForum’ => __(‘Forum: ‘, ‘sp-featured’)
‘afterForum’ => ‘<br />’
‘beforeTopic’ => __(‘Topic: ‘, ‘sp-featured’)
‘afterTopic’ => ‘<br />’
‘beforeUser’ => __(‘By: ‘, ‘sp-featured’)
‘afterUser’ => ”
‘beforeDate’ => ‘&nbsp;-’
‘afterDate’ => ‘<br />’
‘avatarSize’ => 25
‘niceDate’ => 1
‘postTip’ => 1
‘beforePost’ => __(‘Post: ‘, ‘sp-featured’)
‘afterPost’ => ‘<br />’
‘echo’ => 1

Note:

  • True must be expressed as a 1 and False as a zero.
  • All text items can include allowed html.

tagId‘: The unique CSS ID to be applied Div.
tagClass‘: The CSS Class to be applied to the Div for styling.
listId‘: The CSS ID to be applied to the list. The %ID% is replaced by the topic ID number.
listClass‘: The CSS Class to be applied to list for styling.
linkClass‘: The CSS Class to be applied to link for styling.
textClass‘: The CSS Class to be applied to text labels for styling
avatarClass‘: The CSS Class to be applied to avatar.
listTags‘: Flag to indicate whether to wrap the list in <ul> and <li> tags or use a div. A one (1) is true and the tags will be used. A zero (0) is false and a div will be used.
postIds‘: A comma delimited list of post ID’s. If post ID’s are specified here and there are less than or equal the number allowed by the limit’ argument, the template tag display will contain only these posts. Otherwise the post IDs in the featured topics admin panel will be used up to the number allowed by the ‘limit’ argument.
limit‘: The upper limit for number of topics to show in the list. This is a number.
itemOrder‘: Controls which components are displayed and also the order in which they are displayed. Use the following codes to construct this parameter. No spaces or other characters can be used. Upper case (Capital) letters must be used.

    • F – Displays the forum name

 

    • T – Displays the Topic name

 

    • A – Displays the topic author’s Avatar

 

    • U – Displays the topic author’s display name

 

    • D – Displays the date of the post

 

    • P – Displays the content of the post

 

    E – Displays an excerpt of the post content

linkScope‘: Controls what items are made into links (‘a’ tags): This is entered as text.

Note:
The Topic will ALWAYS be formed as a link.

The following options are available:

    • forum – Display the Forum name as a link as well as the Topic.

 

    all – Make the entire entry a link to the Topic.

beforeForum‘: The text to display before the forum title.
afterForum‘: The text to display after the forum title.
beforeTopic‘: The text to display before the topic title.
afterTopic‘: The text to display after the topic title.
beforeUser‘: The text to display before the topic author’s display name.
afterUser‘: The text to display after the topic author’s display name.
beforeDate: The text to display before the date.
afterDate‘: The text to display after the date.
avatarSize: The Pixel size for the topic author’s avatar if the avatar is being displayed. This is a number.
niceDate‘: Flag to indicate whether to display the date of the post in the “nicedate” format. One (1) is true and causes the post’s date to be displayed in “nicedate” format with the post. Zero (0) is false and causes the post’s date to not be displayed in the “nicedate” format with the post. Examples of the “nicedate” format are “1 week ago” and “5 days ago”.
postTip‘: Flag to indicate whether or not to display an extract from the post in the tooltip message displayed when the cursor is hovered over the topic title link. One (1) is true causing the post extract to be displayed. Zero (0) is false resulting in no post extract being displayed.
beforePost‘: The text to display before the post. Note: The ‘beforePost’ text will only be displayed if the ‘itemOrder’ argument contains a ‘P’ or an ‘E’.
afterPost‘: The text to display after the post. Note: The ‘afterPost’ text will only be displayed if the ‘itemOrder’ argument contains a ‘P’ or an ‘E’.
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

This template tag is NOT in standard supplied Simple:Press themes.

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.

A possible location for the template tag in a Custom or Child theme is in the header, ‘spHead.php’ or ‘spHeadDesktop.php’ and ‘spHeadMobile.php’, depending on the Simple:Press parent theme.

If 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 maximum number of the featured posts displayed by this template tag is set by the value selected by the forum Admin in the ‘limit’ argument. If used in the header, it is recommended that the number of posts displayed be kept small.

The function requires the use of file ‘sp-featured-posts-tag.php’ located in the plugin’s Template Tag folder.

Examples

1). Using the defaults but with “tagClass” of “spFeaturedPosts spRight”, display on the right the three (3) latest “featured posts” in the ‘userInfo’ section of the header of a Child theme based on the Simple:Press Default theme after the ‘sp_UserNotices()’ call. Call the function conditionally. Separate the call from the previous call by adding a ‘sp_InsertBreak()’ call.

a. If not already done, download the Simple:Press Default Child Theme Framework to contain the template tag modification, and set it up including providing a unique name as discussed in the Creating a Child Theme page.
b. If not already in existence, add a “templates” folder in the child theme folder to contain the file to be modified.
c. If not already done, copy the ‘spHead.php’ file from the Simple:Press Default Theme and place it in the Child Theme’s ‘template’ folder.
d. Modify the ‘spHead.php’ file header to identify it as part of the Child Theme, add the change listed below, and save the file.

sp_InsertBreak(); 
if (function_exists('sp_FeaturedPostsTag')) sp_FeaturedPostsTag('tagClass=spFeaturedPosts spRight&limit=3');

When complete, the file’s modified section might look something like:

sp_UserNotices('', __sp('(Remove Notice)'));
sp_InsertBreak();
if (function_exists('sp_FeaturedPostsTag')) sp_FeaturedPostsTag('tagClass=spFeaturedPosts spRight&limit=3');

e. Activate the uniquely named child theme on the site by clicking its “Activate Theme” button on the “Available Themes – Select Simple:Press Theme” forum Admin panel accessed from the forum Admin menu at Forum > Themes > Available Themes.

2). Keep everything else the same as in example 1, but change “itemOrder” to “FTAUDE” to add the post excerpt, “limit” to “2”, and “afterPost” to the HTML separator “<hr />”.
The change becomes:

sp_InsertBreak(); 
if (function_exists('sp_FeaturedPostsTag')) sp_FeaturedPostsTag('tagClass=spFeaturedPosts spRight&itemOrder=FTAUDE&limit=2&afterPost=<hr />');

3). Use Shortcode with the default arguments to display featured topics.

[sp_featured_posts];

 

Actions and Hooks Used in the sp_FeaturedPostsTag() Template Tag

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