Multi-Value Custom Fields for Textpattern: aam_split_custom_field
The custom fields feature provided by Textpattern is one of the things that make it such a flexible CMS. On the other hand, the ten-field limit and inability to establish relationships between fields can be a frustrating roadblock. The new aam_split_custom_field plugin for Textpattern helps break down that roadblock.
This plugin lets you collect related pieces of information into a single field, pull one or more of them back out again, and create conditional content based on individual values in the collection.
NOTE: requires version 4.0.4 or higher of the open-source Textpattern content management system.
Download aam_split_custom_field-1.0.txt (8.6KB, 389 downloads)
The collections themselves are simple string-delimited lists — easy to create, but flexible enough to accomplish some interesting things. With the aam_split_custom_field template tag, you can extract and output a single value or several successive values from the field using your choice of HTML markup. For example, you can turn a delimited custom field into a bulleted list or a series of paragraphs. The aam_if_scf conditional tag does comparisons against individual values from the delimited field.
This Sounds Familiar…
This plugin serves a similar purpose to Steve Dickinson’s sed_pcf “packed custom fields” plugin. So why make anther plugin, and which one is better for you?
- This plugin has a simpler syntax for custom field data than sed_pcf, but sed_pcf lets you give data greater structure.
- Consider using aam_split_custom_field when highly structured data is unnecessary, or when novice users will be maintaining the site.
- Consider using sed_pcf when structured data is important, or for sites with more advanced users.
- This plugin offers a convenient way to generate marked-up output from several successive values in a list; sed_pcf lacks a similar feature, but lets you pick and choose specific values by name.
- Consider aam_split_custom_field when dealing with lists or collections of a fairly general nature (e.g. product features).
- Consider sed_pcf when data is more specialized (e.g. product color, size, price, etc.).
Although I haven’t tried, it should also be possible to work with both plugins on the same site. You can use sed_pcf for some custom fields, and aam_split_custom_field for others.
Some Examples
You’ll find all the details in the plugin’s built-in documentation, but a few examples should illustrate how it might help you.
For all these examples, we’ll be using a hypothetical custom field called zoo_animals. This field has the following content:
Giraffes:Toucans:Llamas & Camels:Bears:Monkeys
The Basic Template Tag
<txp:aam_split_custom_field name="zoo_animals" delimiter=":" />
That’s the simplest form of the tag. It will output all the items in the list, separated by line breaks:
Giraffes<br />
Toucans<br />
Llamas & Camels<br />
Bears<br />
Monkeys
Getting Fancy
You can use offset, limit, and other attributes to control the tag’s output.
<txp:aam_split_custom_field name="zoo_animals" delimiter=":"
offset="1" limit="3" escape="html" wraptag="ul" break="li"
class="foo" breakclass="bar" id="baz" />
The above tag construction will give you this:
<ul id="baz" class="foo">
<li class="bar">Toucans</li>
<li class="bar">Llamas & Camels</li>
<li class="bar">Bears</li>
</ul>
Getting Traditional
You can mimic the behavior of the built-in <txp:custom_field /> template tag by setting the limit to 1. This will cause all the formatting-related attributes (except escape) to be ignored. This tag:
<txp:aam_split_custom_field name="zoo_animals" delimiter=":"
offset="4" limit="1" break="p" />
Gives you this output:
Monkeys
Getting Conditional
The aam_if_scf container tag is for comparisons and conditional content.
<txp:aam_if_scf name="zoo_animals" offset="4" delimiter=":" val="monkeys">
<p>The monkeys are eating bananas.</p>
<txp:else />
<p>The bears ate all the monkeys. How sad.</p>
</txp:aam_if_scf>
It’s important to remember that this comparison is case-sensitive. In the above example the monkeys will always get eaten, because the comparison value isn’t capitalized.
DISCLAIMER: No monkeys were harmed in the making of this plugin.
UPDATE: Important Forward-Compatibility Note. The behavior of the plugin’s conditional tag will be changing in the next release. It will become possible to compare a user-specified string against every item in the delimited field (instead of just one selected item). This feature will be invoked by omitting the offset attribute or explicitly setting it as empty. That’s a change from the current behavior, which has offset defaulting to 0. If you use the conditional tag in production, I recommend specifying the offset attribute, even when you intend it to be 0.
Getting Creative
When you combine this plugin with other Textpattern plugins, some interesting things become possible. I created the earliest version of the plugin while working on a project that also used Gerhard Lazu’s glz_custom_fields. That fantastic plugin allows Textpattern’s custom fields to become drop-down menus, radio buttons, or checkboxes instead of just plain text fields.
I needed the options for a single drop-down menu to represent two pieces of related data: a company name and the company’s phone number. These two options would always need to be chosen together, and always match with one another. On the page itself, they would appear separately. Using two custom fields was too error-prone, and the syntax of sed_pcf would have made the options less intuitive to read.
The work-around that eventually became this plugin provided the perfect solution to the problem. I hope that you find it useful in your own work. If you need help with the plugin, post a comment below or leave a message in the support thread on the Textpattern forum.
License
Copyright © 2007 Adam Messinger.
Distributed under the terms of the BSD license.