Simple:Press Documentation

Plugin: Ranks Information

Plugin Description

Plugin: Ranks Information – This Simple:Press plugin allows setup of forum standard and special rankings of users, displaying a forum user’s rank on their forum posts, and a forum page listing the members and their rankings.

WARNING: If the Simple:Press “Hide Posters” plugin is active and posts have been configured to hide the user information about the author of a post, the “Standard” or “Special” Rank information including any badge normally displayed on a post by this plugin WILL NOT BE DISPLAYED.Please see the Simple:Press Plugin: Hide Poster Codex page for further information.

Plugin Overview

  • Forum Admin sets up the ranking systems and selects participants using a new Forum Admin panel.
  • A user’s rank is displayed on their posts in the forum.
  • User ranks of all or selected participants can be displayed on a special “Ranks Information” forum page.
  • An icon and/or link to the “Ranks information” page is displayed by default in the forum page header.
  • A template tag is included to display ranks on any WordPress page, text widget or special areas of the forum.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Ranks Information” 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 “rank-info” containing the plugin’s files.

Activating this plugin provides:

  • A change to the new “Ranks Information” 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 “Components – Standard Forum Ranks” forum Admin panel with several other panels and sections.
    • 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 – Standard Forum Ranks” forum Admin panel containing several sub-panels with sections.
    • “Components – Standard Forum Ranks” subpanel with “Forum Ranks” section where standard forum ranks parameters are set up.
    • “Components – Special Forum Ranks” subpanel with “Special Forum Ranks” section where special forum ranks parameters are set up.
    • “Components – Forum Rank Badges” subpanel with:
      • “Custom rank badge upload” section where files containing rank badge icons can be uploaded.
      • “Custom Rank Badges” section where the uploaded rank badge files are listed.
    • “Components – Forum Ranks” subpanel with “Rank Info Options” section where display options for the forum ranks on the new “Ranks Information” forum page can be selected.
      • Display auto membership info for ranks
      • Display badge with info for ranks
      • Display members of each rank
      • Display members of same rank only
      • Display special ranks info
      • Display members of each special rank (if displaying special ranks)
      • Display members of same special rank only (if displaying special ranks)
    • The “Components – Standard Forum Ranks” forum Admin panel can be accessed from the Forum Admin menu at:
      • Forum > Components > Forum Ranks
      • Forum > Plugins > Available Plugins > Ranks Information > Options
  • A new column “Rank” in the existing “Users – Member Information” forum Admin panel where the “Forum Rank Name” from the “Component – Standard Forum Ranks” forum Admin panel is displayed for each forum member based on their number of posts (the Standard Rank criteria).
  • A new entry in column 1 (the author’s information section) of the forum post displaying the post author’s rank and the rank’s badge if there is one.
    • The “Special Rank Name” from the “Special Forum Ranks” section of the “Components – Special Forum Ranks” takes priority.
    • The “Admin” or “Moderator” rank is displayed for those forum members if they do not have a special rank.
    • The “Forum Rank Name” from the “Forum Ranks” section of the “Components – Standard Forum Ranks” is displayed if the user does not have either of the previously described ranks.
  • A new “Forum Rank” icon in the forum page header with a link to the new “Rank Information” page.
    • Hovering over the “Forum Rank” icon displays the message, “Display Forum Ranks Information”.
    • The default placement of the icon in the header is adjacent to the icons displaying the messages “Most recent topics with unread posts”, “Mark all topics as read”, and “Go to Bottom” when the cursor is hovered over them.
  • A new “Rank Information” forum page displaying the rank information selected by the forum Admin in the “Rank Info Options” section of the “Components – Forum Ranks” forum Admin sub-panel.
    • Specifics of “Standard Forum Ranks” and “Special Forum Ranks” may be display with the sections providing links under “Members” to expand the tables to display the name of members of each rank if selected by the forum Admin.
    • The “Rank Information” viewing page is placed at “… YourWebsite/YourForumName/rankinfo” automatically by the plugin.
  • A new “forum-badges” folder located by default under “…wp-content > sp-resources” where the graphical badge files the forum admin may upload to be associated with the various rank levels are stored.
    • If this path is changed, it is important to note that the “forum-badges” folder and its content need to reside in the forum “sp-resources” folder wherever it has been moved and however it has been renamed. See Storage Locations for more information.
  • A new entry “Forum Badges Folder” on the “Integration – Storage Locations” Admin panel identifies the actual location of the “forum-badges” folder.
    • The “Integration – Storage Locations” Admin panel can be access from the forum Admin menu at Forum > Integration > Storage Locations.
    • See Storage Locations for more information.

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.

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

