Integrating a Template into MODX part 1

Integrating a Template into MODX part 1

In this tutorial we will cover how to get the Soho template homepage into MODX. You can use this process with pretty much any template or custom design in order to create a website in MODX. This tutorial starts on the premises that you already have a working version of MODX installed and have access to the manager portion of it. Before we begin here are some things you should read so you can understand some of the MODX terminology.

Here is a list of the things we will cover in this first part of the tutorial.

  1. Identify Areas of our Homepage Template
  2. Identify MODX Extras we will need to use
  3. Homepage Breakdown
  4. Project Setup
  5. Edit Html, CSS and JS files to use correct paths

Identifying Areas of our Homepage Template

First download the Soho template from Codeplay Studios , this is the template we will be using for the tutorial. Our goal is to get the index.htm template into MODX in order to edit every area of it in MODX.

Once you finish downloading the template and extract its contents you will end up with these files

Extracted Template Folder

The first thing we need to do is get rid of some unnecessary files we will not use in this tutorial, these are about2.htm, index2.htm and index3.htm

Now that we have deleted the unneeded files lets proceed to see what our index.htm template looks like.

As you can see our index.htm template has a header, a footer and area dedicated for content.

Header, Content and Footer areas

The content area of the Homepage has a slider, a four column div followed by a one column div and finally a two column div.

Homepage layout

Identify MODX Extras we will need to use

A MODX Extra is an Add-On that extends the functionality of the CMS, there are many Extras for MODX ranging from Gallery creation, Dynamic navigation generators to Form Creation Extras. You can see the full list of available MODX Extras here .

We need to analyze the sections of our Homepage in order to know what areas of it can be converted to use a MODX Extra.

Homepage Breakdown

Let s start with the template header, we will create a chunk that will contain the site logo and wayfinder extra for the navigation.

Header Chunk

For the slider we will use gallery.

Image Slider

For the four column divs (Introducing Soho, Features, Browser Love and Other Files) we will use template variables, one for each column.

Four Column Divs

For the one column div (Testimonials) we will use another template variable.

One Column Testimonial Div

For the two column divs (Sub Heading 2 and Sub Heading 3) we will use yet another two template variables, one for each column.

Two Column Sub Head Divs

For the footer area we will create a chunk with 3 template variables, a wayfinder call and a simple formit email subscription form.

Footer Chunk with template variables, wayfinder and formit

After our Homepage Breakdown we now know we need 3 extras for this page.

  1. Wayfinder
  2. Gallery
  3. FormIt

Project Setup

Now we will cover how to setup our project for easy integration with MODX, we will create a folder structure that mirrors where our files will reside in MODX this will make the transition from static template to a MODX template very seamless.

To accomplish this we will need to do a few things:

  • Create a assets folder
  • Create a template folder inside our assets folder
  • Create a CSS folder for our style sheets inside our template folder
  • Create a JS folder for our javascript files inside our template folder
  • Create an image folder to store our images inside our template folder

If you go to your template folder you will see all files are in the root of our directory.

Template Root Folder

Let s change that by organizing our files a bit, create an assets folder.

Create Assets Folder

Now let s move all our style sheets, javascripts and our images folder into the assets folder, once we do this our project root folder will look like the screen on the left and our assets folder will look like the screen on the right.

Root and Assets folders

So now our Root folder is nicely organized but our assets folder is a mess, let s create a CSS folder to store our style sheets and move all our CSS files into this folder.

Assets and CSS folder

Now we have to create a folder for our Javascript files so go back to the assets folder and create a scripts folder and move all your javascript files to it.

Assets and Scripts folder

So now our assets folder is nicely organized with a folder for our images, css and javascript files which is great but if you open any of the html pages you will see they are not styled and no images are showing.

Broken Index page

Edit Html, CSS and JS files to use correct paths

In our last section we organized all our files into folders and this caused our HTML to break the paths to the images in all the files, now we have to fix them so it uses the new folder structure we created.

Let s fix our CSS paths, open your HTML/Text editor and let s look at our head tag to see what needs to be changed. In the head of the index page you can see we have some scripts and css links we need to update their paths.

Scripts & CSS links

For our Javascript files we need to add: scripts/ before the name of the script file and for our CSS files we need to add: css/ before each CSS file name, make sure to check the whole document for any stray javascript links that might need updating. Once you have updated the path to the css and js files your template should look like this.

Updated Scripts & CSS paths

So let s see how our page looks now that we ve updated our CSS and Javascript paths, open the index.html file and we see its starting to look like its supposed to.

Styled Index page with broken images

Notice that none of the images are displaying let s fix that by updating the image paths in our template. Let s go back to our editor and look at our image tags, if you look closely you can see all our images share something in common, they all have a starting image/ path this is great because now we can use find and replace on all our template files and update them all at once if your editor supports mass find and replace of opened files or directories.

So open the replace or find and replace in your editor and in the find text field enter images/ and in the replace text field enter images/ and click on replace all (button may vary in your text editor).

Find & Replace

Tip Tip: If your editor doesn t support mass find and replace consider upgrading to Sublime Text 2 (what I m using in this tutorial) or Notepad++ (Did you know the Notepad++ site is built on MODX?) both are great Open Source text editors with tons of features and plugins and best of all FREE! ( Sublime Text 2 can be purchased for $59.00)

Let s go back to our browser and refresh the page, now the Homepage look exactly like it used to and its assets are organized like the MODX setup we will use.

Partially Fixed Index Page

Upon inspecting the page I noticed the email subscribe button in the footer is not displaying correctly, that means our css files have incorrect paths let s fix them.

Open the style.css file in your text editor and let s see how our image paths are setup, we can see all images have a preceding images/ directory.

Broken CSS Image Paths

Again we will use the images/ to do a mass find and replace in all our css files (because your text editor supports this right?) we will be replacing images/ with ../images/ once we do this all our css files will have the correct paths for the images used in the templates.

Fixed CSS Image Paths

Tip Tip: An easy way to know if any images or files are not loading you can use Firebug or Chrome developer tools to see what files or images are returning a 404 (not found) it will tell you the name of the file that has the incorrect path.

After using Chrome Dev Tools I noticed the Index page has an incorrect path for an image.

Chrome Dev Tools Debugging

Upon further inspection I noticed it was an image being used in the javascript tag for the image slider, this image path did not get replaced because it was using img/ instead of images like all the other images in our HTML pages, so I added the correct path images/

Fixed Image Path in Javascript

Now Chrome Dev tools says everything is fine.

Okay we have finally finished with our local files in the second part of our tutorial we will start working inside of MODX uploading all our files and installing the extras we need to get our site done.

06 Jun

Author Benjamin Marte Category Tutorials Comments (5)

Comments (5)

  1. Mad:
    Nov 24, 2012 at 06:38 PM

    Thanks for the tut!

  2. Reshi Mahendra :
    Jan 04, 2013 at 01:45 AM

    Really helpful. Nice tutorial. I just start to learning ModX (evo) and searching related references for the template structure.. want to test it on this weekend.

    Thanks for the tutor.
    Reshi Mahendra

  3. Susan Ottwell :
    Jan 11, 2013 at 02:19 AM

    The link to the SOHO template at is dead; you can get the template at

  4. ahren:
    Jan 30, 2013 at 07:37 PM

    Oops, this seems to be out of date already. That CSS template is no longer available...

  5. Benjamin Marte :
    Feb 06, 2013 at 08:36 AM

    Thanks for the heads up guys I updated the tutorial with fixed links for the template.

Leave a Comment

This thread has been closed from taking new comments.

Scroll to top