MODx Revolution for Complete Beginners Part 4 – Working with Templates

Welcome to Part 3 of the MODx Revolution for Complete Beginners series. In the last installment, we went through the step by step process of installing MODx Revolution. In this post, we’re going to do some basic site configuration. We will also explore installing extras from the MODx repository. This post will just cover the basics, and you will find that as you explore more the Revolution Manager has a lot of options to configure, but we’re just going to look at the basics and then return to different parts of the manager and explore them as we need to interact with them.

So far:

Part 1: Introduction

Part 2: Installation

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.

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.

You can also use click on New Template icon:

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:

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:

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:

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:

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.

What’s Next?

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.

53 Comments

Hi and thanks for this great Tutorial. I would like to see a detailed tutorial on the form customization. It’s nearly impossible for me (a Designer) to do the same like we did with the ManagerManager-Plugin in Evo. It’s the only reason why I stay with Evo.

Hi Mary, after being distracted by so many CMS, I’m hoping to buckle down and port this free news magazine theme to MODx:http://www.os-templates.com/free-css-templates/4
The only thing they require is leaving in a footer link.
Great timing, I’ve been trying to decide Revo or Evo? It seems there are always distractions to coding, which CMS which version yada yada.
Hey thanks alot!

Thank you so much for your time and effort with these evo tutorials. Is there any chance you will be continuing them? And if not, would it be worth while to just watch the revo ones, even though im using evo?

alan,
thanks for the feedback. I am steadily building up the Revo series, although time is always an issue. I think it’s worth watching the Evo screencasts as long as you understand the tag differences and manager interface parallels with Evo, but I AM working on a series of Revo screencasts and will hopefully start posting them in the next week or so, time permitting.

I’m trying to put in place a horizontal menu, oddly I have no trouble doing so in evolution, but revolution is killing me. I just cannot seem to get it working.

I’d like to suggest that you do a screencast of creating and installing a horizontal menu system for revolution as there is none on the web (there is a nice user manual for wayfinder from evolution and there is muddy dogpaw (awesome but lacking in basic educational communication and howtos’)).

I’ve asked you questions in the past and found your replies comprehensive and communicative in a “I speak the language of mortals sort of way” so hope that you might conisder it…

The Revo base template that comes with the Revo install already has those title tags in place. In my tutorial, I am working from a static HTML/CSS template, hence I need to replace the static bits in the title tag with the dynamic MODx tags.

Jeffrey
Depends on what your setup is. I usually zip up the folder, upload it, and then extract it on the server, that way I don’t have to upload one file at a time. It’s faster and uses up less bandwidth, but your server needs to be able to support unzipping archives.

Jeffrey,
If you’re using MAMP I assume you’re working locally, on your computer? If yes then it should just be a matter of moving the folder over using Finder. If you’re working on a remote host, see Crrsp’s response below.

If you have hosting with a control panel, when you use the file directory, and add a file, by uploading a zip box… there will be a check box whether you want the file to be extracted.
You’ll want the zip folder to have it’s contents contained in one folder at the root of the zip file, if you don’t want all those files distributed to the current level, where you uploaded the files.
alternatively you could create a directory, then upload the zip and have it extracted into the directory you created.

A minor point. When you add the , I think you should remove the slash immediately preceeding the double quotes, otherwise your view source shows the site address with // at the end (which your example does not, so I guess you picked it up).

Hello Mary! I’m from Russia and i love your blog! In Russia we haven’t many information about Revo, only Evo and your blog help me to learn this CMF. Thank you for your work Mary! Good luck in the next articles about Revo

ojchris
I presume you’re referring to the manual download method? The error means you may have a corrupted download. I would attempt to redownload, and make sure you’re downloading the correct version.

Hi Mary,
I have a question about these “dynamicizing” MODx tags: I understand how certain things are better made dynamic (like navbars and content etc) but why would you make the site title or charset or base URL dynamic?

The way I understand it, static content loads faster because dynamic content creates more server requests. So if I’m not planning on changing things like the base URL, then wouldn’t it be better to leave them static?

