Building a Website with MODx for Newbies – Part 6: Introducing Template Variables
Welcome to part 6 of our series of tutorials on building a website with MODx CMS. So far we’ve looked at:
As we work through these tutorials, we’re building a MODx resource site called Learn MODx. In the last installment we introduced snippets and learned how to use them to add functionality to our website. Specifically, we used the Wayfinder snippet to create a basic functional navigation system for our website. So far our website looks like this: (you can click on the images to see a larger view)
In this post, we’re going to continue to explore the basics of MODx by looking at Template Variables (TVs). We will add some more functionality and features to our site and move a step forward in our MODx knowledge.
What are Template Variables?
A Template Variable (TV) is an extra or custom Resource Field that is created by the site developer. A TV is used or displayed (via a Content Tag) to represent a value inside a template or a document. MODx allows you to have a virtually unlimited number and types of TVs. TVs are assigned to the Templates in your install. (MODx Wiki)
The TVs on a page are replaced with the actual value entered by the user when the page is displayed. TVs are called “template” variables because they can only be used in templates that you assign them to.
In this post, we’re going to create and use template variables to add custom fields to some of our MODx pages. There are many many uses for TVs, and this simple example is just one of them.
Since I am creating a MODx resource website, I want to have a section where I can list and talk about books that are useful to anyone interested in MODx, a sort of Library section. I want the pages in this section to have a basic description of the book as well as a cover image linking to an external website (such as Amazon.com) where the visitor can read more and if interested, buy the book. I could add a lot of other stuff, but for the purpose of introducing you to TVs, this will do.
Let’s start off by creating a new template for the library section. Since at this point it won’t be too drastically different from the main SwansongHome template, I’m simply going to make a duplicate of the SwansongHome and rename it.
In the admin backend of your MODx website, go to Resources -> Manage Resources -> Templates, and click the SwansongHome template to edit it. Once it’s open, click on the Duplicate option at the top:
Once you select this, the new template will be created and you just need to change it’s name and any other pertinent information. For now, the code will remain the same:
I’ve renamed the template to SwansongBooks. So far so good, we can now save this template.
So we know that we’re going to be listing a number of books using this template, and each book will go in it’s own page. For purposes of organizing and aggregating (coming in the next post 🙂 ) our book information, we will need to group our documents under a parent document, or in a “container”. In MODx, a container is simply a document under which other documents are grouped (kind of like a folder, except the folder is actually just a document – confused yet? 🙂 ).
OK, let’s do this. Let’s go ahead and create a new document and call it “Library”. This document will use the SwansongHome template, have an alias of “library” and have no content in it’s body for now.
Make sure to uncheck the “Show in Menu” for now, since it’s just going to be an empty container.
So now in our document tree we have a new page “Library” with an ID of 6 whose content is blank. I’m going to leave it unpublished for now.
Let us now create a new document under Library, where we will put in the details of our first book. To do this, right click on “Library” and select “Create a Document Here”. This will create a “child” document.
The first book I want to add is, fittingly enough, the MODx Web Development book. So the title of the new document will be MODx Web Development, and the other settings as below. Assign it to the new SwansongBooks template. For now I will borrow some text from the book’s webpage for the content section. Be sure again to uncheck the Show in Menu box, since we don’t want this in the menu.
You’ll notice from the screenshot above that I’ve put some text into the Summary (introtext) area. This will come in handy later. Save this document,and you should now see that “Library” has a little + next to it, indicating that you can expand it. If you click on the + sign you can now see the new document we just created.
Let’s go ahead then and preview our new document (right click and select Preview). It should look pretty much like any other page we’ve created since we haven’t added anything different to the SwansongBooks template.
Let’s now think about how we’re going to add the book cover image to this page and others like it. We want the image to be clickable, so this means we need two extra input fields – one for the image and one for the link. Let’s go ahead and create two template variables for that purpose.
Go to Resources -> Manage Resources -> Template Variables
This is the page where you create and have your TVs listed. At the moment we have no template variables for our site, so go ahead and click on “New Template Variable” to create a new TV.
We’re going to name our TV “bookImages”, and it’s input type is naturally going to be an Image.
For now I’m going to leave all the other stuff blank since this is a simple basic introduction and demonstration. There is PLENTY you can explore about each of the input types that would take a blog post of it’s own. For now, it’s enough to know that our TV doesn’t have any default values, nor will it use any data bindings, all topics we will explore in the future.
If you’re going to directly display your input, you need to specify a widget type. In this case, for my purposes I don’t need an output widget since I’m going to use a different method for my output.
Template Variable Output Widgets make it easier for users to add special visual effects to their web sites in a matter of seconds. With just a few clicks you can add a Marquee or a Ticker to scroll or change content on your website, a Data Grid to display a formatted table of data from a file or a database, an always-present floating display box and more. Again, too much to go into in this post.
Assign this template variable to the SwansongBooks template and to the swansong category, and for now that will do. Save the template variable.
Go ahead and repeat the process to create a second TV for the link. Call it ImageLink, have it’s input format be “url” and don’t assign it any widget. Remember again to assign it to the SwansongBooks template and swansong category and save it.
Cool, so now we have two new template variables and we’ve assigned them to the SwansongBooks template. If we now create or edit any documents that are using that template, we should see two new input fields, one for the image and one for the link. Let’s open the MODx Web Development page we created for editing and scroll all the way to the bottom:
You can now see our new fields at the bottom. Since I have two pieces of information that I want to present as one, I’ve decided to use a chunk to output my information.
To do this, I need to create a new chunk, which I will call bookChunk. I will assign it to the swansong category. With the TinyMCE editor selected (at the bottom left corner of the text editor), I am going to upload an image to the editor and assign it a link. You can completely bypass this step but I’m using it so I can have my markup working before I add my TV placeholders.
I already have a book cover of the MODx Web Development book on my desktop, so I’m going to upload that and then select it and add the page link to it. In the upload dialogue, when you click on the icon at the end of the Image url field, you’re presented with the image browser. I have created, using this browser, a folder called “BookCovers” for all my book covers.
Once this is done, and I can see my book cover in the chunk, I will now save it, insert the chunk in SwansongBook template, and test it to make sure it works.
Open SwansongBook template and place the chunk call just above the [*content*] tag, and then save it.
If we now preview our MODx Web Development document that uses the SwansongBooks template, we should see the book cover above the main page content, and your image should be clickable taking you to the link you specified.
You may notice though, depending on your source image, that the image may be too large. Mine is, it’s actually covering the sidebar. I need to scale it down, and you can do this before or during the upload, to a preset size. I am not too concerned about styling right now, so I will scale it down in the html in the chunk.
OK, so we know the code for our image works, let’s go ahead and replace the links with the template variables so that whenever this chunk is called, it displays the relevant information for the document calling it.
Open the bookChunk for editing, and turn off the TinyMCE editor (toggle it to none). This should reveal the code.
We are going to replace the url to our image with our TV tag [*bookImages*] and the link to the book website with our TV tag [*ImageLink*]. (I apologize my naming wasn’t very consistent 🙁 ).
I am also going to put [*pagetitle*] in the title and alt attributes since the title of the document is the title of the book, so that works (remember this tag from our templating tutorial?). I’ll also add a border=”0″ to remove any borders.
Finally, to resolve my size issue, I am going to scale my image down to 75% of its original size. This is probably not the most optimal way to do this and will affect my other images, but as I mentioned before, I am not too concerned about styling at this point. I will probably need to go in later and add some more styles to this template, probably add a div for the book images and float them… etc. For the purposes of this tutorial, ignore my heathen ways and just focus on the TVs 🙂
Alright, so my code in bookChunk will go from:
<a title="MODx Web Development" href="https://www.packtpub.com/modx-web-development/book" target="_blank"><img title="MODx Web Development" src="assets/images/BookCovers/MODx_Web_Development1.jpg" alt="" width="406" height="502" /></a>
<p><a title="[*pagetitle*]" href="[*ImageLink*]" target="_blank"><img title="[*pagetitle*]" src="[*bookImages*]" alt="" width="70%" height="70%" border="0"/></a></p>
Alright! Let’s now save the chunk and preview our page. There should be nothing there because we need to edit the document and add our link and image so that the TVs can pick them up and display them in our chunk.
Open the MODx Web Development document for editing, scroll down to the bottom, and using the two new TV fields, insert your image and link.
If we now preview the page, we should see something like this:
And if you click on the book cover, it should take you to the web page for the book.
There’s a lot more that we can do with this. We could add more TVs to this template and do a lot more, but I hope that this is good enough for a start and to give you a good idea of what MODx template variables are and what you can do with them.
Remember that this is a basic beginner’s series, so we have really only just touched the surface on the concepts covered here, so be sure to visit the more reading links at the end of the post to expand your knowledge. And don’t forget to grab your copy of the MODx Web Development book.
In the next post we’re going to continue working with our library section, publish and make the book pages accessible to our site visitors, and explore some more MODx functionality and power.
In the meantime, go ahead and add a few more pages to your library section, see if you want to play with some styling to make it more visually appealing, and hang tight till our next post.
As always, please feel free to leave a comment, say hey, ask a question, offer suggestions or corrections, but don’t leave spam – my plugins will catch it 🙂 etc.