by Jeff Eaton

Module Monday: Token Formatters

Drupal's Node Reference and Entity Reference fields do a lot of heavy lifting for complex sites with tangly content models. They allow one piece of content to point at another one, and those relationships can be leveraged when building Views of content, formatting individual piece of content for display, and so on. Unfortunately, when it comes time to display the output of a reference field, "Print the title of the referenced entity" is usually the only option. What if you want something else -- like its description, or the bio of its author? Sure, you could crack open a text editor, build a custom module, and write your own FieldAPI formatter plugin. Or, of course, install the Token Formatters module.

Screenshot of administration screen

With the module installed on your site, one subtle but important new addition appears: a "Token Formatter" for any FieldAPI node, user, or entity reference fields. Customizing the formatter's settings for a given field lets you use tokens to specify the text that will be printed and (optionally) the URL that the formatted output will link to. Want to print out a node along with the name of its author? Want to display a user reference with a link to the user's home page, instead of their Drupal user profile page? Just use the appropriate tokens, and the module does the rest.

Screenshot of resulting change to site

The only serious downside to the module is the difficulty of extracting complex field values (like formatted images) using the token system. While it's possible, the module is better suited for textual values and links. In addition, there's no token reference for site builders to look at when filling out the formatter's settings. Because there are so many tokens, it's a real challenge to guess the right ones. Token module provides a standalone page with just such a list, but if you're not familiar with it, this module's configuration screen can be a bit of a stumper. Those two issues aside, Token Formatters is a quick way of tweaking a reference field's output without writing any custom code.