GS Custom Settings is a plugin for GetSimple CMS which lets webmasters/ site managers, theme and plugin developers implement and use their own custom settings for output, configuration, and cross-plugin/-theme communication. It's a bit like the custom fields plugin, but not for pages. The plugin offers 8 different types of input to choose from, 3 access levels, per-user editing permission, and an easy UI to create, import and export the settings. Once activated, a new tab 'Site', is added, where one will find all settings created with the plugin, grouped by sidebar tab. View a screenshot of the UI in Manage mode or Edit mode

The plugin is built on Knockout JS and handles almost all logic client-side, except for plugin registration, hooks, path resolving, and handling server requests. Data is sent and saved through AJAX. Furthermore, the plugin provides an interactive notification service and a JS localization system. The language file for this plugin is also in JSON format.

GS Custom Settings is compatible with PHP 5.2+ (might work with PHP 5+, untested) and all browsers except Internet Explorer 8 and older Managing settings also works in IE8 (editing doesn't). Some features might not work on some browsers. See Known Issues for more information. If you find bugs or have feature requests or questions, feel free to open a new issue in the Github repo or write a post on the GS support forum.

• Custom settings for site managers, plugin and theme developers
• 8 different setting types (select, radio, text, textarea, checkbox, image, color, section title) + 3 fancy variants (FontAwesome)
• 3 access levels for settings (normal, hidden, locked)
• Output settings in pages with (% setting:tab/setting %) or in PHP with get_setting('tab','setting')
• Output multilingual settings (only with I18N plugin 2.5.8+)
• Restrict user editing permission per user (also with MultiUser 1.8.2+)
• Feature-rich editing in 'edit' mode with multiselect, batch setting adding/removing & keyboard shortcuts
• Responsive feedback through notifications
• Import (IE10+ & other browsers)/ Export settings for re-use through the GUI
• Build and export settings directly through the UI for your plugin/ theme
• Extend existing themes and plugins with custom settings
• Access settings from other themes and plugins
• (almost) fully i18n, even custom theme and plugin settings I18n-enabled
• Available in English, French, Dutch, German, Russian & Spanish

Download the latest (or other) version(s) of this plugin on the GetSimple Extend Plugin page. The latest version of this plugin is 0.3. To install, simply unzip to GS plugins directory.

GS Custom Settings allows you to build custom settings for your theme through an easy UI,
and they can even be multilingual! No need for building a custom plugin like the InnovationPlugin. After you have downloaded Custom Settings, and installed it on your local/ test site (just like other GS plugins), go to Site tab, switch to Edit mode, create a new tab (name it however you like), add all the settings you need, and in the list toolbar, in the select next to Export tab as:, choose Theme.

If for some reason the file isn't automatically named settings.json, rename it to that.

The descriptions/ labels/ values exported will be used as default values in the default language. If you want, you can add more languages by creating a subdirectory in your theme named lang.

For example a simple GS theme with trilingual custom settings would have a directory like this:

Theme root
  ├─ assets/
  ├─ images/
  ├─ style.css
  ├─ template.php
  ├─ functions.php
  ├─ settings.json (with en_US as standard)
  └─ lang/ (optional)
     ├─ en_US.json
     ├─ fr_FR.json
     └─ de_DE.json

The only translatable strings are a setting's label,descr and options (if the setting is a select, radio or fancy radio). For each of these, you should prefix the property with the setting's lookup. The language files in the lang directory should have a strings object holding all strings for the settings. You can optionally add a meta object containing information about the translation version, author, date etc.

{"meta": {"author":"me"}, /* meta is optional */
  "strings": {
     "mysetting_label": "Label",
     "mysetting_descr": "Description",
     "mysetting_options": [
        "option1",
        "option2",
        "option3"
     ],
     "mysecondsetting_label": "Label 2",
     "mysecondsetting_descr": "Description 2"
  }
}

You're set! When your theme is activated in the GS theme tab, your settings will appear in the Custom Settings sidebar in the tab Theme settings (GS tab Site). The data is saved to /data/other/custom_settings/theme_data_<themename>.json.

Not entirely sure yet? For more examples, read the Theme tutorial.

GS Custom settings provides a sleek GUI for building and (later) updating, or managing (by third parties) your plugin's settings. In your plugin's directory (create one if you didn't have one already, and give it the same name as your plugin's ), you should have a valid settings.json file, create a lang subdirectory (if

1. Create a plugin directory with the same name as your plugin's main .php file if you haven't already.
2. In this directory you should have a valid JSON settings file, named settings.json. You can build this either:
   1. Manually: If you choose this, make sure your file has the required format, and your JSON contains no errors. You can test this with JSONlint.
   2. Through the plugin's GUI (easiest):. To do so, install the plugin on your test site, go to Site tab, switch to Edit mode, create a new tab, give it your plugin's name, and add all the settings you need. When ready, in the toolbar's Export tab as: dropdown, choose Plugin. Save the file as settings.json in your plugin's directory.
3. If you want your plugin to be multilingual, create a lang subfolder in your plugin folder, and include all language files with PHP locale used by GetSimple (eg, en_US, fr_FR, de_DE). Translatable setting properties are: label, descr, options. The format of the JSON file should be as in the sample language file in the Attachments section.

Your plugin directory should look like this for GS Custom Settings to work:

/plugins/
  ├─ your_plugin.php
  └─ your_plugin/
       ├─ settings.json (with default language)
       └─ lang/ (optional)
           ├─ en_US.json
           ├─ fr_FR.json
           └─ de_DE.json
	

The only translatable strings are a setting's label,descr and options (if the setting is a select, radio or fancy radio). For each of these, you should prefix the property with the setting's lookup. The language files in the lang directory should have a strings object holding all strings for the settings. You can optionally add a meta object containing information about the translation version, author, date etc.

{"meta": {"author":"me"}, /* meta is optional */
  "strings": {
     "mysetting_label": "Label",
     "mysetting_descr": "Description",
     "mysetting_options": [
        "option1",
        "option2",
        "option3"
     ],
     "mysecondsetting_label": "Label 2",
     "mysecondsetting_descr": "Description 2"
  }
}

GS Custom Settings provides 4 hooks for your plugin's functions. To use it, do: add_action($hook_name, $function)

You can also output a link to your custom settings in your plugin tab by using <?php get_tab_link('myplugin','link title') ?>. When clicked, it will open the relevant item in the Custom settings sidebar.

It should be noted that you don't need to manually add a hook to initialize your settings. As soon as custom_settings.php is included in the site, the settings.json file from your plugin's settings (if it is activated) will be automatically added to the custom settings UI. You should only use functions like remove_setting and set_setting to update settings from an old to a newer version. If so, be sure to include a hidden version setting to check.
Plugin data is saved to /data/other/custom_settings/plugin_data_<yourpluginname>.json.

Functions

get_setting($tab, $setting, $echo=TRUE)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $setting - lookup property of the setting to output
// @param {boolean} [$echo=TRUE] - (optional) Whether to echo the setting. 
// Handy if you want the display value returned but not outputted.

get_i18n_setting($tab, $setting, $echo=TRUE)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $setting - lookup property of the multilingual setting to output
// @param {boolean} [$echo=TRUE] - (optional) Whether to echo the multilingual setting. 
// Handy if you want the display value returned but not outputted.

return_setting($tab, $setting, $prop=NULL)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $setting - lookup property of the setting to return
// @param {string|boolean} [$prop=NULL] - (Optional) A single property of the setting to return, or FALSE to return the full setting

return_setting_group($tab, $group, $prop=NULL)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $group - prefix in the lookup property, common to all settings in the group
// @param {string|boolean} [$prop=NULL] - (Optional) A single property to return for all settings, or FALSE to return them fully

get_tab_link($tab=NULL, $linkText='settings')
// @param {string} [$tab=NULL] - (Optional) Empty, lookup property of  
// lookup property of a plugin (basename) or 'theme_settings', or a site tab
// @param {string} [$linkText='settings'] - (Optional) A custom text for the <a> element

set_setting($tab, $setting, $value)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $setting - lookup property of the setting to return
// @param {string|array} $value - The property (ies) to modify.

remove_setting($tab, $setting)
// @param {string} $tab - lookup property of the tab to search in
// @param {string} $setting - lookup property of the setting to remove

Hooks

add_action('custom-settings-load', $function)
// @param {string} $function - the function you want to execute before settings are loaded

add_action('custom-settings-save', $function)
// @param {string} $function - the function you want to execute right before settings are saved

add_action('custom-settings-render-top', 'custom_settings_render', array($plugin, $function))
// @param {string} $plugin - the basename of your plugin
// @param {string} $function - the function you want to execute 
// to output content above your setting list (eg. instructions, links, ...).

add_action('custom-settings-render-bottom', 'custom_settings_render', array($plugin, $function))
// @param {string} $plugin - the basename of your plugin
// @param {string} $function - the function you want to execute 
// to output content below your setting list (eg. extra buttons).