MODX Settings in Action

Example showing the practical use of a setting


In the last article, we looked at the presenting the name, description, and area of MODX settings in several languages. In this one, we'll see some practical examples of how settings can be used to customize and personalize your site.

MODX logo

Using Settings

Because MODX is so flexible, there are zillions of ways to use MODX settings on your site — way too many to cover here. Many MODX developers (including me) tend to use settings less than they could. I've see examples in code where a developer wanted a string or number available across the site. Instead of adding a simple System Setting, the developer created a TV, attached it to a dedicated "config" resource, and then wrote a custom snippet to retrieve its value when needed. This means they ended up with an unnecessary resource, an unnecessary snippet, an unnecessary TV, and some code that retrieves the unnecessary TV value for the unnecessary resource. All they really needed was a System Setting containing the value and a tag like this:

[[++setting_name]]

System Settings are available everywhere, but the beauty of settings is that they can be tied to specific Contexts, User Groups, or Users. Any time you need to present something, or take a specific action, based on the current context, the current user, or the current user's user-group membership, a setting is often the perfect solution.


A Concrete Example

Suppose you want to let users personalize your site by choosing a theme. Ultimately, you'd like to have a page that shows samples of the available themes and a form that lets the user pick one. For now, though, let's assume that the user will email you with their choice and you'll set the theme yourself. Each theme will be a particular CSS file (which could include other CSS files in its CSS code). The theme CSS files could have different background and text colors or different styles. They could even have completely different layouts.

Since you know this article is about settings, we're obviously going to be using a setting for this, but what kind of setting will it be, what will go in the setting, and what will it be called?

Since the setting will be used to personalize the site, it can't be a System Setting, which would work everywhere. It could be a User Group setting, but it's more likely that you'd want a User setting, so each user can select the theme of their choice.

Your first thought might be that the setting should include the path to the CSS file, but it's much more convenient for everyone if the setting contains just the name of the theme. If you organize things properly, that can be very easy to implement. Let's say you've already created the mysettings namespace and given it the proper path. If you haven't, you can go back to the previous article to see how.

Next, create the custom_theme setting as described in the previous article, but make it a User Setting! There's no need to remove the System Setting if you created one, because the User Setting will override it.

  1. Go to Manage -> Manage Users
  2. Right-click on a user and select "Update User"
  3. Click on the "Settings" tab
  4. Click on the "Create New" button
  5. Use the values below for the fields
  6. Save the User!
Key:            custom_theme
Name:           setting_custom_theme
Description:    setting_custom_theme_desc
Field Type:     Textfield
Namespace:      mysettings
Area Lex entry: custom
Value:          midnight

Let's say you have three themes: midnight, lakeview, and seaview, each represented by a CSS file called theme.css. Here's a possible directory structure that will make the setting work:

assets
    components
        mysettings
            themes
                midnight
                    theme.css
                lakeview
                    theme.css
                seaview
                    theme.css

Create the three theme.css files and add code some CSS code to them that will change the look of the site so you can test the process — something like this:

p {
    color: navy !important;
    background-color: white !important;
}

Use different color and background-color values in a each theme.css file. You may have to adjust the CSS depending on your current site design. For now, anything that shows up is good.

Now, with the custom_theme setting holding one of the three theme names, you can put this tag at the bottom of the head section of your template:

<link rel="stylesheet" href="[[++assets_url]]components/mysettings/themes/[[++custom_theme]]/theme.css">

Once you've made sure that the CSS really affects the site, try creating the same custom_theme User Setting for several different users, using a different theme for each. Then log in as one of those users. You should see the CSS theme in that user's custom_theme User Setting.


Coming Up

In this article, we've seen how to use MODX settings in tags. In the next few, we'll see some examples showing how MODX settings can be used.


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)