MODx Revolution for Complete Beginners Part 4 – Working with Templates
Welcome to Part 4 of the MODx Revolution for Complete Beginners series. In the last installment, we did some basic site configuration and looked at how to set/change global site settings such as the site name, and all that. We also explored how to install extras from the MODx repository using package management. In this post, we’re going to start looking at how to work with templates in MODx Revolution. We’re going to start with a static HTML/CSS template and, over the next few installments, transform that into a MODx Revolution template.
What are MODx Templates?
MODx templates are simply HTML/CSS templates with MODx tags inserted for dynamic functionality. This is a very simplistic definition, but in my mind it captures the essence of what a MODx template is. If you know how to code HTML/CSS or can get your hands on a coded HTML/CSS template, the rest is easy. This one aspect makes MODx very designer friendly.
For the purpose of this tutorial, I have decided to source a theme from Themeforest for my site. If you want to follow along directly you can download this same theme (which I have now provided here as it’s no longer available on Themeforest) and work with me or you can use any template of your choice, whether one you’ve designed and coded yourself, or one you’ve downloaded from the web (searching Google for ‘free css templates’ should give you a good selection to start with). The principles will be the same, and if you have some knowledge of HTML/CSS what I am doing in this tutorial and the ones following should be similar in implementation to any template you pick.
Disclaimer: The themeforest links on this post are affiliate links, so if you make a purchase from clicking on them I get a few pennies, which helps me keep running this blog.
The template that I will be working with on this site is the 7 in 1 Business Success Site template. I picked this template because it looks good and is simple but yet complex enough to make it interesting to port into a MODx website. Additionally, it comes in 7 different color styles. I will use the blue, and you’re free to choose whatever color you want. So let’s get started!! 🙂 Remember that as we’re working through these tutorials we’re building a live site, a resource site for learning MODx Revolution, but should you work through these tutorials at a later date I am adding a lot of screenshots as you go so you can see the work in progress.
The first thing I want to mention is that the method I will follow here is my own method/system of setting up templates in MODx. It’s not the only way, nor is it the best way, it’s just my way. MODx doesn’t restrict you in terms of where to place your files, how to break down your template, etc etc. It’s up to you, what you’re more comfortable with, or what your client wants. So keep in mind as you follow along that this is not set in stone, you can play around with it and make it work for you the way you want it to.
1. Upload the Template Files and Assets
Any template you use will come with assets – css files, js files, images, flash files, etc. These need to be stored somewhere on your server so that your template can access them. My personal preference is to store all template assets in a template folder inside the assets folder. Again, you could really put these anywhere and just set the paths accordingly in your template.
On unzipping the template files, the file structure looks something like this:
So the first step is to upload the three asset folders, sample-data, scripts, and styles to the web server. I have created a folder named templates inside the assets folder, and to that I have added a folder titled 7in1, into which I upload the three assets folders referenced above. So if we now look in the site manager, under the Files tab, we can see the new folders and files that I have uploaded:
The files are now accessible to any templates we build, and remember that you can store these files in any folder you want, or even one that you create outside of the existing folders. I just prefer to use the assets folder.
2. Create the Template
Now that our template assets have been uploaded, we can now begin the process of creating the template in MODx. In the backend, click on the Elements tab on the left, this reveals the various site elements – templates, chunks, template variables, etc. Clicking on templates reveals that there is one template available, called the Base Template. If you click on it, you can see that this is a very basic template which, as you can see, is just some straightforward HTML code with some tags (e.g. [[++site_name]], [[*pagetitle]]) added to it.
These types of tags are what transform the static HTML/CSS code into a dynamic MODx template, and we’re going to be learning about them hands on, as we build out our site.
So let’s go ahead and build our template. To create a new MODx Revolution template, right click on Templates and then on New Template.
In the new template screen, give your template a name and a description. You can place it in a category to keep things organized on your site. Again how you organize your site elements is entirely up to you. I usually have a main templates category where all the templates and chunks related to the templates sit, and then another for nav items, and so on. But you can organize it however you want. To create a category, just right-click on Categories in the Elements tab.
So now we’re ready to add the code to our new template. We’re going to start by creating the home page template. I can tell that the layout of this page is going to be very different from that of the inner pages, so we’ll give it it’s own template which I call 7in1 Home. The code for the home page is in the index.html file in the template folder we downloaded from Themeforest, so we open that file in a text editor and copy its contents into our newly created template in MODx. Before we copy it though, Note that you can do all your initial editing outside MODx and then port in the edited template, but for the purposes of this tutorial we will do all of our editing inside the MODx editor.
3. Edit the Paths
With the code in place, let’s start by editing all the paths. Recall that we placed our template assets in the assets/templates/7in1 folder. So we need to change all references to css files, js files, images, etc. to the correct location on our server. This, as you will immediately deduce, might be one of those things that are best accomplished before pasting your code in the MODx editor. So for example, just glancing at the code I can tell that I need to search for styles/ and replace it with assets/templates/7in1/styles/, and similarly replace scripts/ with assets/templates/7in1/scripts/, etc. So go ahead and do all the path replacements, and then save your template. You may find that after viewing the page you’ve missed some and you just need to go back and correct them.
4. Assign the Template
Now that we have the beginnings of the porting done, let’s assign this template to a page and see how we’re doing. To do this, we go to the Resource tab and open the resource we want to assign the template to (in this case Home). If you click on the field “Uses Template” you should be able to see and select the new template we just created.
Once you select the template, you’ll get a message asking to confirm that you want to change the template. The importance of this will become clear down the line as we build different templates as each template will have different chunks and template variables and will be laid out differently, so you want to be sure that you’re picking the correct template for the resource you’re editing.
Once we click save, we can now preview the page and see what it looks like. Here’s a screenshot of just the top part of the page:
And here’s a shot of the bottom part:
As you can see, our site is starting to look like we want it to, with just replacing the paths so that the template sees our assets. However, the content, title tag, navigation items, etc are all still static, so the next step is to start inserting tags to begin making our template see the MODx stuff.
5. MODx Revolution Tag Syntax
To start working on making our MODx Revolution template dynamic, we need to work with MODx tags. MODx provides different tags that you can use to create and add variable content elements on your site. The full list of MODx Revolution tags is available in the documentation (see link at end of post). If you have used MODx Evolution before, you will understand the concept of tags, but you do need to check the documentation for the new syntax.
If you have never used MODx before, don’t worry, we are going to learn how to use these tags as we work through our site and by the end you should have a pretty solid grasp of what they are and when and how to use them. For now the table above is a nice reference from the documentation that you can refer to if you need a reminder of the syntax or of what tag is used for what content element.
In this installment we are mostly going to utilize the system settings tags.
6. Change the MODx Revolution Site Title
The first thing we want to do is to change the title tag of the site so that it reflects the name of our site, and not the name of the template as it is now:
To change this, we simply need to go to the title tag and replace the existing tag with a system tag. So looking at the <head> element of our template:
<head profile="http://gmpg.org/xfn/11"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Business Success</title>
We simply need to replace the text Business Success in the title tag with the system setting tag that will parse the actual site title from our system settings. So go ahead and replace Business Success with [[++site_name]]. While we’re in there, we can change one more thing. The charset is also defined in our site’s system settings, so we can plop that in there too so that it’s parsed dynamically. So replace UTF-8 with [[++modx_charset]]. So the code section above will now look like this:
<head profile="http://gmpg.org/xfn/11"> <meta http-equiv="Content-Type" content="text/html; charset=[[++modx_charset]]" /> <title>[[++site_name]]</title>
Save the template and preview the page, and you will now notice the change in the site title, that it now reflects our site name.
Additionally, if you view the code, you will see that the MODx parser has picked up on our site settings for the charset and inserted the correct charset dynamically. It just happens to be the same as what was on the template, but it’s being parsed dynamically and is not just a static value.
One very important thing that we need to add to the head element of our template is the <base> tag (see More Reading at the end of this post). We use the base tag to specify the default address for all links on the page. So in my case I could make the following change to the head element:
<head profile="http://gmpg.org/xfn/11"> <meta http-equiv="Content-Type" content="text/html; charset=[[++modx_charset]]" /> <base href="http://learnmodxrevolution.maryspad.com/" /> <title>[[++site_name]]</title>
This would be fine and would work, but again, instead of hard-coding the url in there like that, it’s better to make it dynamic and instead use a system setting tag. So then I make the following change to the code:
<head profile="http://gmpg.org/xfn/11"> <meta http-equiv="Content-Type" content="text/html; charset=[[++modx_charset]]" /> <base href="[[++site_url]]/" /> <title>[[++site_name]]</title>
If we now view source for the page, you can see that the MODx parser again is able to pick up and parse the correct url for the site:
Well, that’s it for now. We’ve made some good progress and now have the beginnings of a MODx template. We have seen an example of how to set things up, created a new template, added it to a category, and then started adding MODx Revolution tags to begin transforming our static template into a dynamic MODx template.
In the next installment, we’re going to continue the process of making our template dynamic. We will talk about chunks, what they are, how to use them to simplify and organize our template, and more. So stay tuned, subscribe to the Coding Pad RSS feed, and let’s continue learning MODx Revolution
If you have any questions or corrections or just want to say hey, please feel free to drop me a note in the comments below. And remember to visit Themeforest to explore the selection of templates on offer.
Go to Part 5: Working with MODX Revolution Chunks