My first MODx-powered website went live today (Pinnacle Telecom Group plc), and my intention now is to share some of my experiences. From a development point of view MODx is so flexible that there are several ways of doing most things, so if like me you constantly fret about your architecture and constantly refactor your code for re-usability, you might be confused about just what is the best way of doing things, especially if you’re just starting out. So in this and forthcoming posts I’ll be discussing some of my development techniques.

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.

Filed under: MODx, web development by Alistair Robinson
Tags: cms, development, managermanager, modx, php, web