Web Development by Alistair Robinson

My third MODx site is about to launch. It’s relatively simple (no forms!) so I had the chance to really concentrate on refining my architecture, and the work I’ve done will stand me in good stead for a while (unless I give in to the enticements of SilverStripe or ExpressionEngine, or just ditch the PHP altogether and finally get up-and-running with Django).

“Refining his architecture? What does he mean?” For me, learning to use MODx well has been about working out how to combine templates, template variables, chunks and snippets in a logical and efficient structure. A good application – a small one, at least – should have a shape that you can envision (if you’re the kind of person who envisions shapes, that is). The shape should be pleasing, natural and economical. In my first two MODx sites I fashioned a few butt-ugly shapes that would certainly have sullied the pages of Euclid’s Elements.

They worked, and they were clever in their ways, but I feel I’ve moved past all that now, that I’m approaching the gleaming heavenly realm of the Platonic solids, of perfect dodecahedrons and icosahedrons.

Maybe I make it difficult for myself. Two components that are mentioned so often in the MODx forum and documentation that you could be forgiven for assuming were part of the core itself, are the snippets Ditto and Jot – but I’ve never used them. And then there’s Wayfinder. I used it once, and it was great, but I didn’t really know what I was doing and I wasn’t comfortable with it, and it was a hassle to learn how to use it. In the project I’m on now I’ve just done it myself, with a “menu” snippet and a couple of chunks. I know the boundaries of the project so I can decide to avoid complication by battening things down; and there’s so little code that changing it will be easy in the event that the structure of the navigation needs to change in the future.

Incidentally, Jot and Ditto are often mentioned in connection with blogs, for which they appear to be indispensable in MODx. Well, say what you like about WordPress but it does blogging pretty damn well and is equally customizable. I fear if I try putting a blog together with MODx, things might get pretty sticky. Even if I was successful I’d still end up with something far inferior to WordPress. This is a tricky situation, because I really do want to be able to use MODx for blogs – the templating system is close to perfection, and WordPress’s is horrible. But this is all by the way.

I really appreciate the work that people put in to writing freely available, open-source code. Wonders abound. But I have to confess: I don’t have much patience when it comes to using plugins, widgets, modules or whatever. If I’m looking for one it’s to save time, so 1. I want it to behave roughly as I’m expecting, and 2. I want good documentation, i.e. documentation I don’t have to spend much time with. Otherwise, I’d rather just do it myself, gaining into the bargain the extra advantage of avoiding the overhead of features I don’t need.

In this last project I’ve been working on, the most common type of page required an image gallery to go underneath the main content, and a main image in the body of the content text. Any page of this type could have photos added to it, and they should appear in the gallery in the same format. For the solution I needed: an easy way for editors to add photos without any resizing woes; auto-generated thumbnails; a way of outputting the gallery HTML; some good HTML and CSS; and a nice Lightbox on the client-side.

I had a look around for a plugin or module but it really wasn’t worth the hassle and nothing I found seemed like a good fit, so here’s what I did. If anyone spots a problem in the code or in the concept itself, let me know.

UPDATES & THINGS TO NOTE:

• This is about MODx Evolution, not the newer Revolution
• I’m not aiming here to provide full site-wide image management. For that, something like MaxiGallery might be a good choice, and certainly provides loads more features.
• The plugin might not work in the 0.9.x versions of MODx. I’m using 1.0.2. Thanks to Dimmy for pointing this out in the comments
• The plugin doesn’t seem to work correctly when using the front-end editor
• It’s not included here but I’d recommend checking the size of the uploaded photos in the first place, and you might want to actually resize all uploaded images so as to standardize the “full-size” photos that are displayed in the lightbox.
• The code here doesn’t check for the existence of files, or handle exceptions

What we’re aiming for

Above is an example of the page type in question, with the portion of the page we’re interested in highlighted. By the way, the photos are not at all relevant to the website – this is just for illustration.

This is not particularly relevant to the MODx side of things, but for the sake of completion the image above shows the lightbox that pops up when you click on a thumbnail.

To achieve all this we need:

• A template for this kind of page
• Template variables for the photos, to apply to this template
• A chunk for the outer HTML of the gallery: gallery
• A chunk for the inner HTML: gallery_item, to be repeated for each photo
• A snippet for the body photo: body_photo
• A snippet for the gallery: gallery
• A plugin: thumbnailer, which generates thumbnails, and runs when a document is saved
• Some CSS to style the gallery HTML
• Some javascript to display the full-size images in a lightbox – I’ll use jQuery

Although it might make sense to explain the thumbnail generation first, I’m going to start with the template, template variables, snippets and chunks to demonstrate the output we’re aiming to produce, and from there move backwards to the plugin. Finally, with the MODx side dealt with I’ll say a bit about the client-side, specifically the lightbox for viewing the full-size photos.

The Template

The template itself can be whatever you like, just so long as there is one that you can target the template variables to and which you can use for all pages of this type. The relevant portion looks like this:

