Custom Formatters 7.x-2.4

8 Jul

Stuart Clark

Full disclaimer, I am saying this as the developer of the module, but it is definitely the module that I am the most proud of.

That’s Custom Formatters with a capital CF; custom formatters (with lower case characters) are a core part of Drupal, they are the layer that takes Field data from the database and presents it to the frontend of your website in a more visually appealing style.

The Custom Formatters module quite simply adds the ability for site builders and developers to create or tweak their own custom formatters from within the website, never needing to touch the site file system.

And now, with Custom Formatters 7.x-2.4, it’s even better.

 

What’s new in Custom Formatters 7.x-2.4?

  1. New Formatter format/engine; Formatter presets
    This is the big one, the catalyst for the new release; Formatter presets give you the ability to take complex Formatters with settings and turn them into new simplified, end-user approved formatters.
    More on this below.
     
  2. Support for Display Suite fields
    I’ve been a big fan of Display Suite (DS) since I first came across it years ago. Custom Formatters did have support for DS in the Drupal 6 version, but I had made the decision to not support it in Drupal 7 due to DS’s own Code fields. Due to popular demand (my self included), that decision has been reversed.
     
  3. Fixes to the HTML + Token format
    HTML + Tokens was always supposed to be the format that made this module site builder friendly, but to various issues with native Field tokens in Drupal 7 it has never worked overly well. I’m happy to say that this is no longer the case, and HTML + Tokens formatters work extremely well.
    More on this below.
     
  4. Miscellaneous bug fixes.

 

How to use Custom Formatters?

Using custom formatters is relatively straight forward, anyone who has used any CTools Export UI based module (Views, Context, etc) should be familiar with the user interface:

By default it comes with some example formatters, and you can import others from your own collection or from CustomFormatters.com, but chances are you are most likely going to want to create your own Custom Formatters.

To do so, simply click the + Add button and you will be presented with the following interface:

You will need to provide the following information:

  1. Formatter name
    The human readable name of the formatter, what the site-builder, or possibly end user will see when choosing a formatter.
    Entering this value will auto-generate the Machine name, which can also be manually edited.
     
  2. Description
    Only used within the Custom Formatters interface, useful to explain what the purposes of the formatter are, where it’s to be used and what modules it requires.
     
  3. Format
    The format/engine of the formatter you are about to create. Out of the box there are three formats, but additional modules are able to provide additional formats. The format determines the method of how the Formatter is created, and as such I will go into more detail for each individual format below.
     
  4. Field type(s)
    Depending on the chosen format, you need to assign the formatter to one or many field types types (image, file, textfield, etc).
     
  5. Formatter
    The formatter interface itself is dependent on the chosen format, more details on each format below.

Once you have created your formatter, you can preview the formatter within the Preview interface. This allows you to apply the formatter to an existing field on an existing entity, or if the Devel generate module (provided by the Devel module) is present you can apply the formatter against a devel generated item.

Lastly, ensure you save your formatter, as you don’t want all your hard work to go down the drain. Alternatively, Save & Edit frequently during the creation of the formatter.

 

Format types

Out of the box there are three formats available with Custom Formatters, but the module is written in such a way that any 3rd part module could add an additional format.

 

PHP

The PHP format was the original format engine for the Custom Formatters module, it mimics as closely to writing a formatter within a Drupal custom module as feasible, and as such is only recommended for use by those with knowledge of PHP and the Drupal API.

The PHP format is provided with all required data for writing a formatter in the $variable array, as well as an individual variable per array key ($variable['#items'] is the same as $items):

  1. $obj_type: The entity type (node, taxonomy_term, etc)

  2. $object: The entity object.

  3. $field: The field definition.

  4. $instance; The field instance.

  5. $langcode; The language code.

  6. $items; An array of all field item data for formatting.

  7. $display; The formatter display settings and formatter settings.

With this data you are free to do with what you will. However, in general a standard pattern is to iterate over the $items array and populate an $elements array which is finally returned to Drupal:

  1. $elements = array();
  2.  
  3. foreach ($items as $delta => $item) {
  4. $elements[$delta] = array(
  5. '#markup' => $item['value'],
  6. );
  7. }
  8.  
  9. return $elements;

