This article has been migrated from f3 Internet, with permission.
MODx is a lightweight PHP-based content management system. It has the concept of “snippets”, “chunks” and “template variables” that come together to create a flexible system that’s perfectly suited for developing custom behaviour. This article assumes that the reader is already familiar with these concepts. Please refer to the MODx learning resources if not.
vCards are a basic file format used for storing information about people and organisations, such as their name, telephone number, email address, etc. Generally, they can be easily and automatically imported into applications that have an address book, like a personal organiser or email client, which as a web site owner gives your visitors a one-click import of your details into their address book.
hCard is a Microformat based on vCards. Microformats are a basic method of augmenting the normal markup of a web page with open data for the Semantic Web. As the semantic web becomes more relevant, with the big search engines looking for an increasing amount of open data and a variety of interesting applications emerging, the small effort involved in putting Microformats on your site is well worth it for a presence on the next generation of the web.
So, on to the method, which I’ll present as step-by-step instructions.
You will need a couple of snippets:
- Ditto, which comes by default with MODx.
- vCard, available in the MODx extension repository here: Package: vCard | MODx CMS / CMF.
These instructions were written for MODx Evolution 1.0.4 (which comes with Ditto 2.1.0) and vCard 0.4, but they’re likely to work with most versions of MODx Evolution and compatible snippets.
Most of the heavy lifting is done by the vCard snippet.
1. Make sure you’ve got the prerequisite snippets installed.
2. Create a new vCard template whos content is simply [#content*].
3. Create template variables for each bit of vCard data, of the Text input type, associated with the vCard template. Place in their own category for convenience. TVs used for this example are called ‘name’, ‘title’, ‘email’, ‘tel’ and ‘mob’.
4. In the system configuration, add a new content type (AKA media type) of text/directory. This will be used for the vCards.
5. Create a new hCard chunk, responsible for producing vCard data as a microformat and linking to the associated vCard:
<div class="vcard"> <div><a href="[~[*id*]~]/vcard?id=[+id+]" title="Download vCard">Download vCard</a><a href="[~[*id*]~]/vcard?id=[+id+]" title="Download vCard"><img src="/assets/images/icon-hcard-download.png" alt="Download vCard"/></a></div> <div>Name: <span class="fn">[+name+]</span></div> <div>Title: <span class="title">[+title+]</span></div> <div>Email: <a class="email" rel="nofollow" href="mailto:[[ObfuscateEmail?email=`[+email+]`]]">[[ObfuscateEmail?email=`[+email+]`]]</a></div> <div>Telephone: <span class="tel">[+tel+]</span></div> <div class="tel">Mobile/<span class="type">cell</span>: <span class="value">[+mob+]</span></div> <div>Note: <span class="note">[+content+]</span></div> </div>
Note that this hCard chunk follows the spam-prevention advice from hCard Brainstorming – Spam Prevention and uses a basic snippet which I called ObfuscateEmail to replace an email’s ampersand with its hex character code as follows:
6. Create a container resource to hold the hCards. In this example we’ll call it ‘Person Directory’.
7. Add a child called ‘vCard’ to the container. Its media type should be set to text/directory and its contents should call the vCard snippet using the TVs we created:
[!vCard? &urlParam=`id` &name=`*name*` &job_title=`*title*` &email=`*email*` &tel=`*tel*` &mobile=`*mob*`!]
Note the stars around each parameter value, which tell the vCard snippet to grab the actual values from the TVs.
8. Edit the ‘Person Directory’ container so its contents calls the Ditto snippet to output all child resources, using the ‘tpl’ parameter to wrap the children in the ‘hCard’ template and the ‘filter’ parameter to ignore the vCard (id 3 in this example) and any other child resources we don’t want:
[[Ditto? &tpl=`hCard` &orderBy=`createdon ASC` &filter=`id,8,2`]]
9. For each h/vCard needed, create a child in the ‘Person Directory’ container that uses the vCard template and set its TVs to the required values. The resource content will be shown as the h/vCard’s ‘note’ field.
That’s it! You should have an hCard directory with vCard downloads.
- Microformats map class names to field names, for example class=“tel” indicates that a telephone number will follow. The class names are not namespaced and are likely to be names picked for other classes already on your site, so watch out for them picking up existing styling from your CSS.
- If you have a auto-generated menu or sitemap, or anything else that automatically lists your site’s resources, you’ll need to exclude the vCard resource because it’s useless unless requested with parameters (as via the hCard’s download links).
Update 24/06/2010: Added index, cleaned up hCard markup and added Gotchas section.
Posted by Stephan on 22/06/2010.