In the last article we looked at how to create User Group Settings in code. In this one, we'll see how to create User Settings in code.
As you might guess, this is very similar to creating System Settings. I've left the information on System Settings below, so you don't have to look back to another article.
Creating User Settings in Code
This process is identical to creating System Settings (see below), except for the name of the object being created (modUserSetting
), and the addition of the user
field. This field is required for creating User Settings. It must contain the ID of an existing User.
Use this in place of the $fields
array listed below. Otherwise the code will be the same.
$fields = array( 'user' => userId, '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', );
Notice that the userId (which should be a number) does not have quotes around it. It should be an integer.
Use this in place of the newObject()
line:
$setting = $modx->newObject('modUserSetting');
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.
key
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.
name
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):
core/components/namespacename/lexicon/en/setting.inc.php
For other languages, the filename would be the same and so would the path except for the two-letter language code.
description
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';
xtype
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-chunk
or 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.
namespace
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.
area
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.
editedon
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(),
value
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.
Coming Up
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.)
Comments (0)
Please login to comment.