As part of the installation, a “Ranks Information” 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 “Components – Standard Forum Ranks” forum Admin panel having sub-panels with sections.

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

The plugin has one (1) template tag, ‘sp_RankInfo()’ incorporated into standard supplied Simple:Press themes from Version: 1.2.2 or newer. A second template tag, ‘sp_DisplayRankInfo()’ is part of the “Rank Information” viewing page. Themes older than V1.2.2, any custom theme previously created or if the template tags are to be used differently than currently implemented, they must be added manually. Please see the example below in the template tag description.

  • 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 the template tag must be added to an older theme, or if any item relating to the template tag in a later theme is to be modified or if 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 tag should be called conditionally, if (function_exists(‘ ‘)) so that if the plugin is deactivated or does not exist, the website will continue to operate.

Plugin Installation and Activation

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

  • Whatever method is used to add the Simple:Press plugin, the folder that should have been added to the forum plugin folder is named “rank-info“.
  • 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 “rank-info.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 Ranks Information 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 Ranks Information plugin section or b) under the Components entry on the forum menu on the left side forum admin page click the Forum Ranks sub-menu item to get the “Components – Standard Forum Ranks” Admin panel and other sub-panels.

    • Uploading Rank Badge Files

This feature allows uploading graphical rank badges to be later associated with the various Standard and Special Forum Rank levels.

      • Scroll down to the “Components – Forum Rank Badges” panel and the “Custom rank badge upload” section of the Admin panel.
        • Please click on the section’s “Help” link for more information on this section’s feature(s).
      • For each “rank badge” to upload:
        • Click on the “Browser” button to open the browser and navigate the file structure to find the badge file to be uploaded.
        • Click on the badge file to be uploaded and complete the browser process for selecting the file (e.g. click “open”).
        • When successfully uploaded, the badge graphic and its filename are shown in the “Custom Rank Badges” section of the Admin panel.
WARNING: A Rank Badge file can be removed from the server by clicking its “Trash Can” icon under the “Remove” column, BUT after the badge file has been associated with any forum or special rank, the forum or special rank that used that badge will no longer display (will be deleted).
      • Repeat the steps above until all desired badge files have been successfully uploaded.

 

    • Standard Rank – Assigning Ranks Based on Number of Posts

This feature allows assigning different ‘ranks’ to members depending on how many post they have made. There is no limit to the number of rankings.

      • Go to the “Components – Standard Forum Ranks” panel and the “Forum Ranks” section of the Admin panel.
        • Please click on the section’s “Help” link for more information on this section’s feature(s).
      • For each “rank” level:
        • In the text input box under “Forum Rank Name” enter the name to be used for the rank level (e.g. Beginner).
        • In the text input box under “# Posts For Rank” enter the maximum number of posts a forum user can make and stay at that rank level.
        • If users are to be automatically moved to a Usergroup when entering that level, click on the ‘down arrowhead’ in the row under “Automatic User Group Membership” to see the usergroups available.
          • Move the cursor down the list to highlight the desired usergroup and click on it to select it.
          • The selected usergroup appears in the box for that rank level.
        • If a badge icon file is to be assigned to the rank level and it has been uploaded using the “Component – Forum Rank Badges” sub-panel with its “Custom rank badge upload” section, click on the ‘down arrowhead’ in the row under “Badge” to see the list of available badge files by their filename.
          • Move the cursor down the list to highlight the desired badge file and click on it to select it.
          • The selected badge file appears in the box for that rank level.
      • Repeat the above steps until all desired Standard Rank levels have been completed.
        • If the last available row has just been filled out, hit “enter” on the keyboard to have another empty row appear.
      • If there are no other Standard Rank levels to be filled in, click the “Update Forum Ranks Components” to save the selections.

 

    • Special Forum Ranks – Assigning Ranks Based A Criteria Defined by the Forum Admin