This pattern allows support for multiple items, as well as taking advantage of Drupal's Render Arrays system.

 

HTML + Tokens

The HTML + Tokens format allows you to create simple and easy Custom Formatters with no more than HTML and Tokens, as the name implies. While this has been available for a long time in Custom Formatters, in the latest release it has been vastly improved upon, primarily with improved support for the Entity tokens module (provided by the Entity API module).

Any entity type token can be used, as well as chained tokens specific to the field in use, but it is important to take into account where the formatter will be used when choosing the formatters. For instance, if you were to use a Taxonomy term token on an Image field formatter that is going to be displayed on a Node entity, the Taxonomy term token will not work.

The markup in your formatter is rendered per field item, so if you are using a multi-value field, each value will run through your formatter. This is where the improvements to the Entity tokens module support is important, as you can target the field values directly.

Example:
If you are formatting an Image field, you can target the URL using the Entity tokens chained token [file:url], which is unique to each item value.

In addition to the improvements with the Entity tokens module integration, I also released a new module, Field tokens, which adds two different type of tokens which are extremely useful with HTML + Tokens formatters:

  1. Formatted field tokens
    Tokens that allow you to pass the field through an existing Formatter with provided formatter settings.
    Example: [formatted_field-image:image:image_style-thumbnail] would pass the current image field value through the Drupal core Image formatter via the thumbnail image style.
     
  2. Field property tokens
    Tokens that provide you with the specific property of a field value.
    Example: [field_property:alt] would return the Alt value for the current image field value.

 

Formatter preset

A new addition to the Custom Formatters module, and while maybe not the most obvious, it is a great addition that was a direct response to the Wysiwyg Fields module.

The Formatter preset format allows you to replace formatters with complex formatter settings forms with simple preconfigured formatters with more user friendly names. Especially useful when the formatter choice is exposed to a non-technical user.

Below you can see an example of the Youtube field and formatter in use in Wysiwyg Fields with it’s abundance of formatter settings (on the left) and a Formatter preset of the same formatter preconfigured as desired (on the right).

It’s obvious a lot simpler, so simple in fact that there’s no evidence that a formatter or formatter settings are present, it will just work.

Creating a Formatter preset is quite different to the other Custom Formatter formats. There is no textarea field, instead you are presented with an interface similar to screenshot below:

Things to note are:

  1. Formatter
    The existing formatter which you are using as a source for this Formatter preset.

  2. Formatter settings
    Everything below the Formatter field are specific to the chosen Formatter, they are that Formatter’s settings.

Extremely simple, but a huge improvement to the user experience.

 

Twig

While not an out of the box Format for the Custom Formatters module, I think it’s important to mention this for two reasons:

  1. Drupal 8 is coming, and it’s bringing the Twig templating system with it.
  2. This is a great example of how other modules can create new Custom Formatters format types.

The Twig format requires the Twig filter module, which doesn’t yet have a stable release, but is still well worth a look.

The interface is much like the PHP and HTML + Tokens formats, with the difference of using the Twig templating language, which is said to be simpler for frontend developers.

 

Using a formatter

Once you’ve created your formatter, that formatter can be used in many different ways, as the the Formatter system is just the theme layer to Drupal’s field system, so in general a Formatter should be able to be used anywhere a Drupal field is used.

Examples of ways to use a Formatter include, but are not limited to:

  1. Drupal’s core Manage display interface

  2. Views using the Field style

  3. Wysiwyg Fields

  4. Formatted field tokens with the Field tokens and Token filter modules

 

CustomFormatters.com

CustomFormatters.com is a companion website for the CustomFormatters module.

It contains various Formatters which can be used as they are, or as examples of how to write your own formatters.

There are also plans to provide the ability for uses to share their own formatters with others.

The website is completely open source, and anyone wishing to steal the site or contribute to the site can do so at https://github.com/Decipher/customformatters.com

 

Download Custom Formatters now

Head on over to the Custom Formatters project page and download Custom Formatters 7.x-2.3 now.

drupal planetdrupal 7custom formatters

Original Article: