Theme settings are a way to set up variables that your theme can use, and which offer an interface to be customized via the AdminCP. For example, the default IPS4 theme stores most of its color choices as theme settings, and it's this which facilitates the easy mode editor.
Theme settings are particularly useful when you plan to distribute your theme for others to use, but you may also find uses even if a theme is for your own use. For example, you might occasionally have a banner at the top of your site about some upcoming event. Instead of constantly editing your templates to add/change/remove this message, you could set up a couple of theme settings - one to show/hide it, and another containing the text.
IPS4 supports a wide range of field types for theme settings, opening up some innovative possibilities for your custom themes.
Managing theme settings
Note: Theme settings can only be managed using Designer's Mode. Ensure that mode is enabled before continuing.
Theme settings are managed by navigating to Customizations -> Themes in the AdminCP, clicking the dropdown menu beside the theme you want to edit, and selecting Custom Settings.
The screen you see shows the current theme settings for this theme. You can drag and reorder the settings by grabbing the drag handle to the left of each row, or edit/delete the setting using the buttons to the right.
Theme settings can be grouped, and the groups are shown as tabs at the top of the table.
Creating theme settings
To create a theme setting, click Add Setting at the top of this screen. You'll see a popup window:
-
Title language key
Theme settings need to be language-abstracted, since they can be shown in other languages if a language pack is used. Therefore, instead of entering an English name for this setting, you enter a language key, and then create that language phrase. Since you're in Designer's Mode, a language file named lang.php will be created in the theme directory, so you should create your language phrase in that file, and enter the key in this field. -
For application
The associated application for this setting; this will be Core in almost all situations. -
Key
The key is how your theme setting will be referenced in templates & CSS files, so it's a good idea to pick something simple but clear. -
Tab type
This controls the grouping of the setting. If you want to add the setting to an existing group, select it from the next setting; otherwise, choose New Tab and enter a name in the text field that appears. -
Type
This determines the field type the setting will use, and therefore how admins will choose a value when they edit the setting. -
Default value
The field type you choose will determine what fields are shown, so fill them in as necessary. The Default Value field is shown for all field types, and determines what value this setting will have if the admin doesn't change it. Note: for the Color field type, the value you enter should be a hexadecimal value, and prefixed with a # symbol. For example, #ff0000.
Save the form to add the setting, and exit Designer's Mode when you have finished creating theme settings.
Editing theme setting values
Theme setting values are edited by administrators on the normal edit screen for the theme. Navigate to Customization -> Themes, and click the Edit icon to the right of the theme you want to edit. Theme settings are available in tabs on the edit screen, and can be adjusted based on the field type:
Using theme settings
Now that you have created a theme setting (or several), they can be used in your HTML & CSS files. There's a couple of ways of using them.
{theme} tag
If you just want to output the value a setting (for example, in a CSS file to set a style value as the value of the theme setting), IPS4 includes a special theme tag you can use:
{theme="your_theme_key"}
A real-world example:
body { background-color: {theme="page_background"}; }
HTML logic
If you need to check the value of a theme setting in an HTML logic tag (for example, to determine whether a block of HTML should be shown or not), a short-hand variable is available to you:
theme.your_theme_key
A real-world example:
{{if theme.forum_layout === 'grid'}}
...
{{else}}
...
{{endif}}
Report Guide