This is the first in a series of articles about Snippet design and improvement. In the series, I’d like to walk you through the process of creation and enhancement of a simple Snippet. The articles are mainly aimed at people first getting their feet wet with PHP, but even if you’re not a beginner, you might find something of value here.
When I create a utility Snippet, it usually starts out as a very modest little Snippet that meets my exact needs. Later, when I start thinking about how other people might use the Snippet if it were a MODX Extra, I add features that make the Snippet more powerful, more flexible, more efficient, and more user-friendly. I thought it might be interesting to look at the steps in that process with an example Snippet.
You probably know this, but a Snippet tag is replaced by the return value of the Snippet named in the tag. If you want something on a page that can be created in the code of a Snippet. You simply put a Snippet tag where you want it to appear, then return a value as a string at the end of the Snippet. The Snippet tag will be replaced with that string.
The Request
A while back, a MODX Forum user asked about a way to highlight new Resources. If a Resource was published within the last two weeks, the user wanted to display the word NEW! next to the pagetitle. In this first article we’ll look at a simple version of the Snippet that does just that, then in future articles, we’ll look at progressive enhancements to the Snippet with some detours into MODX coding standards and good design. The Snippet tag can go in the page Template, in the page content, or in a Chunk.
The Problem
If you want to display something to highlight newly published Resources, it would be a colossal pain to have to edit the Resources every day to keep the display up to date. You could use a TV, but then you’d have to update the TV values, which might be even more of a pain. Testing the age of a Resource based on its publishedon field is very easy to do in a Snippet, and it’s a small step from there to returning the appropriate display. We’ll call our Snippet NewResource.
The Code
Here’s a version of the HTML that might contain our snippet call (say, in a Template):
<h3>[[*pagetitle]] [[!NewResource]]</h3>
[[*content]]The [[!NewResource]] tag will be replaced by the return value of our Snippet. Here’s the code of the Snippet:
<?php
if ( ((strtotime($modx->resource->get('publishedon'))) + 1209600) > time()) {
if ($modx->resource->get('published')) {
return '<span class="new_resource">NEW!</span>';
} else {
return '';
}
}Improvements
As it is, the Snippet does the job. The Snippet simply tests the age of the Resource and returns some HTML that will display the word “NEW!” if it’s less than two-weeks old.
It has to be called uncached (with the !) because we don’t want the cached results of the Snippet—we want the results to be up-to-date.
To change the interval, we can just change the number. Google will give you the value to use if you search for something like “How many seconds in one week”. As we’ll see later, there’s a more user-friendly way to do this.
There are lots of ways in which this Snippet could be improved. It has some design problems, and it’s not very flexible, readable, or user-friendly. The most obvious variation would be to use a different time period. The big number in our code (1209600) is the number of seconds in our time interval (two weeks, in this case). We have to wrap the publishedon value in strtotime() because MODX returns a human-readable string, and we need a timestamp.
You might also want to change the value returned by the Snippet. Remember that the tag will be replaced by whatever you return. It could be a word, some HTML, an image tag, or a class name. At this point, you can just put the tag where you want the return value to appear, and change the value of the string in the return line, but again, that’s not very user-friendly.
In upcoming articles, we’ll look at the process of improving this simple Snippet in various ways. Although our Snippet has a particular purpose, the steps used to improve it are common to many different types of Snippets.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.