Now that we know how to use snippets and some of the basic rules for creating snippets, let's get down to the business of creating some working snippets. We'll start small and simple, then finish up with something a bit more challenging.
Displaying Dates
Way back in the article on how templates work, I mentioned that dates such as createdon, pub_date and editedon for a resource are stored as UNIX timestamps in the database. These need to be converted to human-friendly formats if you want to display them on your page. This simple snippet will do just that.
<?php
$date = $modx->documentObject['editedon'];
$output = date("F j, Y, g:i a", $date);
return $output;
?>
This will display the date and time the resource was last edited.
For example, this page was last edited on September 8, 2010, 7:20 am
Including External Files
I promised to show you how to use a snippet to include an external file for your template, so that you could use editors such as Dreamweaver to work with your template. That's an easy one-liner (well, two, actually, with the snippet's obligatory return ending), although a few bells and whistles can be added to make it more robust. Here's the simplest version.
<?php include "assets/templates/mytemplate/template.php"; return; ?>
Gotcha - Never try to make a one-liner using something like
return include "assets/templates/mytemplate/template.php";
While this will work, the file will be included, what actually gets returned is the return value of the include directive, which is 1 for success and 0 for failure. So your page will have this puzzling 1 hanging around!
Just put the snippet tags in the content field for your template, and now you can edit the template.html file to your heart's content.
But what if something happens to your template.php file? It gets deleted, renamed or corrupted somehow? You'd end up with a site full of blank pages or nasty PHP errors. So let's add some error handling to the snippet.
<?php
$tplfile = "assets/templates/mytemplate/template.php";
if(is_file($tplfile)) {
include $tplfile;
return;
} else {
return "[*content*]";
}
?>
Now if the template.php file can't be loaded, the template will at least contain the page's content. Not pretty, perhaps, but the site is still alive.
Let's take this a step further, and put into practice a few things we discussed in the Creating Snippets article.
<?php
$tpl = isset($tpl) ? $tpl : "template.php"; // is the tpl file set in a parameter?
$tplfile = $tplpath . $tpl; // build relative path from property and parameter
if(is_file($tplfile)) {
include $tplfile;
return;
} else {
return "[*content*]"; // if file can't be included, at least display the page's content
}
?>
In the snippet's Default Properties, set the path to the template file's location.
Add the &tpl parameter to the snippet call in the template's code field, and now the snippet can be used for different templates.
Now, the snippet first checks to see if the &tpl parameter was used in the snippet tags; if not a default file is used. The full path is built from the property we set in the snippet's Properties tab. The file is checked to see if it is really where it's supposed to be, and if it is, it is included.
Finally, if the specified file can't be found, the content tag is put in the template, which while not very attractive will at least keep the site from being completely dead.
So we've gone from a very simple two-line snippet to a flexible, fairly robust bit of code that can (reasonably) gracefully recover from errors.
These examples should be enough get you started on your own snippets, and help you better understand the more complex snippet like eForm or Ditto if you want to examine their code.
Comment On This Article
Do you find something unclear? Did I miss something or get something wrong? What do you like or not like about this chapter? Please do not ask for help here; use the forums if you need help.