• Your cart is empty.

Plugin: Language & Theme Selection

Important Note:  The contents of this document applies ONLY to version 5.x.x of Simple:Press.  It likely does NOT apply to version 6.x.x (our latest version).

Plugin Description

Plugin: Language & Theme Selection – This Simple:Press plugin adds in the ability for forum users to select which color scheme they prefer (color overlay) on overlay dependent themes and the language the forum supports – depending upon the existence of the required language “.mo” files.

Plugin Features

Installing this Simple:Press plugin adds:

  • A new “Language & Theme Selection” 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 “Language & Theme Selection” plugin can be activated, or deleted by the admin.
  • When properly installed, a new folder in the “forum-plugin” folder named “user-selection” containing the “Language & Theme Selection” plugin files.

Activating this plugin provides:

  • A change to the new “Language & Theme Selection” section in the “Available Plugins – Install Simple:Press Plugins” panel under the Admin menu path Forum > Plugins > Available Plugins so the Simple:Press “Language & Theme Selection” plugin can be deactivated, uninstalled, and have it Options set.
    • The Options link goes to the new “Language Files” forum Admin panel where the forum Admin selects the forum language options.
    • The “Getting Started” link associated with the “Deactivate/Uninstall/Options” selections should be selected to view the pertinent information regarding the plugin.
  • A new “User Languages” sub-menu entry under the forum Admin menu Forum > Toolbox entry also linked to the new “Language Files” panel where the forum Admin selects the forum language options.
  • A new “Language Files” forum Admin panel with “Language Options” and “Language File Naming” sections where the forum Admin selects the forum language options the forum user can choose for displaying the forum.
    • A selection allows displaying the default English as a language option.
    • A selection allows inputting a Custom Display name for the language options the forum user will select from instead of the cryptic language translation filename (locale).
    • The “Help” links should be used for assistance in setting up the options.
  • As the default in the footer for forums using the standard supplied Simple:Press themes and their Child themes:
    • To the right of the label “Language:” a drop down menu allows the forum user to select from the available forum languages.
    • To the right of the label “Theme:” a drop down menu allows the forum user to select from the available color overlays for the current forum theme, if any.
    • The “Theme” portion displays on the left of the “Language” portion on the same line.

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

Plugin Requirements

Simple:Press version 5.5.7 and above is required.

An overall understanding of both Word:Press and Simple:Press Language Translation file utilization is necessary. The details found at Localization MUST be understood and the appropriate steps detailed there taken to get SP language translation files (“.mo” files) properly named and placed.

Many of our users have been confused into believing that the localization has not worked after installing the core (Front End and/or Admin) SP .mo files for a given language.

One must remember that Simple:Press is now driven by themes. The majority of the text displayed in the forum is derived from the theme file – NOT the core SP files.

For a given language, one needs to also add the active theme’s translation .mo file and the .mo file for each active plugin that has a display component.

  • The minimum required for this plugin to be affective is to have the Simple:Press “active” Forum Theme” and Forum Core “Front End” language translation files properly named and placed for each language the forum user is to be able to select for displaying phrases on forum pages.
  • For more complete language translation coverage for the each language selectable by the forum user, the language translation files for each “activated” Simple:Press Forum Plugin should also be properly named and placed.

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

  • As part of the installation, a “Language & Theme Selection” section is added to the “Available Plugins – Install Simple:Press Plugins” panel under the admin menu Forum > Plugins > Available Plugins. From this panel the “Language & Theme Selection” plugin can be activated, deactivated, uninstalled, deleted, or its options set up using its “Activate/Delete” and “Deactivate/Uninstall/Options” selections.
  • The Options link goes to the new “Language Files” forum Admin panel where the options are set up.

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

The plugin has one (1) template tag which is incorporated into supplied Simple:Press themes.

  • If the locations 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, 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 “Language & Theme Selection” 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 the Simple:Press “Language & Theme Selection” 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 “user-selection“.
  • 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 “user-selection.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 “Language and Forum Selection” plugin and click on “Activate”. The “Activate/Delete” label changes to “Deactivate/Uninstall/Options” with a “Get Started” Link.

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

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

