MODx Revolution for Complete Beginners Part 6 – Working with Template Variables
Welcome to Part 6 of the MODx Revolution for Complete Beginners series. In the last installment, we explored the concept of chunks. We created a number of chunks and learned how to use them to organize our template. We also mentioned a few other uses of chunks and learned their tag syntax and how to call them into the template. In this installment, we’re going to explore one of the cool features of MODx – Template Variables (TVs).
As we work through this series, we’re building a resource website for learning MODx Revolution. In the past couple of installments we’ve started the process of porting a template that we obtained from Themeforest into our MODx website and in the process we’ve learned the basics of working with templates and chunks. Our website so far looks pretty good, but it’s still a dummy site in the sense that none of the content is our content, and none of it really belongs to the website, but rather it’s all embedded in the template.
In today’s installment, we’re going to start the process of replacing that dummy static content with dynamic content that’s coming out of our website pages rather than from the template.
Working with Content in MODx Revolution
If we look at the content area of our website template you can see three regions that have distinctly separate content in them.
My goal is that by the end of this installment we will replace the content in those three regions with content that we enter in the home page in the resource tab, rather than content that is statically embedded in the template. In the process of doing this we will begin learning the basics of template variables, so let’s dive in 🙂
Creating Content in MODx Revolution
Let’s start by taking a look at a basic resource in MODx Revolution. If you go into the resource tab and open the Home resource for editing, you’re presented with several fields. We briefly looked at this in Part 4 when we assigned the Home resource a template. Let’s look at it again (remember you can click on the image for a larger view):
As you can see from this image, you have, by default, several inbuilt fields available to you. There are also more fields available under the Settings tab:
Each field has a hint that tells you what it’s template tag is as well as a brief description (for most of them) of the field. You can see these hints by hovering briefly over the field:
You can fill all these fields whenever you create a new resource, or just some of them, depending on your needs. You can then access the fields you’ve filled using the appropriate template tag. For example you could choose to use the description field for meta descriptions, and then call that field in the meta description tag in the head of your template, and so on. You will see that the Menu title field is important when we come to working with Wayfinder for creating site navigation (coming soon 🙂 )
As you can see, the default resource provides us with one main content field.
It is reasonable to deduce that this is where we, or the website editor will type in the main content that they want to appear on the site. We access the content typed in here by using the [[*content]] tag. In a simply laid out page with just one main area of content, this would be straightforward. For example if we look at the About page that comes with the template we’re working with, we can see that there is only one main content area:
Now for our home page template, we could choose to hard code those three areas into the content area by copying the html code into our resource. However, it makes more sense to me to make those three areas independent, by having each of them have its own content area. We accomplish this by using template variables.
What are Template Variables (TVs)?
Template variables are simply custom fields that you add to your template. They are specific to the template you assign the to and will not be applied to any other templates unless you assign them to those templates. They allow you to have lots of flexibility and to go beyond the supplied fields in the default resource.
Template variables, because they’re simply fields added to your resource, have the same tag syntax as the default fields: [[*TVName]].
TVs have input and output types that extend beyond simple text fields. They can be rich text regions, image fields, url fields, date fields, etc. You can even create custom TV types. But let’s not get ahead of ourselves. We’re going to touch on just the very basics in this post, and I encourage you to read more about TVs in the links at the end of this post. In future tutorials we will explore more on TVs because they’re quite powerful and flexible, but for now let’s play with the basics.
The best way to learn of course, is hands on.
We are going to use the main resource content field for area 1 in our template (see the first figure in this installment). We will then create two TVs for the other two content areas 2 and 3. Let’s first populate the region 1 with content so that we can track what we’re doing.
For reference, these are the regions again:
Open the template for editing and scroll down to find where the code and content in region 1 appears. You can also use Firebug for this. In my case, it looks something like this:
<div class="special widget_text"> <div class="sp_title_m"> <div class="sp_title_l"> <div class="sp_title_r"> <h3 class="special_title">Theme Features</h3> </div> </div> </div> <div class="textwidget"> <p><span class="dropcap">S</span>earch Engine Optimisation has been made a priority when designing the <em>Business Success</em> theme. In the code hierarchy, the main content block is placed before the sidebar regardless of the sidebar position, so it is crawled first by search engines.</p> <div style="float:left;width:50%;"> <ul class="list-2"> <li>SEO Friendly</li> <li>Easy to Customize</li> <li>Typography Styles</li> <li>Left/Right Sidebars</li> </ul> </div> <div style="float:left;width:50%;"> <ul class="list-2"> <li>2D or 3D Layout</li> <li>Unobtrusive Menu</li> <li>PSDs for All 7 Styles</li> <li>Cross browser support</li> </ul> </div> <div class="clear"></div> </div> </div>
If I now edit this so that I can replace the static content with my content tag, my code will look like this:
<div class="special widget_text"> <div class="sp_title_m"> <div class="sp_title_l"> <div class="sp_title_r"> <h3 class="special_title">Theme Features</h3> </div> </div> </div> <div class="textwidget"> [[*content]] </div> </div>
And now my page looks like this:
You can now see that region 1 is empty. This is because there’s no content in our Home resource content field. So let’s put some content in there. Open the Home resource for editing and add some content of your choice:
Save the home resource and then let’s preview our site. The text we entered in the main resource field is now appearing in the content area of region 1.
OK, so we have region 1 sorted for now. Let’s move on to regions 2 and 3. We want these to be dynamic editable content areas as well. For this we need to create two new template variables that have a rich text area input field.
Creating Template Variables in MODx Revolution
To create a template variable, go into the Elements tab, and right click on Template Variables to create a new TV. You can also click on the New TV shortcut icon.
In the template variable creation screen, there are several tabs where you can enter information about your new TV. Under the General Information tab, enter the name of the TV as well as a caption. Try to name your TVs in whichever way will allow you to remember what they’re for. The caption is important as it will guide the site editor/content creator in knowing what each field represents.
You can also add in a description if you want to.
For now we can skip the Properties tab as we have not yet discussed property sets, and we don’t need them at present.
We next move to the Input Options tab. Because we want the site content editor to be able to use the rich text editor when entering content in this field, we specify that we want the input type to be Rich Text.
Next we move on to the Output Options tab, and for now we can leave this as it is. However, if you click on the dropdown options you will see several choices (such as Date, String, HTML, etc.) which will give you ideas of how you can use this. And in future we will have opportunities to explore other output options, but for now leave it as Default.
As I mentioned, there are other input and output types that we will explore as we continue, and you can read up on them in the links provided at the end of this post.
The next step is to specify what templates you want to have access to this TV. As we mentioned above, TVs are template specific. To set this go to the Template Access tab and ensure that you select your template from the list provided and then click Save. In my case:
There are two other tabs that we haven’t looked at in that screen, namely Access Permissions and Media Sources. At this stage in our learning we don’t need to worry about them, but we will revisit them later when we need to.
If we now go back and open the Home resource for editing we will note that we now have a new tab, namely the Template Variables tab. If we nagivate to this tab we will see that our new rich text field now appears with its caption, in addition to the main content field that comes by default.
We can now add some content to our new field. In the same way, we can go ahead and create another template variable for region 3.
Duplicating Template Variables
HINT: If you know that the new TV you’re going to create is going to be very similar to one that you already have in your list, you can shorten the process by using the Duplicate TV option instead of creating a new TV.
This is so in my case as region 2 and 3 are quite similar. Simply right-click on the TV you wish to duplicate and select Duplicate TV:
In the pop-up screen that appears, edit the name of the new TV and select to have values duplicated. Your new TV will have the same template access, caption, input type, output type etc as the original one. You should go into the new TV and edit the caption so it’s relevant to the new TV, and also edit anything else you need to edit.
So now if I open the Home resource for editing and again go into the Template Variables tab, I now see that I have two extra rich content areas as desired, as well as the default content field.
So now that we have these two regions available to us (and to our website’s content editor), let’s pull them into the template so that their content can be dynamically parsed into our front page.
We need open the template and look for the code and content in regions 2 and 3 so that we know what to replace with our template tags (again we can use firebug for this). In my case I have:
<div class="cont_col_1 widget_text"> <h3 class="cont_col_1_title">B. Success Theme</h3> <div class="textwidget">You will be able to choose from 28 different transition effects for the Header Slider. Ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes. Aenean massa. Cum sociis natoque penatibus et magnis. <img style="padding-top:10px;" src="assets/templates/7in1/sample-data/b_success_logo_btn.png" width="200" height="92" alt="b-success-logo" /> </div> </div> </div> <!-- end cont_col_1 --> <div id="cont_col_2" class="column_1_of_4"> <div class="cont_col_2 widget_text"> <h3 class="cont_col_2_title">WordPress Rocks</h3> <div class="textwidget">You will be able to choose from 28 different transition effects for the Header Slider. Ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes. Aenean massa. Cum sociis natoque penatibus et magnis. <img style="padding-top:10px;" src="assets/templates/7in1/sample-data/wp_logo_btn.png" width="200" height="92" alt="b-wp-logo" /></div> </div> </div> <!-- end cont_col_2 -->
which I edit to become:
<div class="cont_col_1 widget_text"> <h3 class="cont_col_1_title">B. Success Theme</h3> <div class="textwidget"> [[*home7in1_home_contentregion2]] </div> </div> </div> <!-- end cont_col_1 --> <div id="cont_col_2" class="column_1_of_4"> <div class="cont_col_2 widget_text"> <h3 class="cont_col_2_title">MODx Rocks</h3> <div class="textwidget"> [[*home7in1_home_contentregion3]] </div> </div> </div> <!-- end cont_col_2 -->
If we now view our home page, we should see that the three regions that started out with static dummy content that was embedded in the template are now pulling content dynamically from our three content fields, two of which are new TVs that we’ve created.
For simplicity I did not worry about the columns in the first region or the images in the second and third regions, or some of the special formatting classes. You can figure those out by looking at the template code and adding the appropriate code and adding the images to your content areas using the rich text editor.
There is no limit to the number of TVs you can add to a template. I will likely go a step further and add three more TVs, one each for the title of each region, so that the titles Theme Features, Success Theme, and MODx Rocks are not static but rather can be entered from the Template variables tab. I could also just decide to use one of the existing fields, e.g. Long title, for one of the titles. It’s really all up to you and how you want to work your template.
There is of course so much more to TVs than I have covered here, these have just been the bare basics. I encourage you to dive in and explore some more about them, learn their different input and output types, read about custom TV types, and experiment. We will be running into more and using TVs again and again as we continue with our MODx series, so stay subscribed and keep experimenting 🙂
So now that things are getting dynamic in our template and we’re coming along well with our site build, I think it’s time to start adding some functional bits and pieces. In MODx, we add functionality to our site through the use of Snippets. In the next installment we will begin looking at Snippets and go on to make our site rock and roll 🙂
I look forward to your comments, questions, feedback etc. 🙂
Go to Part 7: Working with MODX Revolution Snippets