Beginner's Guide to MODx

From MODx Wiki
Jump to: navigation, search

Unless you are one of the lucky ones who can intuit almost instantly how to use MODx, the first thing that happens after you get it installed is: “Great CMS! Now how do I use it?” Well, read on, and have a look at the overview video posted here:

The idea with this tutorial is to give you some early success with MODx, answer some of your basic questions, and set you on the path to learn the rest of MODx yourself.

One caveat: Although this tutorial is about how to use MODx, it does get into several other areas of website building, so if you are an experienced website builder, please just skip those areas you are familiar with.

Everything in this tutorial template involving location and appearance on the webpage is done with a Cascading Style Sheet (CSS) file. If you don't know CSS - learn it. It is the future. This tutorial will introduce you to some CSS usage. Use caution when making changes to the CSS file – go slow and check to see what you did. Webpages can break in the browser very easily if you do the wrong thing with the css. Before you make any changes to the css file, make a backup copy of it while it still works.

If you have the template open in a browser, you can make changes in the CSS file in your editor, save the CSS, and then do an F5 in the browser to refresh the page and see the results of the CSS change immediately.

So, then—let's get into it.


Before you install MODx

Several prerequisites come to mind:

  1. It's best to have a functional webpage to create a template for MODx. Note: You do not need an entire site, just one page containing the layout of what your site will look like. Because MODx essentially relies on substitution to create dynamic pages, if you find a site you like, view the source. If you're able to see all the HTML and style sheets, chances are you'd be able to use the site's source code as a starting point for your own MODx template.
  2. You must have access to a web server, either local (localhost) or remote (a server which is maintained remotely. You normally pay a web host or hosting reseller for access to a server, but limited hosting can also be found for free).
    1. If you don't have a local server, you should get one as it greatly simplifies the constructing and testing of a website. You really don't have to know much about Apache (the preferred server among those who know), just go to Apache Friends and download and install XAMPP on your computer.
    2. If you're hosting the site remotely, you're almost certainly going to need a domain name to access it through. XAMPP installations and the like can gernerally be accessed [locally] at http://localhost/. You can make this accessible remotely by forwarding it (port 80, normally) to the outside, but there are major security implications doing this.
  3. You must have access to a MySQL database. The XAMPP install includes MySQL. Eventually you will need database access to the (remote) MySQL server. Discuss this with your hosting provider (ISP). See Create the modX database.

If you meet all of these requirements, you are probably now ready to install MODx. Be sure to take the option during install to install all the snippets—you will want them later.

Note for Mac OS X: OS X is a Unix system and it ships with Apache—once you're in the Terminal, it is nearly identical to most Linux variants. You merely need to enable Web Sharing in the Sharing control panel. You can download the latest PHP module at [1] and the MySQL module at [2]. Make sure Apache is configured securely. A very convenient solution is MAMP.

The abbreviation MAMP stands for: Macintosh, Apache, Mysql and PHP. With just a few mouse-clicks, you can install Apache, PHP and MySQL for Mac OS X. MAMP installs a local server environment on your Mac OS X computer, be it PowerBook or iMac. Like similar packages from the Windows- and Linux-world, MAMP comes free of charge. Download it from the MAMP site.

Creating the Template

Start with a complete functional webpage