Plugin Administrative Options

Before this plugin’s administrative options are set up, the translation files for the languages the forum user will be allowed to select for viewing the forum must be installed or downloaded/properly placed in the appropriate forum-language folders. Please see the discussions and procedures at Localization.

To be complete, the language translation files for this plugin, “Language & Theme Selection” for the languages the forum user will be allowed to select for viewing the forum 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.

After activation, a) on the aforementioned “Available Plugins – Install Simple:Press Plugins” panel, click “Options” on the “Language & Theme Selection” plugin section or b) under the “Toolbox” entry on the forum menu on the left side forum admin page click the “User Languages” sub-menu item to get the “Language Files” panel to set up the plugin’s options.

  • Setting Up the “Language Options” Section Option
  • In this section, the forum Admin can optionally choose whether or not to offer the forum default language of English for users to select as a language.

    • In the “Language Options” section if English is to be provided as a language for the user, select the checkbox next to “Display default English as language option” by clicking it if it does not already contain an green check mark.
      • The check box is selected when it has a check mark in it.
    • Deselect a check box with a check mark in it by clicking on the check box.
      • The check box is deselected when it is empty.
    • Scroll to the bottom of the page to click the “Update” button if there are no other options to set on the panel. Otherwise, wait to click the button until the other desired options have been set.

  • Setting Up the “Language File Naming” Section Options
  • In this section, the locale (filename) for Simple:Press “Front End” translation files that have been installed or downloaded/properly placed are displayed under the “Translation File” column. These (and possible the default English, if that option has been selected) are the only languages the forum user will be allowed to select.

    The forum Admin can attach a custom display name to each of the available language packs for the forum users to select because the locale for translation files are often very cryptic. This custom display name will be used instead of the language translation locale. If a custom name is not supplied, the language translation locale will be used instead.

    • For example if the locale (filename) for the Chinese (Taiwan) “Front End” translations is “sp-zh_TW.mo”, the user would likely be better able to understand which language to select if the custom display name of “Chinese (Taiwan)” or the equivalent in the target language were provided.
    •  

    For each of the Simple:Press Forum Core “Front End” language translation files (and also the default English language file if the “Display default English as language option” was selected above) listed in this section under the “Translation File” column with a corresponding blank text input box under the “Display Name” column:

    • If a more understandable identification is desired for a language file in the list, insert the display name to be used in the blank text input box under the “Display Name” column. For example for the language translation locale “en”, one might type “English” into the blank text input box.
    • Repeat the step immediately above for all language files to have more understandable display names.
    • Scroll to the bottom of the page to click the “Update” button (or the equivalent in the language specified by the WP “Site Language” setting) if there are no other options to set on the panel. Otherwise, wait to click the button until the other desired options have been set.

Plugin Language Translation

Three types of language translations files can exist for translating forum message strings from English to other languages and then displaying the translation. Parts of the forum may not have translation files.

  • Simple:Press Language files for translating core forum message strings
  • If translations are available “Admin” and “Front End” sections have their own files each with possibly multiple pages.

  • Simple:Press Plugin Language Files for translating forum plugin message strings
  • Each plugin has its own files each with possibly multiple pages if translations are available.

  • Simple:Press Theme Language Files for translating forum theme message strings
  • Each theme has its own files each with possibly multiple pages if translations are available.
    The theme’s translation files also provide translations for its standard supplied Child Theme Framework.

