Just to whet your appetites for Revolution a little more, I thought I’d try to explain the new, and almost too cool, custom sets of properties in MODx Revolution. The properties can be used with any element (as OpenGeek keeps reminding me), but I’m going to explain their use with snippets, which will probably be the most common use for them.
Snippet properties are basically the things with the ampersands you’re used to putting as parameters in the snippet call. They control the behavior of the snippet. In 0.9.6 and before, the snippet programmer usually had to check to see if you sent them and, if not, set them to their default values. As a user, you had to either look at the code or find documentation somewhere on what each property was for. You had to get the case right, remember the ampersand, and use back-ticks.
In MODx Revolution, the snippet properties and their default values appear in a grid on the properties tab of the create/edit snippet screen. Each one has a drop-down box that explains what it’s for. For the snippet developer, they come to the snippet automatically with their values already set (but with a twist -- more on that later).
You can override the default values in the grid by using ¶meters in the snippet call, just like always. But, and here’s where it gets really cool, you can also create named custom sets of properties and edit the values right on the screen in a grid, then just send the name of the cusom property set to the snippet.
Here’s an example:
I’ve installed SPForm, which automatically sets up the default values and a working contact form on your site. The install is completely automatic and, if mail() is enabled, there’s nothing left to do but some styling. But on my XAMPP install, there’s no mail() server so I have to use SMTP. There are also a number of properties I’d like to tweak for a local install. I could type all the SMTP parameters and other defaults I want to override into the snippet call, but then, when I move the site to the remote server, they’ll all be there mucking things up.
Instead, I go to the SPFom edit screen, click on the Properties tab, and select "create new property set." I give it the name "Local". It’s immediately there on the screen in grid form. I edit the SMTP and other options in about 20 seconds and save the set.
I change the snippet call to:
I’m done. When I move the site to the remote location, I remove the "@Local" (or create a new set and change it to @Remote). I can also update or reinstall the snippet without losing any of my custom properties and I can change them easily in the grid at any time -- no ampersands, no back-ticks, no worrying about whether it’s "startID" or "startId" and often, no typing at all (drop-down lists).
If I use a snippet (e.g. Wayfinder or Ditto) on different pages or more than once on a page and want to have different parameter values for each call, in a flash I can create as many custom property sets as I want.
For the snippet programmer, all the values come automatically in an array ($scriptProperties). So they’re all available with $scriptProperties[’someParameter’]. Properties set in any custom property set specified in the snippet call override the defaults. In the custom property set, you can set as few or as many properties as you like. It could be just a few, or you could end up setting all of them. If, for some reason, you want to override the value of a parameter in a custom property set, you can still do that because the old-fashioned ¶meter in the snippet call, will override anything else. All this is done automatically behind the scenes. The $scriptProperties array available in the snippet already has the final set of values.
Here’s a quick crib sheet on how the properties are parsed.
- The default property values are all available to the snippet unless overridden.
- A value set in a custom property set named in the snippet call will override the default value.
- A value set with ¶meter in the snippet call will override both the default and any custom property set setting.
I also want to take this opportunity to confess that I argued strongly for a different way of handling snippet properties and boy am I glad that I wasn’t successful. This is the cat’s pajamas (and I’ve got a really gigantic cat).
If you haven’t yet installed MODx Revolution, trust me, it’s worth doing just to see this feature (and there’re no flies on the package installation system). I’m not sure which one will "revolutionize" MODx more. Once you get used to the new features (and honestly, it takes very little time) you’ll be holding your breath waiting until you can use all this on a live site.
MODX Staff
MODX Staff