Adi
Making site title and charset or base url dynamic comes in really handy if somewhere down the line you change hosts, or change something in your site configuration, or decide you want to use a different title for your site, or your internationalize your site and find you need to use a different charset, etc. Then it’s really handy to have all these settings in just one place instead of changing it on every template or chunk or whatever. It’s just good practice to separate settings from the site, and it makes site maintenance a whole lot easier. You can leave them static if you want, no problem, it’s also a matter of preference. But I personally think it makes things cleaner and easier to make them dynamic.

Thanks for all of your tutorials this one especially it finally has gotten me started. At the end of it you say (In the next installment, we’re going to continue the process of making our template dynamic) but how do I find the next installment and how many tutorials are there?

1) when I switched the ‘Home’ page template from the BaseTemplate to the CustomTemplate, and then tried to preview it, the preview did not update – because MODX was using the cached version of the page. In my setup, after changing the page’s template, in order to see the changes I have to ‘Clear Cache’ for the site, first. It may be worthwhile mentioning this in the tutorial, so other newbies like me don’t feel too lost, if they come across the same problem.

2) The “++site_url” tag seems to be a “system setting” – I’m guessing this because of the “++” on the tag. Nevertheless, when I search the System Settings list, it is not listed anywhere… Confusing… Does that mean that there are ‘hidden’ settings that are set automatically? If so, how do we find out what they are?

Once again, many thanks for such an easy-to-follow guide. Please, keep up the good work, it’s appreciated!

Bob
I actually have not used or explored the MODX Revolution sample site. In these tutorials I do start from complete blank slate so if you want to follow them step by step you would need to only have a clean installation with no sample site.

You could do two parallel installs since it’s only experimental, one with the sample site so that as you learn the different parts you can go in and see and understand how the sample site was built, and one blank one for these tutorials.

Thanks Isaac. I will take a look at that theme. I plan to update this series soon and will probably pick a different theme, one that I can attach to the series and that will remain available and not disappear 🙂

Was working thru your tutorial on templates. Using Modx Revolution v 2.5.7. I dowloaded the 7in1 template you linked to: it’s quite complex. I extracted it and then made a Zip archive with it’s 3 directories that you’ve shown + the 10 or so files.

However, using the Modx Rev manager I can upload the file but I cannot extract from a zip. I guess I need to execute some sort of terminal command to do this on my site? I put it in /assets/templates/7in1/
I can also recreate the directory structure and upload all the files without the need for a .zip but that’s very tedious.

Last year I hired a developer to work on my site. They did install the Modx but little else. While I can pay for some support I don’t want to spends thousands of $ and not get anything working.

Hi Julius,
I don’t believe you can unzip from the MODX file manager. Instead, you probably want to do this from your hosting account’s file manager, for example if your hosting account is on a cPanel platform you can log into cPanel and use the unzip utility in the file manager. If you have SSH access to your site that’s another way to do it – log into your site using SSH and then navigate to where your zip file is and unzip it. Uploading the files individually is very tedious and time consuming, I agree. Try one of the methods i have outlined and don’t hesitate to reach out if you have further issues.

Actually I hadn’t even thought of that. I’m used to using FileZilla for SFTP and was able to upload the 3 directories & the files for the 7in1. I stuck it in assets. My developer uploaded a WordPress template {bought thru my Envatio account} months ago so there are template files all over the place but I have no indication that that one works.

An update, Surprisingly enough it worked !!! However this template with the modern rounded buttons isn’t the effect I’m looking for. This is the 1st time I’ve ever used a template for anything. Now I just need to figure out how to get the target look.

It would be perhaps easier to edit in an outside editor with global search & replace tho…

Thanks very much for the tutorials- they really are extremely helpful: even up to Rev 2.5.7-pl. If I could edit my comments I could cut out unnecessary stuff.

Glad it’s working! Regarding being able to edit with an outside editor, there are options. There are code editors that include FTP/SFTP ability so that you can edit a remote file locally on your code editor and when you save it syncs and uploads to your server. A few that come to mind are Sublime Text (with the SFTP plugin installed), Atom (with an FTP plugin installed), Coda (on Mac), Aptana IDE on both Windows and OS X, etc. A google search should bring up some alternatives for you depending on what OS you’re using. Hope this is helpful.