Learning Modx, Tutorial #1 Creating a Template

This Tutorial will walk you through the steps to create a simple template for Modx CMS.

Audience, who is this tutorial for?

This tutorial is aimed at those that are new to Modx Revolution, but also have a good understanding of HTML and CSS. This tutorial will not cover how to create HTML or CSS.

Version

Modx Revolution 2.0.0 rc2 and above.

Requirements

You should have a working version of Modx Revolution so you can follow along.

Download Code files – updated 9-26-2011 I moved this Tutorial and code.

Make sure that you have the following packages installed before you begin this tutorial

• getResourcesPackage Page: http://modxcms.com/extras/package/552Docs: http://svn.modxcms.com/docs/display/ADDON/getResources
• Wayfinder
  Package Page: http://modxcms.com/extras/package/487Docs: http://svn.modxcms.com/docs/display/ADDON/Wayfinder

Optional Packages

These optional packages are not required to complete this tutorial, but you may find them helpful.

• TinyMCE: http://modxcms.com/extras/package/459

Concepts/terms used

• Templates
• Tags
• Template Variables
• Chunks
• Dynamic menu/navigation creation
• Categories

The Tutorial, version 1.0

1. Create a Category

   The first thing we want to do is create a category. This will help us keep all of our pieces easily organized. As you create more templates, chunks, snippets and plugins this becomes very important.

   1. Click on the Elements tab
   2. Right click on Categories, you will see New Category appear, left click on it.
   3. For the Name field type in: Webdeveloper

   

   Note the Parent field allows you to have nested or sub categories.

2. Create Template Variables

   Okay now I want to create TVs(template variables). You probably are saying what is that? So here is the simple scenario. In our template we want to allow customization on every page/resource some additional text fields like meta info, CSS and JS. Don’t get confused here, we are planning to use a global CSS file and JS files, but these will allow us to have properly embedded CSS and unobtrusive javascript for each page we create!.

   NOTE: you cannot have HTML tags in the name, description, etc when you are creating the TV!

   1. Again in the Elements tab, right click on Template Variables and click on New Template Variable.
   2. We are only going to use the General Information tab. We will fill in the Variable Name, Caption, Description, Category (Webdeveloper), Input Type and for one TV Default Value. Only enter/change the values listed, see the list below of the TVs you should create.
   3. More info on Creating TVs

   TVs to create:

   • Variable Name: meta-keywords
     Caption: SEO Keywords
     Description: 5 to 7 keywords related to this page.
     Category: Webdeveloper
     Input Type: Text
   • Variable Name: meta-description
     Caption: SEO Description
     Description: A 25 words or less description related to this page.
     Category: Webdeveloper
     Input Type: Textarea (mini)
     Default Value: [[*introtext]]
   • Variable Name: webdeveloper-css
     Caption: Embedded CSS
     Description: Enter in your CSS, remember to wrap in style tags
     Category: Webdeveloper
     Input Type: Textarea
   • Variable Name: webdeveloper-js
     Caption: JavaScript
     Description: Enter in your JS, remember to wrap in script tags
     Category: Webdeveloper
     Input Type: Textarea

   

3. Create the Template

   Now that we have created some TVs lets create a Template. We want to make a template that will be flexible by allowing us to create more templates using some common elements like banner, navigation menu and footer. Once you get an understanding of this you will see how to make sub templates and many more options.

   • Again under the Elements tab right click on Templates and then left click on New Template
   • Fill in the Template name: WebdevelopmentTemplate1
   • Description: Our first Template!
   • Select the category: Webdeveloper
   • Paste in the HTML code from the WebdevelopmentTemplate1.html file
   • Now click on the Template Variables tab and check all of the ones we created in step 2

   About the “[[”, this is the start of a Tag. I used two types in our template, the first type you see is [[*, this is for the TVs that we created. Our template will now import the value of those TVs for each page/resource. The [[$ is for Chunks. Chunks are simply little bits of HTML. Now we need to create the banner, navigation and footer Chunks.

   
   

4. Create the Chunks

   1. Under the Elements tab, right click on Chunks and then left click on New Chunk.
   2. Fill in the Name: webdeveloper-banner
   3. Description: HTML Banner
   4. Category: Webdeveloper
   5. Chunk code (html): Paste in the HTML code from the webdeveloper-banner.html file

   Now do the same and create these two chunks:

   • Name: webdeveloper-navigation
     Description: This is the main navigation HTML
     Category: Webdeveloper
     Chunk code (html): Paste in the HTML code from the webdeveloper-navigation.html file
   • Name: webdeveloper-footer
     Description: This is the footer HTML
     Category: Webdeveloper
     Chunk code (html): Paste in the HTML code from the webdeveloper-footer.html file

   

5. The CSS file

   Now the last piece in our example, the CSS file. We need to have the CSS file uploaded to:
   (the folder where you have modx)assets/templates/webdeveloper/css/layout.css. You can do this two ways, via FTP or the File manager.

   Using the File Manager:

   1. Click on the Files Tab
   2. Navigatigate to assets/templates – note if these folder/directory are not here you will have to create them.
   3. Create the Directory webdeveloper by right clicking on the folder templates. Then left click on Create Directory Here.
   4. Do the same with css
   5. Now right click on the css folder/directory and left click Upload Files
   6. Click the add button and select the layout.css file
   7. Click the Upload button then Close.

   

6. Create a test page

   1. Click on the Resources tab
   2. Right click on web and hover over Create and then click on Create a Document Here
   3. Now select the Template WebdevelopmentTemplate1 and an alert message will pop up, click Yes.
   4. You can name the file whatever you would like.
   5. Now click on the Template Variables tab, and you will see the text fields we created!
   6. Open up the file testpage-data.txt and copy and paste into the appropriate fields
   7. Now save and preview and you should see your page!