Translation files of a given type are to reside in a unique forum folder location as defined on the “Integration – Storage Locations” forum Admin panel available through the forum Admin menu at Forum > Integration > Storage Locations.

  • Forum core translation files are to reside at the location indicated by the “Simple:Press Language Files” entry.
    • The default location for forum core translation files is the folder “…/wp-content/sp-resources/forum-language/simple-press”.
  • Forum Plugin translation files are to reside at the location indicated by the “Simple:Press Plugin Language Files” entry.
    • The default location for forum plugin translation files is the folder “…/wp-content/sp-resources/forum-language/sp-plugins”.
  • Forum Theme translation files are to reside at the location indicated by the “Simple:Press Theme Language Files” entry.
    • The default location for forum core translation files is the folder “…/wp-content/sp-resources/forum-language/sp-themes”.

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. 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.

The “Language & Theme Selection” plugin’s available language translation files with translation statistics, and message translations can be viewed at Language/Theme Selector within the repository for Simple:Press language translation files.

  • Installing the Simple:Press “Language & Theme Selection” Plugin Language Translation “.mo” files
    The “Language & Theme Selection” plugin language translations files for each language can be correctly located in two ways.

    WARNING: Some plugin and WordPress language files come with a ‘double’ language code like ‘it_IT’ for Italian. This will be the case for languages spoken in many countries.

    The important point is that the language code displayed on the “Integration – Language Settings” panel under the “Language” section MUST be matched for the WordPress language file and ALL Simple:Press “Core”, “Theme” and “Plugin” language files.

    If they do not, edit the language translation file name to match the displayed code. For example, if “Your site language is set to fr_FR – French” is shown, the “fr_FR” must be matched in all the French translation file names. In the example, ‘sp-fr_FR.mo’ for forum “Front End” phrases and ‘spa-fr_FR.mo’ for forum “Admin” phrases.

    Any Simple:Press language file it MUST begin with the component short name followed by a hyphen and then the desired single or double language code with the extension of .mo and all will be well. For example, ‘spa-it_IT.mo” (Admin – Italian), ‘spDefault-fr_FR’ (Default Theme – French), and sp-birthdays-de_DE (Birthday Plugin – German).

    • Using the Admin Word:Press “Site Language” and Simple:Press “Language Translation” Features
      • Go to the Localization codex page.
      • Under “Language Translation Selection Sequences”, “Coordinated Language Translation File Download Using the “Simple:Press ‘Language Translation’ Selection”, follow the instructions at “Adding its Translation File(s) After Downloading/Activating a Simple:Press Theme or Simple:Press Plugin”.
        • Follow the instructions and click on the “Install” button for this plugin, “Language and Theme Selection” to install the language translation file for the current “Site Language” language.
        • Be sure to verify the locale (filename) Matches the language code for the language as discussed in the “Warning” above. If it does not, change it.
        • As called out in the section, continue to change the “Site Language” language and repeat the process until all desired “Language and Theme Selection” plugin translation files have been installed.
        •  

    • Manually Finding and Storing the Simple:Press “Language & Theme Selection” Plugin Language Translation ‘mo’ files
      • Find the Simple:Press Plugin Language Files folder where plugin translation files are to be stored.
        • Note: Do not confuse the forum-language folders. There are three (3) different ones as discussed above.
        • The location of the Simple:Press Plugin Language File folder is identified by the “Simple:Press Plugin Language Files” entry on the “Integration – Storage Locations” panel viewed from the forum Admin menu at Forum > Integration > Storage Locations.
          • The default location for Simple:Press 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.
      • Go to the plugin translation files at Language/Theme Selector Translations.
      • Click on the Version Number link to see the languages available for the plugin.
      • Click on the Language Name link for the desired language to see plugin messages and their available translations.
      • If available, export the file for the selected language to the forum language plugin folder (default is …/forum-language/sp-plugins) as follows:
        • Scroll to the bottom of a translation page to see the word “Export” (the Export Link) followed by a 1st drop down menu with translation phrase options followed by the word “as” followed by a 2nd drop down menu with translation file export options.
        • In the 1st drop down menu click its up/down arrowhead to see the phrase options and select the desired option (typically “all current” is chosen).
        • In the 2nd drop down menu click its up/down arrowhead to see the export file options and select “Machine Object Message Catalog (.mo).”
        • Click on “Export” (the Export Link) to download the selected language “.mo” file.
          • Be sure to note the language file locale (filename) so it can be found and relocated if necessary.
          • For example, the Swedish translation file for the Simple:Press “Theme & Language Selection” plugin could be “sp-usel-sv_SE.mo” and the French translation file for the Simple:Press Birthday plugin could be “sp-birthdays-fr.mo”.
        • If the language file was not downloaded to the forum language plugin folder (the default is …/forum-language/sp-plugin), find the file and move it to the forum language plugin folder, wherever it is located and whatever it is named.
        • Be sure to verify the locale (filename) Matches the language code for the language as discussed in the “Warning” above. If it does not, change it.
      • Repeat the steps above for each language to have a translation file available for the “Language & Theme Selection” plugin.