Now for the good stuff: stripping your web page. What—you don't have a web page? Then:

  1. Pay/trick/bribe/plead a web designer to create one for you ($£¥€), or:
  2. Copy, download or buy a template you like from a tenplate site CSSDrive comes to mind, although there are literally hundreds of sites offering both free and premium templates. Be sure to get the permission of the designer to use the webpage you download, unless it has a license with it that allows unrestricted use. Creative Commons-licensed material is currently proliferating hugely on the internet: check the specific license, but this normally allows you to use the template as you wish provided it is attributed to the author. (Maybe you could even consider putting your own stuff under a CC license—it's a service to the net.)
  3. Download a template from the MODx repository. This is easy, but you won't learn as much in this tutorial and your site won't be particularly unique.
  4. Use the basic webpage I have included with this tutorial so you can get started right away.

It would also help for you to have at least a smattering of knowledge about; (X)HTML, CSS and Java script (and PHP if you want to create snippets.) If not, get ready to buy or borrow a bunch of books and refer to them when you get stuck. There are also a number of websites dedicated to learning these languages—W3Schools and YourHTMLSource both teach good, standards-compliant (take note: that is important) markup. Cut-and-paste from other working xhtml & css markup is also a good learning tool from seeing how someone else did it.

Hand coding vs Automated code generation

This tutorial assumes you are using an HTML editor – but if you don't have one, there are several fine code editors that work great and are free.

For Windows users:

For Mac users:


If you don't like any of these, look for a text editor/notepad that has:

  • Syntax Highlighting
  • Tabbed multiple-document interface

I would recommend that for this tutorial, that you do not use Dreamweaver or GoLive or a similar WYSIWYG ('what you see is what you get') website builder. Hand-coding will teach you more and it is neither difficult nor arduous. In any case do not use Microsoft Word, OpenOffice Writer, Word Perfect or similar word processors as they will introduce disruptive formatting when you copy and paste from them to MODx.

What happened to my template?

One question a lot of newcomers to MODx keep asking is: Where are all the files? Most all of the documents end up living in the MySQL database where you can't see them (e.g. the templates, documents/pages, snippets, chunks, and TVs). Some additional files are on the server where you can see them (e.g. images, css files, audio files, movies, etc.).

The sample page

The sample page we are going to use for this tutorial is a page design that I started on, but never used. It is a plain, two column, fixed width, web page.

It has:

  • a branding area, (used to be called header)
  • two columns of content in a 2/3 – 1/3 ratio,
  • a side menu and a top menu.
  • a site info box (used to be called footer).

This page is a pure CSS creation! No tables. This tutorial uses as lean a page as possible so you can see better what you are accomplishing. The logo picture was taken at the Mexican resort of Mazatlan and the logo is from my website. If you have another image you would rather use that's fine as long as the dimensions are: 240 pixels high by at least 790 pixels wide. Keep the kilobytes of the image down for faster loading.

The Starting HTML markup

The page being created will look something like the image below when completed.


So let's start the conversion to MODx template by stripping out the unnecessary markup. To start off with, here is the complete markup (without the css styles) used to display the page above in Firefox. For this tutorial, copy it out of this page and paste it into your editor.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<html xmlns="" xml:lang="en" lang="en">
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
	<link rel="stylesheet" type="text/css" href="[(base_url)]assets/templates/tutorial/css/style.css"  />
<div id="branding">	
</div> <!-- end of branding -->
<div id="content-main">
	<div id="content-text"><h2>Welcome to CixDegrees</h2>
			<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras a nisi.
			Donec blandit, ipsum id bibendum posuere, neque magna tincidunt nisi, nec facilisis odio turpis
			sed odio. Donec nibh pede, tempor aliquet, vehicula eu, pellentesque vel, urna. Nullam at arcu
			eu eros pretium viverra. Aenean vel mi quis augue cursus viverra. Cras at quam. Pellentesque
			imperdiet nunc id lacus. Duis justo pede, tincidunt sed, accumsan sed, sollicitudin aliquet, dui.
			Aliquam sed tortor at enim volutpat convallis. Vestibulum feugiat blandit erat. Sed vel libero.</p>
			<p>Pellentesque habitant morbi tristique senectus et netus et malesuada
			fames ac turpis egestas. Suspendisse nisi. Morbi elementum, diam ac pellentesque scelerisque,
			nulla nulla pharetra sapien, nec rutrum erat eros sed velit. Aenean dignissim blandit tortor. Nulla
			condimentum, ante quis volutpat blandit, ante lorem nonummy dui, eu fermentum nibh leo id magna.
			Nam tempus nisi eget orci ullamcorper venenatis. Sed in nisl. Ut vel tortor. Phasellus id diam
			semper enim congue tincidunt. Aenean dui neque, suscipit non, posuere ac, nonummy et, dolor.</p>
			<p>Aliquam elit. Aliquam quis enim. In fringilla lectus. Nullam orci justo, sagittis id, 
			malesuada ac, cursus egestas, massa. Sed ipsum nulla, blandit quis, tempor a, hendrerit sed, 
			libero. Nam non eros ut nisi malesuada malesuada. Aliquam mauris. In hac habitasse platea 
			dictumst. Proin rhoncus volutpat ante. Ut consequat, nunc nec tempor vulputate, turpis neque 
			nonummy nisl, quis iaculis ante mauris a tortor. Nulla facilisi. Sed lectus justo, laoreet non, 
			elementum sit amet, laoreet et, augue. Ut odio velit, tristique pellentesque, luctus et, varius 
			a, ante. Donec aliquam. Cras ipsum nunc, feugiat cursus, tincidunt eu, molestie et, diam.</p>
	</div> <!-- end content-text -->
</div> <!-- end content-main -->
<div id="content-sub">
	<div id="content-sub-title"><h2>News</h2>
			<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</p>
 	</div> <!-- end content-sub title -->
	<div id="navigation">
				<li class="active"><a href="/home" title="Home" >Home</a></li>
				<li><a href="/blog" title="Blog" >Blog</a></li>
				<li><a href="/services" title="Services" >Services</a></li>
				<li><a href="/search" title="Search" >Search</a></li>
				<li><a href="/misc" title="Misc." >Misc.</a></li>
				<li><a href="/about" title="About" >About</a></li>
				<li class="last"><a href="/login" title="Login" >Login</a></li>
		</div><!-- end of navigation -->
</div> <!-- end content-sub -->
<div id="site-info">
<p>Copyright© 2007 - Powered by MODx - Hosted by (mt)MediaTemple</p> 
</div> <!-- end of  -->

Note: The menu works, although it was not linked to anything, otherwise it is a functional webpage.

The Head Section modifications

First add one line to the head section right below any meta lines :

<base href="[(site_url)]"></base>

This sets the base URL for other use, like locating images, etc. It gets the URL from: MODx / Access / templates / from information you entered as you set up MODx.

Note: In order to avoid some serious Javascript issues in IE6, do not use the short form, i.e.

<base href="[(site_url)]" />

Second, strip out whatever was between the “title” tags and replace it with two MODx tags:

<title> [*pagetitle*] | [(site_name)]</title>

This will get the page title and site name respectively, from the “Title” you will input in the “Create/Edit' document screen, and “Site name” from the “Tools->System->Configuration" page. (Wait a bit and this will become more clear. I promise.)

Next, add the following line in the head of the template html to reference your CSS file:

<link rel="stylesheet" type="text/css" href="[(base_url)]assets/templates/tutorial/css/style.css" />

[(base url)] is NOT needed in your links if you have above base href="[(site_url)]" in the head section.

The Navigation Modifications

Next delete all this code in the the "navigation" div:

	<li class="active"><a href="/home" title="Home" >Home</a></li>
	<li><a href="/blog" title="Blog" >Blog</a></li>
	<li><a href="/services" title="Services" >Services</a></li>
	<li><a href="/search" title="Search" >Search</a></li>
	<li><a href="/misc" title="Misc." >Misc.</a></li>
	<li><a href="/about" title="About" >About</a></li>
	<li class="last"><a href="/login" title="Login" >Login</a></li>

and replace the markup with:

<div id="navigation">
</div><!-- end of navigation -->

The Wayfinder call explained: it is a call to a snippet. It can take various parameters, but at the moment we are only using startid=`0`. This tells Wayfinder to begin the menu with document ID 0. If there is no document ID 0, then it defaults to the next higher doc ID and builds the menu buttons for however many documents are visible (not grayed-out in the document tree).

Note that the parameter value is surround by the ` character. This is not an apostrophe, but is another character normally called a grave or backtick. You should find it at the top left hand side of an English keyboard, below Esc.

I know what you are thinking : "How is the menu going to look like it was before?" If the navigation menu(s) was styled and positioned with the css before the conversion, then the call to the Wayfinder snippet will take that css styling and build your menu as it was before, with the menu titles and links based on the "Menu title" entries for the documents (pages) it finds in the MODx Document Tree. (See below; #The MODx Manager.) The complete documentation with all possible parameters can be found here: Wayfinder homepage

More Complex Navigation Modifications

If all that seems pretty amazing, it is. There is a non-zero chance that it won't quite work when you wave your magic wand. What the Wayfinder code is doing is printing out a bit of text (often an unordered list) whose format is determined by some small templates that are stored as Chunks in your MODx admin control panel. If you are lucky, the default operation of this will work for you, but here are two possible scenarios that will force you to make a couple minor changes to the Chunks and to your Wayfinder call. Here a couple examples that should increase your understanding of how this snippet works:

What if your CSS class for the selected item is not class="active", but rather class="selected"? This is a simple one. Simply change your call to the Wayfinder snippet to reference the new class:

[!Wayfinder?startId=`0` &hereClass=`selected`!]

What if your menu has a separate CSS class or id for the unordered list? Or what if you aren't using an unordered list at all? Head over to Resources > Manage Resources > Chunks in the manager and either duplicate existing menu related chunks or create your own that look something like this:

Chunk name: my.OuterTpl

<ul class="my_style">

Chunk name: my.InnerRowTpl

  <a href="[]" title="[+wf.title+]"><em>[+wf.linktext+]</em>

The names could be anything, but I'm keeping the names so they match up with the variables that Wayfinder expects. Just to explain what's going on here, the my.OuterTpl chunk has the [+wf.wrapper+] bit, which is replaced with as many copies of the my.InnerRowTpl chunk as there are items in your menu. It's a template inside of a template. By default, Wayfinder uses its own templates for this menu generation, but you can tell Wayfinder to use your own chunks instead:

[!Wayfinder?startId=`0` &hereClass=`selected`  &outerTpl=`my.OuterTpl` &rowTpl=`my.InnerRowTpl`!]

Notice that you specify the names of the chunks to use in the &outerTpl and &rowTpl parameters. At first, this organization may seem really weird, but after you've got it plugged in and working, you can see that this design provides a lot of flexibility. In this way you can create chunks for any number of menu styles (e.g. tables, other CSS classes, etc.) and you can still use Wayfinder to generate all of them.

Orientation of the Menu

Examine the CSS styling fragments below for the "menu" div and the "navigation" div in the CSS file "style.css";


The Horizontal menu:

#menu ul li {
  display: inline;

and the Vertical menu:

#navigation ul {
   display: block;

Essentially the difference between a horizontal menu and a vertical menu is in the css styling of the ul tag. The horizontal menu "ul" is "display: inline;" and the vertical menu "ul" is "display: block;" (actually it defaults to the block display) I've commented the file "style.css" so you can play around with changing some of the styling to see what that will do to the menus. (please - only change number values, unless you are familiar with css.) You can play with the Wayfinder parameters also to see what they do beyond just the basic ones used here. This should get you started on menus. documentation on Wayfinder can be found here:

If you look at the installed MODx demo site you will see a number of pages (you see them in the document/folder tree on the left hand side of the MODx Manager page. i.e.; "Home", "Blog", "Design", "Register with us" etc.)

Backing up


You really do not want to be in the situation of discovering that the code you just overwrote/erased/deleted was your best and only working copy, and that it will take you days to recreate. (Did you try CTRL-Z to recover it?)

You can perform a backup of the MODx database by going to Tools > Backup. Tick all of the tables, then 'click here' to download the backup. Bear in mind, however, that this only backs up the database. You will not be able to recover other things such as MODx plugins that you've broken, images that you've deleted and javascripts that you've messed up from this backup: these are all stored as files on the server. To back these up, regularly use the backup function of your host or use FTP to regularly download all the files on your server.

The MODx Manager

Let's digress in the conversation for a moment.

This is a good time to explain several features of the MODx Manager's Document Tree that are not obvious at first glance.

The numbers in parenthesis along side of the document titles are the document ID's that are generated by MODx when a document is created, uniquely identifying those pages for future linking, reference,etc. By the way, the menu titles are going to be created by Wayfinder from the menu titles you input in the new document screen (unless you tell it otherwise.)

Note how some names are grayed out. This is by your choice when creating a document – there is a “Show In Menu” check box in the document “Create/Edit” screen – grayed out indicates you may have decided you don't want this document on the menu for various reasons. This “Create/Edit” screen is reached by a number of ways; when in the MODx Manager and you create a new document, ( MODx Manager->Site->New Document (which is also used to modify – edit existing documents) or by right clicking on a document name in the tree and bringing up a context menu – from which you would select “Edit Document” to also see the document screen

View Manager.jpg

Now back to the modifications; where were we? Oh yeah, we demolished the navigation. Now for the content!

The content modifications

Delete everything in the "content-text" div as shown. Don't worry about how we are going to re-fill it with content yet—that comes later. Now, replace what you ripped out with the document-specific variable [*content*] as shown in the code fragment below:

<div id="content-main">
</div> <!-- end content-main -->

There! That was easy and painless, wasn't it?

“How do I get it back? Where is it? I knew I shouldn't have ripped out all that neat markup! Now if only the page had it...content, that is.”

Don't worry, it's coming soon!

The Site-Info modifications

Now on to the Site Info.

By the way, I have been trying my best to begin using Web 2.0 semantic markup. Semantic markup is content marked up in a way that describes its meaning, rather than what it looks like. "Header", "leftColumn" and "footer" are presentational markup (they describe what the thing looks like, or where it goes), while "branding", "content-sub" and "site-info" are pieces markup descriptive of what they do. It's all about making the web a more accessible place: currently mainly to those with vision problems, but in the future hopefully to machines and AI.

If you are interested in learning more about ‘Web 2.0’ and semantic markup, read more at Andy Clarke's place.

If you have to ask who Andy Clarke is, you haven't been paying attention to the web world around the globe. Next time you are in your bookseller's, look for Andy Clarke's "Transcending CSS" in the computer book section. It was the hottest selling computer book in the winter of 2006/2007.

OK, now the site info (formerly the footer)—scalpel please:

<div id="site-info">
	<p>Copyright© 2007 - Powered by MODx - Hosted by (mt)MediaTemple</p> 
</div> <!-- end of site-info -->

turns into:

<div id="site-info">
</div> <!-- end of site-info -->

Wait where did all the actual information go? Well we transplanted some of it (the fixed information—and all of mine was fixed) into a chunk.

What's a chunk?

A chunk is a code/html markup fragment that we want to have MODx insert into our web page at some specific location. Why? So that we can separate the code/markup and generic, unchanging content of the webpage from the content specific to that page. For example, the {{cixfooter}} chunk consists of this markup:

Copyright &copy; 2007 Design by hjd
<a href=""></a>
Powered by MODx  Hosted by (mt) Media Temple</div>

Why not leave it in the template? You could and it would work fine. The only problem is that if you have a number of different sites and documents (pages), and you needed site info changes, you would have to change each individual template for any change in the site info. This way you only have to have one site-info chunk and call it in whatever document you need it in. If it needs a change, then you only have to do it one place. In that sense it's just like CSS: less work for everyone.


That's what MODx is all about.

Of course when you create your template, you are going to want all the variables to reflect your own site (i.e. {{cixfooter}} to {{yourfooter}}) Follow these steps to create your chunk:

Go to Resources > Manage Resources > Chunks > new Chunk in the manager.

In the chunk name enter “cixfooter” (for this demo, at least, and without the quotes of course). Now enter a description and pick a category for the new chunk. Copy the markup fragment above and paste this markup into the “Chunk code (html):” window. Click on “Save”. For now that is all the chunks we will need to enter.

The Results

Here is what we have for our complete MODx webpage template: (drum roll please) The MODx calls are highlighted.

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
  2. <html xmlns="" xml:lang="en" lang="en">
  3. <html>
  4. <head>
  5. <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  6. <base href="[(site_url)]"></base>
  7. <title> [*pagetitle*] | [(site_name)]</title>
  8. <link rel="stylesheet" type="text/css" href="[(base_url)]assets/templates/tutorial/css/style.css" />
  9. </head>
  10. <body>
  11. <div id="branding">
  12. </div> <!-- end of branding -->
  14. <div id="menu"> <!-- Horizontal menu at top of branding. -->
  15. [!Wayfinder?startId=`0` &level=`1`!]
  16. </div>
  17. <div id="content-main">
  18. [*content*]
  19. </div> <!-- end content-main -->
  20. <div id="content-sub">
  21. <div id="navigation"> <!-- vertical menu – it's all done with the CSS -->
  22. [!Wayfinder?startId=`0`!]
  23. </div><!-- end of navigation -->
  24. </div> <!-- end content-sub -->
  25. <div id="site-info">
  26. {{cixfooter}}
  27. </div> <!-- end of site-info -->
  28. </body>
  29. </html>

Not much to it, is there? There is more we could (and will) add, but for now all you need is “proof of concept”—whether it works, how it looks—then we'll talk about adding content back into it.


The generic name for all of these weird things in brackets is ‘placeholders’. Here is a partial list of placeholders used by MODx. For a more complete guide to the placeholders used by MODx, please refer to the placeholder reference.

  • [(site_url)]: A “setting” which takes the URL as determined during the MODx installation and inserts it in the html at run-time.
  • [*pagetitle*]: A “Template Variable” which takes the page title as entered in the “document setting” screen of the Manager, and inserts it in the html at run-time.
  • [(site_name)]: A “setting” which takes the site name as determined during the MODx installation and inserts it in the html at run-time.
  • [(base_url)]: A “setting” which is based on the URL as determined during the MODx installation and inserts it in the html at run-time.
  • [!Wayfinder? &startId=`0` &level=`1`!]: Explained above.
  • [*content*]: A “Template Variable” which enables a rich text editor (TinyMCE, CKEditor and FCKEditor are some examples here) to allow the entry of content to the document (page). Content can be a combination of text, html markup, images, various media, etc. (See—I told you I'd tell you all about adding content.)
  • [!Wayfinder? &startId=`0`!]: Wayfinder is a snippet which builds a menu for the website navigation as described above.
  • {{cixfooter}}: This is a chunk, which inserts pre-formatted text and html markup into the page at it's location.

Getting ready to see it work

Take the modified html, and put it into MODx to become a template. Here is how:

Login in to the MODx Managern Once the manager is open, on the top set of tabs,

  • click on “Resources” or “Elements” to open that screen. (In the newest GA release, Resources are called Elements.)

Once it is open,

  • click on “Manage Resources” or “Manage Elements” and then, on the lower tab set,
  • click on “Templates” and then,
  • click on “New Template”.

In all subsequent directions I will just show it this way: Resources > Manage Resources > Templates > New Template

From your coding editor, copy the template and paste it into the window marked: ”Template code (html)”

Don't hit save yet.

Go up to the input box “Template name:” and enter a name for your template. I used “tutorial”. You can use whatever you want. In the next box (“Description:”) enter whatever description you like. I entered: “A tutorial template to play with”. Then pick a category to classify the template. I didn't find one I liked, so I entered a “New Category:”, which I called ”Template Tryout”

Now click the ”Save” button.

Next, you need to navigate to your MODx root folder on your server (on a remote server it is often: domains > HTML or /www/ while on a local server it might be: xampp > htdocs > modx-0.9.5). Then navigate as follows: MODx-0.9.5 > assets > templates and, inside the templates folder, create a folder (call it “tutorial” for example). Then enter that folder and create two folders inside of the tutorial folder: “css” folder and “images”.

Place the logo image, “cixlogo-tropic.png” into the image folder (assets/templates/tutorial/images).

Copy the css script file “style.css” into your code editor.

You may have to make a change to the css file so MODx can find the logo image. If you use the folder name suggested and the supplied image, you won't need to make any changes. This is because when the css calls for an image, it looks relative to itself (the css file), rather than relative to the page. So, if your css is in its own folder, and images is another folder at the same level, it can stay like this:

/* ===== BRANDING ===== */
	background: url(../images/cixlogo-tropic.png) no-repeat 0 0;

(../ raises you a level in the file structure. If you were in /www/www/css/ before you added ../, you're in /www/www/ afterwards. images/ then brings you into the /www/www/images/ folder.)

Copy and paste the file “style.css”, into the assets/templates/tutorial/css as “style.css” .

The css script could use a lot of work to clean it up and refine it, but it works as is.

A short preflight checklist:

Where we are:

OK, now we have the template in MODx.

  • We checked to be sure the link for style.css in the template html was
  • We checked to be sure we put style.css in the tutorial/css folder.
  • We checked to be sure we put cixlogo-tropic.png in the tutorial/images folder.
  • We for sure entered the “site-info chunk” into the MODx manager and named it “cixfooter”.

Now go to Manager > Tools > Configuration and enter the following information:

  • In “Site Name” at the top of the screen: enter a name for the site.
  • Then scroll down to “Default template” and using the drop-down list select the “Tutorial” template.
  • Then check the “Reset all pages to use the Default Template” radio button.
  • Scroll to the top of the page and click on “Save”.

Then click on the Site tab and,

Run the Template

  1. Jump up, hop over your monitor and twirl three times and click your heels!
  1. Click the Preview button.



There it is in all its ragged glory, with nothing in the content area yet, but look at that menu! Click on it and notice how it takes you to all the MODx demo pages. It might not be much to look at yet, but it's a start. Play with the menu. Note how some documents break the page. The css file will have to be refined for those pages (or perhaps there is no styling info for them yet in “style.css”) but it is fixable.

The main thing is: we now have a working template and we know how we did it.

A Primer on the MODx Manager

Go to the manager and, in the document tree, right click on the “Home” page. Select “Edit Document” from the pop-up menu. Look at the information on this page—you can change all or any of the text in the boxes. For now leave it as it is.

There are several items to note on the page;

“Uses Template”

Which ever template is selected in this box will be the template for this page. You could in fact select different templates for each page if you wish, but that would destroy the visual cohesiveness of your site.

For now “tutorial” is the template for all pages, because if you remember (you do remember don't you?) back on the Tools > Configuration page you selected “Reset all pages to use Default template” with “tutorial” as that default.

After a while you might have quite a few templates to choose from.

“Menu title”

The text you place in this box will become the title on the menu button for this page.

“Menu Index”

This number sets the document position on the menu. By visiting each document and changing this number you can re-arrange the menu sequence. Home of course usually is #1.

“Show in menu”

Determines if the document will show in the menu. There are some documents you may not want to show in the menu such as a Thank you page or a 404 Not found page. For these pages just make certain the box is not checked. Also, if you know that your menu is going to stay the same, you can set up Wayfinder to only display certain IDs or pages with particular templates. This is not an ideal solution (you should always untick anyway), but it prevents you accidentally breaking your layout by forgetting to untick the box.

“Document parent”

Where in the tree do you want the document to be? For organizational reasons you will probably need to change the “Parent” document for this document and you do it here. There are two ways to select the parent doc, just accept the default parent or click on the button and then in the tree click on the doc you want to be this doc's parent. Simple. You can later change the parent if it suits your needs.

Now drop down below the text entry box to “Editor to use” On a default install of MODx you will probably only find “None” and “Tiny MCE” as options. What the MODx install documentation neglects to tell you is that you should download and install the powerful [FCKEditor] (all one word).

After it is installed you will find the FCKEditor in the drop-down list as well. It is a nice editor, with very nice content insertion features. It can take a while to learn all the ins and outs of it. The TinyMCE editor has some nice features to use during site development; it allows you to edit content from the web. For this tutorial select the FCKEditor editor.

NB FCKEditor has now changed its name to CKEditor, although compatibility updates are still released for FCKEditor. An plugin of the new CKEditor is now in development for MODx, though you'll have to trawl through [a forum thread] to download it.

Now for the pièce de résistance! While you have the document edit screen open, note the tabs at the top of the page. We have been working in the “General” tab. Go to the “Preview” tab and note how Quick Edit has placed small gray buttons at various places on the page view. When you click on them, they allow you to edit content directly. For example click on the gray button labeled “content”. (there are two places you could do that; at the top of the page in the QE button bar, and lower down on the page note the button place at the end of the current content text labeled “<< edit content”.

Clicking on the top button will present you with a list of options you could want to edit, while the button near the text will directly open a pop-up window with a rich text editor. Just in-case you are wondering on how to get the Quickedit menu off your page – go to the Quickedit bar and click on the right side “Go” and take the “logout” item from the menu. Good bye Quickedit. Start entering your content. Type, type, type. Come on, you wanted “content”!—keep typing.

How to get your content looking like you want it: In the document tree, right click on the document you want to work on the content of an select “edit” from the context menu. Use the formatting features of FCKeditor to enter text, images, media and some html markup. You will have to read up on the editor tool bar and then experiment with it. Later additions to the tutorial will include demonstrations of content entry.


I will also do some elementary css stuff; showing how to change the space around paragraphs, images, position menus etc. by adjusting the margins and padding. The css file is heavily commented for your edification and enjoyment.

Wisdom and Learning

Now is a good time to pause from our labors in the fields of Webdom and go to the MODx site and look up, and read some of the relevant documentation on what we have done so far.

Now that you can see it work, the docs will make more sense. Here is your homework:

  • Research what [(site_url)] is for and what kind of MODx tag & its syntax is. (a Setting)
  • Research what [*pagetitle*] is for and what kind of MODx tag & its syntax is.
  • Research what [(site_name)] is for and what kind of MODx tag & its syntax is.
  • Research what [*content*] is for and what kind of MODx tag & its syntax is.
  • Research what [!Wayfinder? &startId=`0`!] is for and how it works & what its syntax is. Look up the options we could have used. Experiment.
  • Research what {{footer}} is for and what kind of MODx tag & its syntax is.

For additional study (and you thought you were done!) look up, and read the documentation on the following subjects:

Adding Features

OK on with the show! How about adding some breadcrumbs (are we there yet?). Simple. Copy some code from the Breadcrumbs documentation and there we are.

<div id="breadcrumb">[!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!]</div>

and paste it into the template.html so it will show up some place, for example, up high on the page. Looking at the page in the browser, it looks like there is room at the top of the branding div above the logo image. Here is what I mean by that; if you look in style.css at the “branding” div:

	background: url(../images/cixlogo-tropic.png) no-repeat bottom;

You will note that the height is 250 pixels but the logo image is only 240 pixels high giving us 10 px at the top to play with.

If you are not yet familiar with css, what this div (think of it as a box) tells us is: it has a height of 250 pixels and since the image it contains is 770px wide, it is by default 770px wide also. The background of this div, is set to an image ( cixlogo-tropic.png), it doesn't repeat, and is placed at the bottom of the div box.

Let's put the breadcrumbs there and see if it works.

<div id="branding">	
[!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!]
</div> <!-- end of branding -->

It is a snippet, and the call is to build a breadcrumbs trail for a maximum of two levels deep (a page and it's first child level) and do not show crumbs when on the home page. OK? There are plenty more breadcrumbs parameters for you to play with in the breadcrumbs documentation. Click on Preview and . . . Hmmmmm! That's ugly!.

The font is too large, and it pushed everything down when it displayed. We can cure that. Let's surround the breadcrumbs call with a div so that we can style it with css. First add the following markup (breadcrumbs div) in bold to tutorial.html:

<div id="branding">	
     <div id="breadcrumbs"> 
             [!Breadcrumbs? &maxCrumbs=`2` &showCrumbsAtHome=`0`!]
     </div> <!-- end of breadcrumbs -->
 <div id="menu">

we will copy some styling script from another document that works and append it onto the end of the style.css file.

/* ===== Breadcrumb ===== */
#breadcrumbs {
	width: auto; /* makes the div the entire width of the surrounding container.*/
	height: 0.6em;
	font-size: .6em;
	color: Black;

Save the css file and then do an F5 to reload the page in the browser and – It works! Quickedit is in the way but you can see the breadcrumbs behind it. The css needs to be tweaked for position and font size and perhaps color – but it works. Now go read the Breadcrumbs docs and see what else you can do with it.

Still more additions

We are beginning to dress out the page now. Let us add something into the content-sub div under the navigation. Perhaps some blog summaries, or news headlines. Copy the code below.

	<p>[[Ditto? &summarize=`3` &total=`3` &startID=`2` &tpl=`news`]] </p>
</div> <!-- end of content-extra -->

And paste it in the template just under the end of the "navigation" div.

What do you know? I works! The text that shows up for "summarize" in the Ditto call is whatever you typed into the "Summary (introtext)" box of the create/edit document->general screen.

Now we are on the way to finishing this page. Obviously there are some warts to be taken care of and I hope to show how to fix most of them.


This should answer most of your questions about how to get started with MODx and further enhancing the page is left for an exercise for you.

Enjoy MODx.

  1. /* ===== BEGIN STYLE.CSS HERE ===== */
  2. /* This is style.css to work with tutorial.html HJD 2/07 */
  3. /* Normalizes margin, padding */
  4. body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, form, fieldset, input, p, blockquote, th, td
  5. { margin : 0; padding : 0; }
  7. /* Normalizes font-size for headers */
  8. h1,h2,h3,h4,h5,h6 { font-size : 100%; }
  9. /* Removes list-style from lists */
  10. ol,ul { list-style : none; }
  12. /* Normalizes font-style and font-weight to normal */
  13. address, caption, cite, code, dfn, em, strong, th, var
  14. { font-style : normal; font-weight : normal; }
  16. /* Removes list-style from lists */
  17. table { border-collapse : collapse; border-spacing : 0; }
  19. /* Removes border from fieldset and img */
  20. fieldset,img { border : 0; }
  22. /* Left-aligns text in caption and th */
  23. caption,th { text-align : left; }
  25. /* Removes quotation marks from q */
  26. q:before, q:after { content :''; }
  28. h1,h2,h3,h4,p,li{
  29. font-family: Verdana, Geneva, Arial, Helvetica, sans-serif;
  30. font-weight:normal;
  31. }
  32. h1{font-size: 2.0em;}
  33. h2{font-size: 1.0em;}
  34. h3{font-size: 0.8em;}
  35. h4{font-size: 0.7em;}
  36. p{font-size: 0.8em;}
  38. html{
  39. text-align: center;
  40. font:Verdana, Geneva, Arial, Helvetica, sans-serif;
  41. }
  42. body{
  43. width:770px;
  44. margin: 0 auto;
  45. padding:5px;
  46. text-align:left;
  47. background:#FFF;
  48. color: Black;
  49. }
  51. /* ===== BRANDING ===== */
  52. div#branding{
  53. height:250px;
  54. background: url(../images/cixlogo-tropic.png) no-repeat bottom;
  55. }
  57. ***************************************************
  58. Header Menu
  59. ***************************************************/
  61. #menu {
  62. text-align: left;
  63. }
  64. #menu ul li {
  65. width: auto; /* lets the menu item buttons be same size as menu title*/
  66. /* width: 3em; */ /* sets menu buttons to fixes width */
  67. display: inline;
  68. float: left;
  69. list-style: none;
  70. text-align: center;
  71. text-transform: uppercase;
  72. font-size: 0.6em;
  73. padding: 0 1em; /* spacing between menu items experiment with this*/
  74. color:Black;
  75. }
  76. #menu ul li a {
  77. text-decoration: none;
  78. text-transform: uppercase;
  79. }
  80. #menu ul li a:hover, #menu ul li {
  81. color: Red;
  82. }
  83. /* ===== Navigation-side ===== */
  84. #navigation ul {
  85. list-style: none;
  86. margin: 6px 0;
  87. display: block;
  88. }
  89. #navigation a {
  90. border: 1px solid #BEDFF6;
  91. display: block;
  92. /* background-image:url(menubar-1.png);*/
  93. background-color: #BEDFF6;
  94. text-decoration: none;
  95. text-align: center;
  96. margin: 3px auto;
  97. font-size: 13px;
  98. padding:5px;
  99. width: 85%;
  100. }
  102. #navigation a:hover {
  103. color: Black;
  104. border-left-color: #10638E;
  105. border-left-width: 2px;
  106. background-color: #B0D9F9;
  107. }
  108. /* ===== CONTENT ===== */
  110. div#content-main{
  111. float:left;
  112. width:520px;
  113. margin:0 4px 10px 0;
  114. }
  115. div#content-sub{
  116. float:right;
  117. width:242px;
  118. margin:0 0 10px 4px;
  119. }
  120. div#content-sub{
  121. background: #DDEEF6;
  122. }
  123. div#content-main h2{
  124. background: #1FA8EF;
  125. }
  126. div#content-sub h2{
  127. background: #DD4411;
  128. }
  129. div#content-main h2, div#content-sub h2{
  130. /*text-transform:uppercase;*/
  131. padding: 8px 0 8px;
  132. text-align:center;
  133. letter-spacing: 0.1em;
  134. font-size: 1.0em;
  135. color: White;
  136. }
  137. div#content-main h3, div#content-sub h3{
  138. text-transform:uppercase;
  139. padding: 8px 0;
  140. text-align:center;
  141. letter-spacing: 0.1em;
  142. background: #EE8800;
  143. font-size: 0.8em;
  144. color: Black;
  145. margin: 0 40px;
  146. /*padding: 0 30px;*/
  147. }
  148. div#content-main p,div#content-sub p{
  149. margin:0;
  150. padding:5px 8px 15px;
  151. /*font-size: 0.7em;*/
  152. }
  153. /* ===== comments ===== */
  154. div.comments div{
  155. background: #EEEEEE;
  156. padding: 4px 3px;
  157. margin-bottom:10px;
  158. }
  159. div.comments div.odd{
  160. background:#E7EEF8;
  161. }
  162. div.comments p{
  163. padding: 10px;
  164. margin:0;
  165. }
  166. /* =====================================================
  167. div#content-main-title div,div#content-sub-title div{
  168. border:2px solid #1FA8EF;
  169. } ====================================================*/
  170. /* ===== Site Info ===== */
  171. div#site-info{
  172. clear:both;
  173. width: 100%;
  174. background: #B0D5E5;
  175. padding:15px 0;
  176. text-align:center;
  177. }
  178. div#site-info p{
  179. /*font-size: 0.6em;*/
  180. }
  181. /* ===== navbar ===== */
  182. #navbar {
  184. margin-top: 10px;
  185. }
  186. /* ===== Breadcrumbs ===== */
  188. #breadcrumb {
  189. width: auto;
  190. height: 1.5em;
  191. font-size: .6em;
  192. color: Black;
  193. }
  194. /* ========== End of CSS Styling ========== */
Personal tools