Usage
The ClientConfig add-on is typically used for:
- Regularly updating the slogan or tagline in the header or footer.
- Changing the color of the order buttons depending on the time.
- Storing updated contact information in a single database.
- Updating the form for sending email notifications.
- And / or settings that you need and can easily update.
Installation
ClientConfig can be downloaded via the package manager from the main repository and the modstore repository.
You can also download the transport package from the MODX repository here: https://extras.modx.com/package/ClientConfig.
You can report bugs here: https://github.com/modmore/ClientConfig
When installing, Client Config will ask you which mode to choose:
Global mode (default) – 90% of the time you need to leave this mode, in it users can manage settings that affect the entire website.
Multi-context mode – a mode for multilingual sites (select only if you want to create a site in several languages). In multi-context mode, a context selector is added to the upper right corner of the configuration screen, allowing the user to set different values for each independent context.
Working with ClientConfig
After activating the add-on, the Configuration section will appear in the Packages section, go to it.
Creating groups and settings
On the page that opens, click the Administration button, Go to the Groups tab and create a group or several groups, for example: contacts and social networks.
After creating the groups, go to the Settings tab and add the settings:
In the pop-up cat, be sure to fill in:
- Key, on en without spaces, as a separator (if needed) it is better to specify the lowercase underscore, example: company_name.
- Name: Any – shown when filling, for example: Company name
- Field type: Text by default – suitable in 90% of cases.
- Text (xtype: textfield)
- Text area (type: text area)
- Code (type: text area with ace editor)
- Number (xtype: numberfield)
- Checkbox (xtype: xcheckbox)
- Date (xtype: datefield)
- Time (xtype: timefield)
- Selectbox (xtype: modx-combo); properties: text == value || text2 == value
You can use the Selectbox field type to simulate the boolean behavior yes || no for certain system parameters by setting the field parameters.
You can also fill in other optional fields if necessary:
- Description, shown under the field when filling in, I usually specify the field output: [[++name_polya]]
- Group: the group in which this field should be displayed
- Required setting: if the field must have a value, check the box.
- Default value: set if you know (or specify any – so that you can immediately output it to the code).
- Options: available only for a subset of field types (see field types).
Filling in the settings
Exit the administration mode by clicking on the “Show to client” button, and fill in the fields with data (if you did not set their default values when creating them) and save.
Outputting settings on the site
After creating the settings, you can call them in the code like this: [[++name_key]]
.
The settings are also available via API: $modx->getOption('name_key')
, which allows you to override system settings.
Additional
ClientConfig overwrites System Settings with the same names. This allows you to easily replace or change existinge System settings.
Check for emptiness
If you are developing a website and do not know whether the client will add specific settings or not (for example, buttons for groups in social networks), you can display them in the following constructions:
[[++name_key:!empty=`[[++name_key]`]]
Export and import of fields
All created groups and fields can be exported and imported (moved) to another or from another website. To do this, go to the administration mode. On the Settings and groups tabs, you will see the Export settings / groups and Import settings / groups buttons.
First, export the groups, then the settings in the same way.
It turns out you download 2 xml files. Then import them to the new site, first groups, then settings.
Cache control
While ClientConfig Settings act as MODX System Settings, they have different caches. Unlike System Settings, updating the processed settings may require clearing the Resource Cache. For this reason, Client Config is equipped with a “smart cache”. By default, ClientConfig automatically clears the required cache cell when updating settings. You can disable this feature in the ClientConfig system settings.