Template Variables are one of the most powerful features of MODx dynamic content generation. At their simplest, they can be considered extensions to the existing document variables, such as pagetitle, longtitle and content. Custom fields, as it were. But they can go far beyond that, querying the database or processing PHP code.
TVs are extra tables in the database, with a selection of various types of extra fields added to the document editing form as TVs are created. They also have a choice of output formatting "widgets" to control the appearance of their output in the final web page. The TV definition itself, including a default value if set, is in the site_tmplvars table. The value for each resource is in the site_tmplvar_contentvalues table. Two other tables contain the TV's template connections and its access permissions.
TVs are connected to templates (hence the name Template Variable). Any document that is assigned the same template will have the TV's extra fields in the Template Variables section below the main Document content editing area. Access to a TV can be controlled by the same security measures used to control access to documents, which will be covered in detail in a later chapter.
The order in which a template's TV fields will appear in the document editing form is managed by a drag-and-drop interface in the Templates tab of the Elements -> Manage Elements main menu item. When you select a template to edit, you will see the Assigned Template Variables tab. Opening that tab will show a list of the TVs assigned to that template. If you have more than one TV assigned to the template, you'll see a link "Edit the sort order of the template variables". This will open another page with the TVs listed in boxes. You can drag-and-drop the TVs into the order you want. This is on a template-wide basis; you cannot have the order different for different documents using the same template.
TVs are managed by three .php files in the manager/includes directory. These contain functions that are called by the parser when processing TVs.
- tmplvars.inc.php - controls the field type for adding to the document editing form.
- tmplvars.command.inc.php - processes bindings and returns their value.
- tmplvars.format.inc.php - processes output widget formatting.
TVs are a bit more complicated than chunks or snippets. The TV itself has a default value, which can take a number of forms, or even be left empty. Then each document using the same template can edit its copy of the TV to a unique value. If the document's TV field is not edited, it will use the default TV value. There is also the question of what output widgets were assigned the TV when it was created. Once the value of the TV for a given document is determined, it will be formatted according to the widget selected, if any.
TV output is positioned according to the placement of the TV tags, which take the same form as the default document variable tags; [*TVName*]. TVs can also be used as the value of parameters in snippet calls. They can be placed in templates, chunks and document content. They can be accessed in PHP code with a number of MODx API functions, most commonly $modx->getTemplateVar('TVName'), which will return the value of the TV for the current document.
If you want to access the value of a TV for a different resource, you need to use a snippet. There are several MODx API functions for accessing a TV's value, either its raw value, its processed output, or the default value. These all take a parameter to specify what resource to get the value for; by default it will use the resource currently being parsed. See the Wiki entries for more detail. Until the new Wiki is populated, you can also still find this in the old Wiki.
Creating a TV
Let's start by creating a simple custom-field type TV to hold the keywords for each document.
In the Manager, go to Resources, Manage Resources, and select the Template Variables tab. Click on the New Template Variable link. This will open the TV editing form.
There are a number of fields to fill in:
- Variable Name - this is for the name of the TV and must be matched exactly when placing its tags in your template or content. Notice that the field is surrounded with the tags that you'll be using when you call the TV. Give our new TV a name, "MetaKeywords" (without the quote marks).
- Caption - the caption that will be shown in the list of TVs and for the field when editing the document. Let's put "Meta Keywords" (again no quote marks) in this field.
- Description - again will be shown for the field when editing the document. Put something like "Put the keywords you want for this page here." (no quotes).
- Input Type - there is a select list of input type options that will be used for the form field when editing the document. They correspond to the normal form field types any HTML form can have, plus a few extras. For now, let's keep it simple and just leave it at the default of "text". Another good option for this case might be "textarea" if you expect to use a lot of keywords.
- Input Option Values - this is for use if you're using a select drop-down, or any other multiple selection field types, such as radio buttons or check boxes. We'll look a bit more closely at this later on. For this TV, we leave it empty.
- Default Value - This is for whatever you want to have all pages use if you don't edit the TV for the document. Let's add a few common keywords we might want for all of our pages; "MODx, CMS, CMF, content, management, content management, framework" (no quotes!).
- Widget - how do we want our output to be formatted. Since we're using this as the content of a meta tag, we don't want a widget.
- Sort Order - in what position do we want this TV to show in the document editing form? This is related to the drag-and-drop interface mentioned earlier. The newer drag-and-drop interface is a much better way of controlling the position of the TV, unless you can remember the position of all the other TVs for this template, and care to edit and reposition them all!
- Lock variable for editing - check this, and only a full Administrator manager user can edit the main TV. This is useful for keeping other manager users from breaking an important part of the site. Other users will still be able to edit a document's fields, just not the main TV definition here.
- Template Access - this is perhaps the single most important field in the whole form. If you don't assign the TV to a template, none of the documents in your site will ever have its field in their editing form! This is a common "newbie" error. You can check as many templates as you want to be able to use this TV.
- Access Permissions - you can assign a TV to a document group just as you can a document, and only Manager users belonging to the associated manager user group will even see the TV in the document editing form. More on users, groups, and authorization will be discussed in a later chapter.
- Category - like all the other Resources, you can assign the TV to an existing category or create a new one to keep your TVs organized. This doesn't have any effect at all on how the TV behaves, only on how it's listed in the main Template Variables resources tab. Since this TV will be used as an integral part of the template, select the Templates category (you did create that in the last article, right?).
That's all, so now save your TV.
Remember, the Input Type is for choosing what kind of field will show on the document editing form, and the Widget is for formatting the TV's output; what will show on the finished web page.
Using a Template Variable
There are two parts to using a TV. To begin with, let's place the TV where we want its output to appear on the web page. This is for having custom meta keywords for each page, so we'll want to have it in the template. If you've been following along with the other articles, you created a simple template while reading the last article. So go to the Resources, Manage Resources page and the Templates tab. Select your template to open it for editing. In the head, add a meta tag, using the TV tags of our new TV in place of its content:
<meta name="keywords" content="[*MetaKeywords*]" />
Now the default keywords will appear there for all of the pages using the same template. The next part is to edit the TV for each page.
Click on the page icon to the left of a document in the Document Tree (or right-click on its title) that is using the same template as your TV. Select Edit document from the pop-up context menu. When the document is opened for editing, scroll down past the main Document Content editing area to the Template Variables area. There you'll see a field for your MetaKeywords TV, already filled in with the default keywords we entered when we created the TV.
Edit the field to remove or add keywords. Save the document, and now when that page is being viewed on the Web, it will have the keywords you specified for that document rather than the default keywords.
Comment On This Article
Do you find something unclear? Did I miss something or get something wrong? What do you like or not like about this chapter? Please do not ask for help here; use the forums if you need help.