Plugin Usage

Forum Admins use this plugin to set up the plugin’s options.

Forum Users and Admins can make theme color overlay selections and/or language selections from the respective drop down menus that are located by default in the forum page footer.

  • The theme overlay options displayed are those of the active theme.
  • The language options displayed (along with possible the default “English) are only those for “Front End” language files downloaded by the forum Admin and placed in the appropriate forum-language folder.
  • Selecting a Theme Color Overlay
    • On the forum page, by default in the footer, find the default label “Theme:” adjacent to the name of the active theme’s current color overlay.
    • Click on the down arrowhead to see the drop down menu with all the available color overlays for the active theme.
    • Move the cursor down the list to highlight the new selection of color overlay and click the mouse again to select that overlay.
      • The forum page reloads now using the selected theme color overlay.
      • The selected theme color overlay name is now displayed adjacent to the default label “Theme:” to indicate it is now being used.
  • Selecting a Forum Language
    • Note: The language selections are the options for the “Front End” of the forum, the portion seen by a forum user.
      • Only if the active theme has a downloaded translation file matching the selected “Front End” language selection, will the theme’s phrases display in the selected language.
        • The specific theme phrase must have a translation from English in the theme language translation file to show up in the selected language.
        • Otherwise the theme phrase will continue to be displayed in English.
      • Only if the each active plugins had a downloaded translation file matching the selected “Front End” language selection, will that plugin’s phrases display in the selected language.
        • The specific plugin phrase must have a translation from English in the specific plugin language translation file to show up in the selected language.
        • Otherwise the plugin’s phrase will continue to be displayed in English.
    • On the forum page, by default in the footer, find the default label “Language:” adjacent to the name of forum’s current language.
    • Click on the down arrowhead to see the drop down menu with all the available languages for the forum.
    • Move the cursor down the list to highlight the new selection of language and click the mouse again selecting that language.
      • The forum page reloads now using the selected forum language.
      • The selected forum language locale or Display Name is now displayed adjacent to the default label “Language:” to indicate it is now being used.

Plugin Special Notes

The color overlay selection form (drop down menu) will only be shown if the active Simple:Press theme or Simple:Press Child theme uses overlays and the only overlays displayed are those residing in the appropriate overlay folder(s). With a child theme, overlays in a parent theme’s overlay folder can be seen along with the uniquely named overlays in the child theme’s overlay folder.

The language selector also checks for installed Simple:Press language files. If no optional language files are found the plugin will not display a language selection form (drop down menu).

When changing color scheme and language files only the forum itself is changed. This plugin will not change the site’s main WordPress color or look nor it’s language.

Template Tags Used in the Plugin

There is one (1) template tag available for this plugin that allows further customization of the plugin’s usage or otherwise customize the website.

  • If the default locations in the themes as well as the arguments and parameter values for the template tag are acceptable, nothing need be done.
  • If any of these items relating to the template tag is to be modified, 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 “Language & Theme Selection” 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.

Plugin and Template Tag Changelog

Since Simple:Press version 5.0.
Version 5.6.0 – ‘echo’ argument added to ‘sp_UserSelectOptions’

Codex page sync’d to code version 5.6.0 and plugin version 1.3.4.