This feature allows assigning different ‘ranks’ any member based on whatever criteria the Forum Admin wants. There is no limit to the number of Special rankings.

      • Go to the “Components – Special Forum Ranks” panel and the “Special Forum Ranks” section of the Admin panel.
        • Please click on the section’s “Help” link for more information on this section’s feature(s).
      • For each “Special rank” level:
        • If there is an empty Special Rank row, fill it in starting with the next major step in this list of steps or if a new row is needed perform these two (2) substeps:
          • In the text input box to the right of “New Special Rank Name” enter the name to be used for the Special rank level (e.g. Contributor)
          • Click the “Add Special Rank” button to have a new row appear with the new Special rank name in it.
        • If not already filled, in the text input box under “Special Rank Name” enter the name of the Special Rank level.
        • Click on the “Add Members” button to view the “Eligible members” list containing forum user who could be added to the level.
          • Move the cursor down the “Eligible member” list to highlight the desired user and click on it to select/highlight it.
          • Click on the “Move to Selected List” button to move the user from the “Eligible members” list to the “Selected members” list to be added to the level.
            • For a highlighted user in the “Selected members” list, clicking on the “Remove From Selected List” will remove the user from the “Selected members” list and place them back in the “Eligible members” list.
          • Repeat the two (2) steps at this same indentation level immediately above selecting additional users until all desired users have been moved to the “Selected members” list.
          • Click the “Add Members” button to add the users in the “Selected members” list to this Special Rank.
        • If a badge icon file is to be assigned to the Special Rank level and it has been uploaded using the “Component – Forum Rank Badges” sub-panel with its “Custom rank badge upload” section, click on the ‘down arrowhead’ in the row under “Badge” to see the list of available badge files by their filename.
          • Move the cursor down the list to highlight the desired badge file and click on it to select it.
          • The selected badge file appears in the box for that rank level.
        • Click the “Update Rank” button associated with the Special Rank to save it.
      • Repeat the above steps until all desired Standard Rank levels have been completed.

 

    • Setting the Rank Info Options

These features allow setting the options for the “Rank Information” display page. This page is accessed by clicking the “Forum Ranks” icon in any forum page header. The message “Display Forum Ranks Information” is displayed when hovering over the “Forum Ranks” icon.

Note: Options are selected or deselected as follows :

  • The check box is selected if it contains a green check mark.
  • Clicking a check box containing a green check mark deselects the check box and removes the green check mark.
    • Scroll down to the “Components – Forum Ranks” panel and the “Rank Info Options” section of the Admin panel.
      • Please click on the section’s “Help” link for more information on this section’s feature(s).
    • Click on the check box to the left of “Display auto membership info for ranks” to select this option for display.
    • Click on the check box to the left of “Display badge with info for ranks” to select this option for display.
    • Click on the check box to the left of “Display members of each rank” to select this option for display.
    • Click on the check box to the left of “Display members of same rank only” to select this option for display.
    • Click on the check box to the left of “Display special ranks info” to select this option for display.
    • Click on the check box to the left of “Display members of each special rank (if displaying special ranks)” to select this option for display.
    • Click on the check box to the left of “Display members of same special rank only (if displaying special ranks)” to select this option for display.
    • When all options have been set to the appropriate state, click the “Update Rank Info Options” button at the bottom of the panel to save the selections.

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 Ranks Information 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 “Ranks Information” 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 “Ranks Information” 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.

Usage

Forum Admins use this plugin to view the Standard Rank and number of posts of forum users from the Forum Admin menu.

  • Viewing Users’ Standard Rank and Number of Posts from the Forum Admin Menu
    • In the forum Admin menu navigate to Forum > Users > Member Information to view the “Users – Member Information” forum Admin panel to see the list of forum users.
    • The “Standard Rank” of each user is displayed under the “Rank” column in the user’s row.
    • The number of posts for each user is displayed under the “Posts” column in the user’s row.

