MODx and YAML – from zero to finished site
Why MODx? Because it just rocks if you have some markup skills.
Update: For more MODx tutorials there is a series; the creation of Asian Diving Vacation.
In this tutorial we will start with an empty MODx and the default YAML 2 column left layout. In fact I just dropped all of YAML in a folder called mytemplate inside the MODx assets/templates folder.
One annoying thing is that per default MODx needs you to store the template in the database, editing HTML in a text area in the browser is not really cool. I’m sure this behavior can be overridden by some kind of snippet but I’m a noob so I just went with the default process.
In MODx there are two main constructs, the snippet and the chunk. The snippet is what would be called plugin, module or component in another CMS, it’s the PHP code. A chunk is a piece of HTML that can be used as a mini template within the main template, for instance for rendering a footer. However, as you will see, chunks can also be used in much more dynamic ways to format various content.
Installing MODx is a breeze, you just need your DB login and password. Choose empty site instead of default content, for the purpose of this tutorial some default content would only be confusing.
When the installation is finished you can start to create content by going Site -> New Document. You can create subsections by creating a folder and then creating articles within that folder. It’s basically identical to the way it works in TYPO3. I only have one folder, the news folder, and some news articles in it.
That took care of our content, it’s time to layout the site. I began by simply copy pasting the 2 column left layout template that I chose into the Resources -> Manage resources -> Templates -> New template text area. It currently looks like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>[(site_name)] - [*pagetitle*]</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<!-- (en) Add your meta data here -->
<!-- (de) Fuegen Sie hier ihre Meta-Daten ein -->
<link href="[(base_url)]assets/templates/mytemplate/examples/02_layouts_2col/css/layout_2col_left_13.css" rel="stylesheet" type="text/css"/>
<!--[if lte IE 7]>
<link href="[(base_url)]assets/templates/mytemplate/examples/02_layouts_2col/css/patches/patch_2col_left_13.css" rel="stylesheet" type="text/css" />
<![endif]-->
</head>
<body>
<div id="page_margins">
<div id="page">
<div id="header">
<div id="topnav">
<!-- start: skip link navigation -->
<a class="skip" href="#navigation" title="skip link">Skip to the navigation</a><span class="hideme">.</span>
<a class="skip" href="#content" title="skip link">Skip to the content</a><span class="hideme">.</span>
<!-- end: skip link navigation -->
login
</div>
</div>
<!-- begin: main navigation #nav -->
<div id="nav"> <a id="navigation" name="navigation"></a>
<!-- skiplink anchor: navigation -->
<div id="nav_main">
[[Wayfinder? &startId=`0`]]
</div>
</div>
<!-- end: main navigation -->
<!-- begin: main content area #main -->
<div id="main">
<!-- begin: #col1 - first float column -->
<div id="col1">
<div id="col1_content" class="clearfix">
<h3>News</h3>
[[Ditto? &startID=`11` &summarize=`4` &tpl=`news_format`]]
<br/>
{{partners}}
<br/>
{{support}}
</div>
</div>
<!-- end: #col1 -->
<!-- begin: #col3 static column -->
<div id="col3">
<div id="col3_content" class="clearfix">
<!-- skiplink anchor: Content -->
<h2>[*longtitle*]</h2>
[*content*]
</div>
<div id="ie_clearing"> </div>
<!-- End: IE Column Clearing -->
</div>
<!-- end: #col3 -->
</div>
<!-- end: #main -->
<!-- begin: #footer
<div id="footer">{{footer}}</div>
end: #footer -->
</div>
</div>
</body>
</html>First of all you will see the special MODx tag [(base_url)] in the paths to my stylesheets. This is a settings tag. As you can see there are quite a few more than just the base url that you can use in various places.
The next interesting tag is [[Wayfinder? &startId=`0`]]. Wayfinder is a core snippet by Kyle Jaebker that generates menus, I am passing a startId of 0 to it. The startId controls where Wayfinder shall begin parsing the document tree, 0 is the root, therefore all our articles will be contained in the menu. Not the news articles in their subfolder though, that would require a more complex usage. If you install MODx with the default content you can examine such an example with drop down menus for each subfolder and all, sweet. For more info check the Wayfinder wiki.
Our left column is controlled by this list of tags:
<div id="col1_content" class="clearfix">
<h3>News</h3>
[[Ditto? &startID=`11` &summarize=`4` &tpl=`news_format`]]
<br/>
{{partners}}
<br/>
{{support}}
</div>
</div>Ditto is another core snippet that is extremely flexible in how it can control the formatting of aggregations of content in various ways. In this case I wanted it to display my news section like this:
Headline (Which also links to the article, causing it to display in the main content area).
Short description (Created when we create the article).
Publish date
However, when I first used [[Ditto? &startID=`11` &summarize=`4`]] I got author name too, that is not what I wanted. Btw, as you might have suspected by now the startID is the id of my news folder and summarize summarizes 4 articles sorted by date per default which is just what I want.
So how to get rid of the author name? After doing a show source in firefox followed by a ctrl+h to do a search in the whole project in eclipse I find the following in assets/snippets/ditto/lang/english.inc.php:
<div class="ditto_item" id="ditto_item_[+id+]">
<h3 class="ditto_pageTitle"><a href="[~[+id+]~]">[+pagetitle+]</a></h3>
<div class="ditto_documentInfo">by <strong>[+author+]</strong> on [+date+]</div>
<div class="ditto_introText">[+introtext+]</div>
</div>This seems to be the default formatting, but how do we change it? Part of the answer is already obvious from above in the form of &tpl=`news_format`. News_format is a chunk that we create by going Resources -> Manage resources -> Chunks, and this is how it looks at the moment:
<div class="ditto_item" id="ditto_item_[+id+]">
<h3 class="ditto_pageTitle"><a href="[~[+id+]~]">[+pagetitle+]</a></h3>
<div class="ditto_introText">[+introtext+]</div>
<div class="ditto_documentInfo">[+date+]</div>
</div>No author name, perfect, just what we want. But what are those tags? A good resource on them is the list of Document-Specific Template Variables. Or Ditto Placeholders. A more advanced Ditto tutorial is Tagged blogging with Ditto. Anyway, the only special case above is [~[+id+]~], the extra ~’s is shorthand for “create a link to the article with this id”.
This is the best example in this tutorial of how powerful the Ditto/MODx way is, we have total control over the formatting of content without writing a single line of PHP!
{{partners}} and {{support}} are just plain chunks inserted directly into the template.
The main content area consists of the following tags:
<div id="col3_content" class="clearfix">
<!-- skiplink anchor: Content -->
<h2>[*longtitle*]</h2>
[*content*]
</div>A good intro to MODx tags like these is the Using MODx Tags in your Template section of the Designer’s Guide.
If you felt that this was a bit much or went too quick you can try the Beginner’s Guide to MODx.
To be honest, to really get finished with the site you would have to do some serious CSS work in addition to the above, but that is another story.