Individual Template Tags


 

sp_UserSelectOptions

Description

sp_UserSelectOptions() – This template displays labels and drop down menu selections allowing the forum user to select the theme overlay and/or the language used when displaying the forum.

Usage

sp_UserSelectOptions($args=”, $labelTheme=”, $labelLanguage=”);

Arguments

$args – List of arguments for controlling display.
Type:
(string) (optional)
Default:
‘tagId’ => ‘spUserSelectOptions’
‘tagClass’ => ‘spSelectOptions’
‘themeClass’ => ‘spSelectTheme’
‘languageClass’ => ‘spSelectLanguage’
‘labelClass’ => ‘spLabel’
‘selectClass’ => ‘spSelect’
‘theme’ => 1
‘language’ => 1
‘spacer’ => ‘    ‘ which contains four (4) “& n b s p ;” in a row between the single quotes
‘stacked’ => 0
‘echo’ => 1

tagId‘: CSS ID for the Div.
tagClass‘: CSS Class for the Div.
themeClass‘: CSS Class for the theme.
languageClass‘: CSS Class for the language.
labelClass‘: CSS Class for the label.
selectClass‘: CSS Class for the select.
theme‘: Flag to indicate whether to show the theme overlay options or not. A one (1) will show the theme overlay possibilities for forum user selection. A zero (0) will not show the theme overlay possibilities for forum user selection.
language‘: Flag to indicate whether to show the language possibilities or not. A one (1) will show the language possibilities for forum user selection. A zero (0) will not show the language possibilities for forum user selection.
spacer‘: Characters to display between the theme and language portions.
stacked‘: Flag to indicate whether to display the language portion below the theme portion or leave them on the same line. A one (1) will show the language portion stacked below the theme portion. A zero (0) will show the theme portion followed by the language portion on the same line.
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.

$labelTheme – Text displayed before the theme overlay selection drop down menu.
Type:
(string) (optional)
Default:
None

$labelLanguage – Text displayed before the language selection drop down menu.
Type:
(string) (optional)
Default:
None

Special Notes

In standard supplied Simple:Press themes this template tag is included in the footer (‘spFoot.php’) file.
The exception is:

  • the reboot theme where the template tag is not included in the ‘spFoot.php’ file, but is included in the ‘spFootDesktop.php’ and ‘spFootMobile.php’ files.
  •  

The function is called conditionally, if (function_exists(‘ ‘)), so that if the “Policy Document” 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.

This template tag function requires the usage of the ‘sp-user-selection-tags.php’ file located in the plugin’s template-tag folder.

Examples

1. In the footer of the Simple:Press Default theme page conditionally display the drop down menu list of overlays for the current theme preceded by the label “Theme” and on the same line the drop down menu list of the available language options preceded by the label “Language”. In the Default theme the following template tag is placed in the ‘spFoot.php’ file:

if (function_exists('sp_UserSelectOptions')) sp_UserSelectOptions('tagClass=spCenter spLabelSmall', __sp('Theme:'), __sp('Language:'));

2. In the footer of a theme page conditionally display the drop down menu list of overlays for the current theme preceded by the label “Theme” and below on the next line the drop down menu list of the available language options preceded by the label “Language:”.

Because the ‘stacked’ argument value is being changed from that in the standard supplied theme, it is suggested a Child Theme be developed to accept the modified template tag. For this example, the Default theme’s Child Theme Framework would be downloaded in the ‘forum-theme’ folder and set up. The Default theme’s ‘spFoot.php’ file should be copied over to the corresponding folder in the Child Theme Framework. Modify the Child Theme’s ‘spFoot.php’ file’s standard ‘sp_UserSelectOptions’ call to be:

if (function_exists('sp_UserSelectOptions')) sp_UserSelectOptions('tagClass=spCenter spLabelSmall&stacked=1', __sp('Theme:'), __sp('Language:'));

 

Actions and Hooks Used in the sp_UserSelectOptions Template Tag

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

Posted in