Forum Admins and Forum Users can view the “Standard” or “Special” rank of themselves or other users in forum posts.

WARNING: If the Simple:Press “Hide Posters” plugin is active and a post has been configured to hide the user information about the author of a post, the “Standard” or “Special” Rank information including any badge normally displayed on a post by this plugin WILL NOT BE DISPLAYED.Please see the Simple:Press Plugin: Hide Poster Codex page for further information.

  • Viewing Users’ Rank In Forum Posts
    • Navigate to the forum, topic, and the post of the user whose ranks is to be viewed.
    • If the “Hide Poster” plugin is not active or the post is not configured to hide the post author’s information, the post authors “Standard” or “Special” Rank and any associated badge are displayed in the left most column (column 1, the author’s information section) of the post, typically somewhere under the author’s Avatar and name.

Forum Admins and Forum Users can view the “Rank Information” forum page that displays the forum rank information specified by the forum Admin when selecting the options on the “Components – Forum Ranks” sub-panel.

  • Viewing the “Rank Information” Forum Page
    • In the forum page header, click on the “Forum Rank” icon which displays the message “Display Forum Ranks Information” when hovered over by the cursor to display the “Rank Information” viewing page.
    • The rank information displayed is a result of the selections made by the forum Admin.
    • If the “Standard Rank” information (the table with “Rank Name”) is being shown and setup to show members, clicking on the “View” link under “Members” for a given rank will expand the table to show that rank’s members by name.
      • Clicking on the “View” link when the table is expanded will close down the members listing expansion.
    • If the “Special Rank” information (the table with “Special Rank Name”) is being shown and setup to show members, clicking on the “View” link under “Members” for a given rank will expand the table to show that rank’s members by name.
      • Clicking on the “View” link when the table is expanded will close down the members listing expansion.

Plugin Special Notes

None

 

Template Tags Used in the Plugin

There is one (1) template tag available for this plugin that allow further customization of the plugin’s usage in themes or otherwise customize the website. ‘sp_RankInfo()’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 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.3

Codex page template tags sync’d to code version 5.6.4 and plugin version 1.0.17.



Individual Template Tags


 

sp_RankInfo

Description

sp_RankInfo() – This template displays the “Forum Rank” icon and link to the forum “Rank Information” viewing page.

Usage

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

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spRankInfo’
‘tagClass’ => ‘spButton’
‘icon’ => ‘sp_RankInfo.png’
‘iconClass’ => ‘spIcon’
‘linkId’ => ‘spRankInfoLink’
‘mobileMenu’ => 0
‘echo’ => 1

tagId‘: CSS ID for the Div.
tagClass‘: CSS Class for the Div.
icon‘: Filename of the file containing the “Forum Rank” icon to be displayed.
iconClass‘: CSS Class for the icon.
linkId‘: CSS ID for the link.
mobileMenu‘: Flag to indicate whether to compile the target into the mobile action list for mobile device display or keep it as a separate button/link for desktop display. One (1) is true and the target is compiled into the mobile action list. Zero (0) is false and it is left as a separate button/link for desktop display.
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.

$label – Text to include on the register button.
Type:
(string) (optional)
Default:
None

$toolTip – Message to display in tooltip when the button is hovered over.
Type:
(string) (optional)
Default:
None

Special Notes

In standard supplied Simple:Press themes this template tag is included in the forum page header (‘spHead.php’) file.
The exceptions are:

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

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

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-rank-info-tag.php’ located in the plugin’s Template Tag folder.

Examples

Display the “Forum Rank” icon with “tagClass” of “spButton spRight”, “$label” of ” ” (no label), and “toolTip” of “Display Forum Ranks Information”. Call the function conditionally.

if (function_exists('sp_RankInfo')) sp_RankInfo('tagClass=spButton spRight', '', __sp('Display Forum Ranks Information'));

 

Actions and Hooks Used in the sp_RankInfo Template Tag

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