“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.

This post is mainly an introduction to the ManagerManager plugin written by Nick Crossland. In my opinion it is absolutely indispensable, unless you’ve come up with your own way of doing the same thing. But it took me a while to get it. It’s possible I was just having a stupid day, but on my first encounter with it I was puzzled and frustrated for a while about how and when to use it, so maybe I can plug some gaps here. Let me just say again that this plugin is absolutely indispensable. Well, I guess you could get by without it, but at the very least it’s very excellent.

Essentially, it allows you to control how resources (also referred to as “documents,” mostly corresponding to web pages) are edited, depending on the role of the user and/or the template used by the resource. Using it you can customize and control the user-experience for content editors by changing, in several ways, the document fields and template variables that are available to users editing a resource. And you do all this by defining “rules” in a single rules file or chunk.

Install

Before I go into what exactly you can do with it, here’s how to set it up. ManagerManager came bundled with my MODx 1.0.2 installation, but you can also get the package from the MODx website. The two things to look out for in the download are plugin.txt and the managermanager folder. Put that folder in yoursite.com/assets/plugins and go to yoursite.com/assets/plugins/managermanager/docs in a browser to read the documentation (you can also see it here on my site if you haven’t downloaded it yet).

In the documentation you get details on installing and setting up, but I’ll briefly go over the steps here. Basically all that’s left to do at this point is to create the plugin in MODx with the contents of plugin.txt. Go to Elements > Manage Elements > Plugins > New Plugin and paste in the code, then check the System Events described in the docs, and then paste in the configuration string in the Configuration tab. The string looks like this:

By the way, if you’re not aware, configuration parameters are defined like this:

So in the configuration string for ManagerManager given above, it sets up a text-field parameter called config_chunk but leaves it blank. If you want to use a chunk to manage your rules, put the name of it in here. My MODx installation already had the chunk mm_demo_rules.

When the plugin runs, it looks for rules in the chunk that you’ve defined in the configuration tab, but if that chunk is empty or nonexistent or not defined in the configuration tab (as in my case), then it looks in the file managermanager/mm_rules.inc.php. I use this file for my rules rather than a chunk, but it’s a matter of taste. Note that if there’s something in the chunk (and the chunk is defined in the configuration), none of the rules in the file will be applied, because the file won’t even be included.

The Rules

So what do the rules actually look like? Basically they’re function calls. All of them are described in the documentation, in the Fields, Tabs, Widgets and Sections pages, and the names to use to refer to the fields are described in Field names. Note that the although these field names mostly correspond to the MODx database field names, not all of them do.

Here’s an example rule:

Your rules file or chunk is just a bunch of these calls, and every time somebody edits a resource, they will be applied. Easy.

Hiding Fields

You may want to hide fields from users who are editing certain resources, because you don’t want those values to be changed. Say you want to fix the value of the parent resource, or you want to ensure that Show in menu is always set to true and can’t be changed. Or maybe you just don’t want to confuse users with too many fields (if there’s no need for them to see the URL alias or Link Attributes fields, why not hide them?).

One of my uses for this is hiding the resource content editor for templates that contain only dynamic data such as tables, feeds, blog post excerpts, and so on. For these pages, all the content is generated by snippets, in combination with chunks, and anything entered as content by the user will not show up (because in the templates and chunks I’m not using the [*content*] field at all) – so it makes sense to remove that functionality.

Setting Default Values

You may want to ensure that certain resources always have the same default value for particular fields. I used this recently when I wanted to set the value of content-type to application/pdf by default. I saw this as a must-have feature, rather than a nice-to-have, because one of the main ongoing actions of editors of this site was to add new PDF documents, the links to which would then be displayed by a snippet in various parts of the site.

Incidentally, this only made sense if I could make sure that the resources in question had a specific default template, so I also used my own plugin to automatically set the template for these resources. I didn’t realize at the time, but I probably could have used an MM rule for that too, namely mm_hideTemplates (see below).

Renaming Fields

Renaming fields changes their labels. One way that I used this was to change “Long title” to “Page heading,” because that’s how I was using [*longtitle*], i.e. as the <h1> heading (in other words, in the relevant chunk I had <h1>[*longtitle*]</h1>). Changing the label just made it clearer for users. The flexibility of MODx means that, by default, fields are named in a fairly abstract way, because you can use them however you want, so more meaningful labels are often better, once you’ve settled on how you’re going to use them.

Changing the Help Text

This way you can help to tailor the user’s experience to the specific functionality of your implementation. If you’ve customized things to a great extent, some of the help text will begin to be useless or even misleading, so it’s good to keep things tight by paying attention to stuff like this.

Synching Fields

Use this to ensure that fields always have the same value. I haven’t used this myself, but I’m sure I will.

Inheriting Values From the Parent Resource

Does what it says on the tin.

Hiding Templates

The above example removes the (blank) template from the Uses Template drop-down. As I noted above, it looks like I could have used this when I needed to set a default template by hiding all the other templates from the drop-down list, instead of using my own plugin. I haven’t tried it though.

Tabs, Widgets and Sections

There are also a number of functions for changing the tabs and sections. For example, if you want to restrict users to editing the content field and nothing else, hide the Settings tab as well as hiding fields in the General tab. Sections, by the way, are a MODx way of grouping fields together in the edit screen. Common ones you’ll see are “Resource content” and “Template variables.” As for widgets, ManagerManager provides a few functions for changing the widget that is rendered for a field, eg. colour-picker or image preview.

With careful combinations of rules, and any logic you fancy putting in the rules file, you can get as clever as you like.

For more information on ManagerManager have a look at the dedicated board on the MODx forum.

For the next MODx-related post…I’m not sure. One thing I’ve found interesting: I struggled for a while to find a satisfying way of combining two requirements regarding javascript. 1) How to manage and maintain my javascript files easily and avoid any duplicated code; and 2) also ensure that the resulting page is optimized for speed (sometimes I find it quite hard to settle for a YSlow grade of B). I’d love to see how other developers manage this in MODx.