It’s not important that I’m using HTML5 (see the <section> tag). But if you haven’t coded in HTML5 before I heartily recommend it – you can even get it to work in IE with the inclusion of a wee javascript file. This is the first line of an HTML5 document:

Beautiful.

The Template Variables

We need some template variables, one for the main body image and one for each photo in the gallery, and the latter variables need to go in a new category, which I’ve called “Gallery.”

In the editor, this gives you something like this:

You may pick up on a crucial implication of this, namely that the number of photos an editor can add to a page is limited, almost hard-coded. I think this is probably fairly standard practice in the world of CMSs, but it went against my instincts: it’s natural to want to provide the flexibility of being able to add limitless photos. But ultimate flexibility is mostly a complete waste of time, and often holds its own problems. So editors will only be able to add eight photos to a gallery. So what? Looking at the requirements, eight was plenty. To paraphrase 37 Signals in Getting Real, it just didn’t matter. It’s amazing the time you can save by making decisions like this.

Anyway, providing for more photos per page at some point in the future would be a simple matter of the developer/administrator adding more template variables.

The Chunks

We need an outer and an inner chunk.

gallery

gallery_item

The Snippets

First of all, some configuration values to be used both by the snippets and by the plugin.

config.php

It’s not very important where this config file lives. Somewhere in “assets” is good. (And if you’re a big fan of config files you could put other things in here, such as the chunk names. Or, now that I think of it, you could pass in the chunk names in the snippet calls.)

The body_photo snippet is pretty basic, and it’s not crucial to do it this way. As usual with snippets I just include a separate file:

body_photo

body_photo.php

All this does is echo out an image tag to the page if there’s a value for the body_photo template variable, and nothing if there isn’t. Crucially, though, the image is not the one uploaded but a resized version held in a folder for the medium-sized images. More on the resizing later.

By the way, get_tv_value is just a helper function which I’ve got in utility.php:

Now for the gallery. Again, in the MODx manager we need to just include our snippet code:

gallery

gallery.php

In gallery.php, line 12 shows why we put the template variables for the gallery in a new category: we can get a MySQL result for the eight variables. Immediately afterwards we loop through that result to build a bunch of list items, each time injecting values into the gallery_item chunk, which is the inner, repeated chunk of the gallery HTML. Each iteration will replace the various placeholders, [+big+], [+title+] and so on, producing something like this:

Notice that the actual image for the image tag is the thumbnail version, and the surrounding anchor links to the original. Also notice the rel=”lightbox” value, which will be used by the JavaScript.

When we’ve got all the list items it’s time (line 41) to inject them into the outer chunk, gallery, by replacing the placeholder [+gallery_items+]. The end result is something like this:

And then it’s echoed out to the page. With all the template parsing done, the HTML that’s sent to the browser will look something like this:

That’s it for the output side of things. But how do we get those thumbnails, and the medium image, where they’re meant to be?

The Plugin

I’ve called the plugin thumbnailer, but it actually does one other thing, which is generate a medium-sized version of the body photo, which is exactly the size required for the page.

As with the snippets I include an external file:

thumbnailer

Notice the lack of PHP opening and closing tags. In plugins, unlike snippets, you always exclude them (and you always forget to.)

The one other thing to do to set up the plugin in the manager is check the OnDocFormSave System Event, as shown below.

thumbnailer.php

My first instinct when writing this was to use the MODx API to get the template variable values, but when the plugin runs it’s too early to do that, so we have to use $_REQUEST to get the form values directly from the editor. The naming scheme for template variable input elements is “tv[template variable id],” e.g. in my case it was tv9 to tv17 for the gallery variables.

For the thumbnails, we can get the same MySQL result that we used for the snippet (line 21), and then in the loop, concatenate the input name using the template variable IDs (line 28). For the body photo, we can get the name for the input by first getting the ID of the body_photo template variable based on its name (line 37).

For the resizing itself, I’ve used a small class called ImageHelper, which is kindly provided here at Tips for Twits. I’ll include the code here for completeness:

ImageHelper.php

It takes care of cropping and resizing very nicely, and is the simplest and most effective code for this kind of circumstance that I’ve found.

So let’s say an editor has their document looking like this:

In the file system, the result of saving this document will be the following (with all other files excluded).

Client-Side

It’s a simple job to style the HTML output with CSS, so I won’t cover that. So, let’s briefly cover the lightbox. First it needs some CSS like this:

Recall that in the gallery each list item’s image link has rel=”lightbox”. We can use this in following code, which, aside from its dependence on jquery, is the entirety of the lightbox script (it doesn’t work in IE6 though, last time I checked – some tweaking required for that).

Click on the photo below for a demo.

So there you have it. I hope you find it shapely, pleasingly simple, and easy to maintain.

Tags: cms, content management, evolution, gallery, image, jquery, MODx, photo, php, plugins, snippets, web development
Posted in MODx, web development | 10 Comments »