Template variables (TV)

What is a TV template variable?

Template variables (TV fields) in MODX are a powerful tool for customizing and managing the output of information on the site. They allow you to add additional fields to resources that can be filled with various information, such as text, images, links and other data.

Each TV field has its own unique identifier and can be customized for specific types of content. For example, you can create a TV field for a page title or an image that will be displayed on the page.

One of the main advantages of using template variables is the ability to create universal templates that can be used for different types of content. For example, you can create a template for a news page that will be used for all news articles on the site. This simplifies the process of creating and editing content on the site.

Template variables also allow you to easily manage the output of information on the site. You can configure the output of a certain TV field only on certain pages or for certain groups of users. This allows you to create personalized content for different audiences.

Creating a template variable

1. Login to MODX Manager

Login to MODX admin as admin (or similar) for this to work!

2. Add a Template Variable (TV)

In the left pane of the resource tree, go to the Elements tab

3. Fill in the general information

When we define a TV, we have to define a lot of information about the behavior of this custom field. The General Info tab contains the basic information for this variable.

• Variable Name: This corresponds to placeholders that will be used in your templates, such as TableOfContents = [[*TableOfContents]]. This name must be unique!
• Caption: This is the primary label for your variable that appears when editing a resource that uses this TV
• Description: This is the secondary label for your variable
• Category: This affects which tab the variable appears on
• Sort Order: If you are using more than one TV, this will determine which ones appear on top (1 = top, large numbers move TVs down)

4. Define Input Options

Next, click on the Input Options tab: you will need to select the type of field, such as text field, drop-down field, WYSIWYG, etc. Check out Template Variable Input Types for a full list of possible input types.

• Input Type: Your field can be a simple text field, a drop-down list, a link to another page, or a variety of other types of fields.
• Input Options: Some input types ignore this field, but others may require it. For example, a drop-down list requires a list of possible values. Again, see the Template Variable Input Types page for more information.
• Default Value: This affects what the default value for the field will be. This can be a simple value, or it can use one of the MODX Bindings to do things like fetch values ​​from a database or inherit values ​​from a parent page.

5. Configure Template Access

Go to the Template Access tab: you must define which template(s) will use this custom field you have defined. Once you have defined this custom field, you can choose which template(s) can actually use it.

Every time you create a Resource that uses the template the TV has been attached to, it will be editable. Make sure you have connected your TV to at least one template.

6. Save the TV definition

When you edit a page that uses a template associated with this TV, you will be able to add data to this TV field.

7. Use this: Create a resource

Now that you have defined your TV and added it to your template, add a MODX resource (e.g. right-click in the document tree and select Creategive -> Create resource here). Select the template that uses this TV.

8. Change the value

When your MODX resource (i.e. page) uses a template that contains your template variable, you can add data to that attribute by clicking on the Template Variables tab on the page.

Usage (output in templates)

Let’s say we have a TV called bio, which is a text field TV we created. We assigned it to our “Bio Pages” template and want to display it on our page. To do this, we simply put this tag in our templates: [[*bio]]

To add a TV to a page, you must remember its template (these are Template variables, remember?). Make sure you define the TV and attach it to the template you are using. See the Creating a Template Variable page.

Advanced Usage

TVs can also have properties. Let’s say you had a TV called “intromsg” with the value:

Hello [[+name]], you have [[+messageCount]] messages.

You could populate the data with a call to:

[[*intromsg?name=`George` &messageCount=`123`]]

Which would output:

Hello George, you have 123 messages.

Output filters are also great tools to apply to TVs. Let’s say you wanted to limit the TV’s output to 100 characters. You would simply use the “limit” output filter:

[[*bioMessage:limit=`100`]]

When we say “Create a template variable”, we could be talking about two possible actions: we could be referring to the action of adding some text or content to one of the existing custom fields when editing a MODX page (i.e. a resource). OR we could be referring to the action of defining that field so that it is available to our MODX resources. This page is about the latter. In the first case, we would be creating an example of a template variable, while the second case is defining the template schema of the variable, which determines how each instance will behave.

Field Class When you create a template variable, you are really defining the class of the custom field: this acts as a blueprint for all instances of that custom field.

Advanced Usage

WHILE FILLING OUT…

You may have noticed that we skipped a fair number of tabs the first time you looked at it. Template variables offer some more advanced functionality that you don’t need for simple scenarios.

Output Options

In most cases, you want the default output, but for dates, for example, you can select “Date” and, as you’ll notice, some form fields will be displayed underneath that (depending on the Output Render you select).

Allows us to edit more detailed options for that Output Render.

Properties

From there we can specify any default properties we want for the TV. “How can you use properties for a TV?” you ask. Well, let’s say we’re making a text TV called “singSS”. In our content we have this:

View: [[+subsection]]

We can add a “subsection” list property to the grid, and then allow that property to be overridden using property sets. Let’s say we create a property set called CarsSectionTVPS (for property set). In it we set the “subsection” property to “Cars”. Then we would attach it to a TV in our resource, or template, or wherever we use it, like this:

[[*viewingSS@CarsSectionTVPS]]

This will output the TV:

Viewing: Cars

Accessing Templates and Resource Groups

We can assign TVs to Templates, too. This allows those resources assigned to those Templates to edit the TV for each resource.

Additionally, TVs can be restricted to specific resource groups, which can be selected in the grid labeled “Access Rights”.