Creating MODX Settings

How to create new System, Context, User Group, or User Settings in the Manager.


In the last article, we looked at the MODX settings hierarchy and how settings at different levels can override other settings of the same name. In this article, we'll see how to create and use your own custom settings.

MODX logo

Custom Settings

You've probably already used the standard System Settings that come with MODX — things like site_start and friendly_urls. You may even have created Context Settings, User Group Settings, or User Settings that override settings lower on the priority list. The fact is, though, that you can create your own custom settings to hold any values you want to be available across the site. They could be System, Context, User Group, or User Settings, depending on your needs. You could use a setting, for example, to let users pick a CSS file to use for the site or to show different users different chunks.

We'll look at how to create the settings in this article. In the next one we'll look at some practical uses for settings.


Getting There

Here's the path through the Manager you take to create the various kinds of custom settings:

  • System Settings — System (gear icon) -> System Settings -> Create New Setting button
  • Context Settings — System -> Contexts -> right-click on Context -> Update Context -> Context Settings tab -> Create New button
  • User Group Settings — System -> Access Control Lists -> User Groups tab -> right-click on a group -> Update User Group -> Settings tab -> Create New button
  • User Settings — Manage -> Users -> right-click on a user -> Update User -> Settings tab -> Create New button

Setting Form Fields

Key

This is the string that must be used in tags or other references to the setting. It's not required, but typically the key is in all lowercase and words are separated by an underscore character like this: setting_name. Setting keys shouldn't contain any spaces.

Name

This is a plain language name for the setting. It is arbitrary and is only used when creating or updating a setting in the Manager. The name for the site_start setting, for example is "Site start."

Earlier versions of MODX don't have a name field and if you skipped a major version of MODX when upgrading (e.g. 2.3.0, 2.4.0, 2.5.0), this field may be missing in your database. See this article for more information.

The name field can be internationalized if you need it to appear in more than one language. We'll see how to do that in the next article.

Description

Notes on the purpose and usage of the setting. Like the Name, this field will only appear in the Manager. If you only need this in a single language, you can just type it into the Description field. If you need to present the description in more than one language, though, it's a little tricky. We'll cover the method for that in the next article. For now, use setting_, plus the key, plus _desc in the Description field. For a setting called page_count, for example, you'd put this in the Description field: setting_page_count_desc.

Field Type

Like element properties, settings have a number of different input types, though the list is different from those available for properties (and it's much longer). This is true for all four types of settings. MODX may limit the number of characters you can enter for the value of some types of fields, but the value field in the settings table in the database will hold 65,535 characters, so there's little chance of filling it. Here are the types of fields:

  • Textfield — A single line of text
  • Textarea — Same as a TextField, but with more space
  • Yes/No — Presents a drop-down menu with the options Yes and No. What's actually stored is 1 (for yes) and 0 (for no)
  • Password — Same as a TextField but all characters appear as asterisks. The value is stored as plain text in the database
  • Category — Presents a drop-down menu of all the categories on the site. What's actually stored is the ID of the selected category
  • Charset — Presents a long list of character sets. What's stored is the database is the short code for the charset. For example, if you select Unicode (UTF-8) - utf-8, the value field will hold UTF-8
  • Country — Presents a long list of countries. What's stored is the short code for the country, e.g., US for United States
  • Context — Lists the contexts on the site. What's stored is the context key (e.g., web or mgr
  • Namespace — Lists the namespaces on the site. What's stored is the same as what is selected: the name of the namespace
  • Template — Lists the templates on the site. What's stored is the ID of the selected template
  • User — Lists all users on the site. What's stored is the ID of the user
  • User Group — Lists all user groups on the site. What's stored is the ID of the user group
  • Language — Presents a list of language codes (e.g., en), what's store is what is shown
  • Source — Lists all the Media Sources on the site. What's stored is the ID of the Media Source
  • Manager Theme — Lists all the Manager Themes. What's stored is the same as what's shown

In all cases where a list is presented, the setting tag will be replaced by what is stored in the value field of the database record, not necessarily what appears on the list.

Namespace

The Namespace that this Setting is associated with. If you will be creating one or more custom settings, it's not a bad idea to create your own namespace, just to make them easier to find. If you don't, your setting will be attached to the core namespace. That namespace is is for the MODX built-in settings, so yours doesn't really belong there. To create a namespace, go to System (gear icon) -> namespaces -> Create New button. Typically, namespace names are all lowercase and contain nothing but letters (no spaces, hyphens, or underscores).

When you create a namespace, the form will ask you for the name, which is required (it's the primary key for the namespace). It will also ask for a Core Path and an Assets Path. These are optional, but if you want to internationalize the name, description, and/or area name of the setting, you'll need to enter a Core Path. Use the following exactly as written. Don't put a slash after {core_path}: and don't forget the trailing slash at the right end. In order to get a head start on the next article, we'll use mysettings for the namespace Name.

{core_path}components/mysettings/

As long as we're here, we should add an Assets Path as well in case we need it later on:

{assets_path}components/mysettings/

Once you've created your namespace, put its name in the "Namespace" field when creating any new custom settings.

To find your settings in the grid (e.g., the System Settings grid), click on the "Filter by Namespace" dropdown and begin typing the name of your namespace. When the fill name appears, click on it and you'll be looking a just the settings in your namespace.

Area Lexicon Entry

This field is optional, and its name is a little confusing. You can use it for the name of an area under which the setting will be organized. If you only have one or two settings, you can leave this field blank. If you have lots of settings, though, it will make it easier for the user if you organize them under several areas.

If you only need the area names in a single language, just type them into this field.

If you need to internationalize the area names, see the following article where we'll discuss how to do that. For now, just enter a short word that describes the area. That will serve as the key for the lexicon entry. We'll look at how to create the lexicon string for that key in the next article.

value

You might think that this field holds the raw value for the setting, and in the database, it does. In the form, however, if there is a drop-down list for the value, what's shown in the field is the string from the list, "Unicode (UTF-8) - utf-8" for example. When you use a tag to retrieve the value, the tag will be replaced with what's stored in the database. In this case, that's "UTF-8". See the list of field types above for more information on what's stored in the database for each type.


Wrapping Up

Creating custom settings may seem complicated, but it's not as bad as it sounds. Once you've done a few, it's very easy. Almost all custom settings are either Textfield or Yes/No settings. I should also mention that if you have settings that need to be modified often (either built-in MODX settings, or custom ones of your own), it's nice to have Mark Hamstra's excellent ClientConfig extra, which provides a nice interface for setting their values.


Coming Up

In this article, we've seen how create custom MODX settings. In the next one, we'll look at presenting setting names, descriptions, and areas in multiple languages.


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.

  (Login)