It's usually easier to create settings in the Manager, but suppose that you're creating an extra. In that case you won't have access to the Manager when the extra is being installed. You'll need to create the settings in code in a resolver for your package. We'll look at how to do that in this article.
When you're creating settings in a package, they're almost always System Settings, so we'll look at those first.
Creating System Settings in Code
Here's the basic code to create a System Setting:
$fields = array( 'key' => 'setting_key', 'name' => 'setting name', 'description' => 'setting description', 'xtype' => 'type code', 'namespace' => 'namespace name', 'area' => 'area name or Lexicon Key', 'editedon' => '', 'value' => 'setting value', ); $setting = $modx->newObject('modSystemSetting'); $setting->fromArray($fields); $setting->save();
The only parts of the code above that need to be edited are the values of the 8 array members.
This is simply the key you want to use to identify the setting. It will be used in any setting tags. The key usually contains only letters and underscores.
This is the name that will be displayed in the Manager when the System Setting is edited in the grid. The field contains the name itself if you will only be showing it in one language.
If you you would like to display the setting name in more than one language, this should be setting_ + key. So if the setting is
site_start, the name would be
setting_site_start. Then, you'd create a lexicon string like this:
$_lang['setting_site_start' = 'Full Name of the setting';
If the line above were for the English version, it would go in this file (with "namespacename" replaced by the actual namespace):
For other languages, the filename would be the same and so would the path except for the two-letter language code.
This is handled just like the name. If it's only one for one language, just set the field to your description. If you need to translate it, set the description field to setting_ + key + _desc. So, for example, the description for the
site_start setting would be
setting_site_start_desc. Then, in the same language file described for the name, you'd place a line like this:
$_lang['setting_site_start_desc' = 'Full description for the setting';
Here are the possible setting types and their equivalent xtype codes. It's the value on the right you want to use in creating the setting:
- Textfield — textfield
- Textarea — textarea
- Yes/No — combo-boolean
- Integer — numberfield
- Password — text-password
- Category — modx-combo-category
- Charset — modx-combo-charset
- Country — modx-combo-country
- Context — modx-combo-context
- Namespace —modx-combo-namespace
- Template —modx-combo-template
- User — modx-combo-user
- User Group — modx-combo-usergroup
- Language — modx-combo-language
- Source — modx-combo-source
- Manager Theme — modx-combo-manager-theme
Notice that all of the actual DB values are all lowercase. Most of the time, you'll be using one of the first three. Even numbers are usually stored in a Textfield because MODX generally passes properties, settings, and snippet return values, as strings.
Looking at the field names above, you might think that you could also use
modx-combo- followed by another MODX object name, minus the "mod" prefix, such as
modx-combo-snippet. Unfortunately, the values above are hard-coded in the MODX core code. Using any other value will make the System Settings table grid page hang indefinitely.
The namespace to associate with the setting (not to be confused with the
namespace xtype listed above). This is kind of like a category for things like settings, Manager actions, Dashboard Widgets, extension packages, lexicon entries, and menu items, though unlike a category, it also comes (optionally) with a core path and assets path that MODX can use to look for things like processors and lexicon files.
This value must be the name of an existing namespace listed in System -> Namespaces. If it will be a custom namespace, you'll have to create the namespace before the setting is created. If this is part of a transport package, the package itself will have a namespace that will be created before any resolver runs, so if that is your namespace for the setting, it will be save to use it in the resolver.
This is optional. It's used only to organize the settings in the tree under areas.
If you want to display the area name in more than one language, use the
area_ prefix on the lexicon string (in the setting.inc.php file described above. Do not use that prefix on the area field you put in the array to create the setting. MODX will add the prefix when it goes to look for the lexicon entry.
Creating the setting is not considered editing it, so this field is usually left blank. MODX automatically updates it to the current date and time whenever a setting is updated in the Manager. It won't hurt anything to set it to the current time if you want a record of when the setting was created, though again, it will be overwritten if the setting is ever changed in the Manager. You can set it to the current date and time like this:
'editedon' => time(),
This is the value you want the setting to have. When you use a setting tag for this setting, it will be replaced by this value.
In the next article, we'll look at creating Context Settings in code.
Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)