Creating MODX Settings in the Manager

Create and manage your own custom settings in MODX Manager.

By Bob Ray  |  January 13, 2026  |  9 min read
Community MODX CMS Tutorials
Creating MODX 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 in the MODX Manager.

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. Later in this series we'll look at some practical uses for settings.

When to Create a Setting

If you have a snippet or plugin that needs a piece of information that won't be used outside the snippet or plugin, the usual thing is to use a "property". For snippets, as you probably know, the properties can be sent in the snippet tag line this:

[[MySnippet? $somePropertyName=`someValue`]]

You can send multiple properties by sending them as a comma-separated list. You can also make the properties available as default properties, or part of a property set that's attached to the snippet or plugin. Since plugins don't have tags, you can't send them in a tag, so they should be in default properties or property sets (which are beyond the scope of this article). Note that default properties used for a MODX extra will be overwritten if you upgrade the extra, so using them is a bad idea.

When you have a piece of information that will not be limited to a single snippet or plugin, it's time to create a setting, because settings are available everywhere. We'll see some examples of uses for settings in later articles in this series.

Getting There

Here's the path through the Manager you take to create the various kinds of custom settings (see my previous article for a discussion of the various 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

The User Settings path above assumes that you are a member of the Administrator user group or at least one user group where you have permission to see the "Settings" tab when editing a user.

Setting Form Fields

Let's look at the form fields you might see when creating a new setting.

Key

This is the string that must be used in tags or other references to the setting. By convention, 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."

Very old versions of MODX don't have a name field. It's unlikely, but I have seen users who skipped a major version of MODX when upgrading (e.g. 2.3.0, 2.4.0, 2.5.0) for whom the name field was missing in your database. It happened to me once. In that case, you see a "missing database field" error message. 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.

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 over-filling it. Here are the types of fields:

  • Textfield — A single line of text
  • Textarea — Same as a TextField, but with more space to edit it in the Manager
  • 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 stored 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 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).

In some cases, the namespace name is used to locate files. This will definitely happen if you internationalize the name or description of the setting. That means that on case-sensitive filename systems, the filename's case will have to match the case of the namespace name, so making both of then all lowercase will make life easier for you.

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, a Core Path will let MODX find your language files. You may also want to use a Core Path or Assets Path in the PHP code of a plugin or snippet to let it find files (e.g. image or JS files). 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. If you want to get a head start on the next article, use mysettings for the namespace Name.

{core_path}components//mysettings/

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

{assets_path}components/mysettings/

If you create a MODX extra, the namespace name would be the name of your extra in lowercase, and "mysettings" above would be replaced by that namespace name.

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 (the box on the left) and begin typing the name of your namespace. When the namespace 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 you and any other users who will deal with the setting if you organize your setting under several areas. When you look at your settings in the grid, the settings will each be listed under their area.

Like the Name and Description fields, the Area field can be internationalized. 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 or phrase that describes the area.

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. Many 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 (including both built-in and custom settings).

Mark's extra is particularly useful for clients who need to edit settings, but might be confused by the Setting form. The extra assumes that any custom settings have already been created.

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.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.