Entity Formatter Module: A Drupal themer’s dream

Make Drupal theming as easy as writing HTML with this excellent module.

Themers rejoice. After years of wrangling with Drupal’s theming system, Entity Formatter has arrived. It makes Drupal theming as easy as writing HTML.

It’s power lies in two key areas: 1) It lets you print fields with custom markup. 2) It has no hierarchy.

If you’ve been theming Drupal websites for a while, you are probably used to Drupal’s quirks and so may not see how this is a game changer. If so, keep reading!

Installing the Module

Entity Formatter installs like any other module, but there’s an extra step. Once installed you have to use one (or more) of the following Drush commands

For theming nodes: drush efm node — module=entity_formatter_custom

For theming comments: drush efm comment — module=entity_formatter_custom

For theming entities (e.g. from ECK): drush efm — module=entity_formatter_custom

These commands basically find all your fields and creates special PHP snippets that are stored in a module called “Custom Entity Formatters”. You have to enable this new module before theming. If you later add a new field to your site, you will have to re-run the Drush commands. The “Custom Entity Formatters” module, however, can be left alone as it automatically updates.

Benefit 1: Print fields with custom markup

By default, Drupal loves wrapping fields in multiple DIVs that are littered with classes. This is a pain when using CSS techniques like floats and Flexbox as the extra wrappers get in the way of crafting layouts.

You can, of course, use Drupal template files to render fields without markup. But the code isn't very neat. Doing it the correct way requires multiple lines of code per a field!

With Entity Formatter, your fields can be rendered with just a single snippet wrapped in whatever markup you wish.

For example, if I want to print my Intro field in H3 tags, I simply need this code. <h3><?php print $page->getIntro()->text();?></h3>

If the field is optional and I don't want the markup present when the field is empty, I can use this simple isDetlaValid function:

<?php if ($page->getIntro()->isDeltaValid()): ?> 
<h3><?php print $page->getIntro()->text();?></h3>
<?php endif; ?>

Benefit 2: Use fields without hierarchy

Drupal pages are very hierarchical.

At the top level, we have nodes. On the second level, we have fields. On the third level, we have sub-fields.

What's a sub-field?

In Drupal, fields can have multiple instances. For example, on website I recently completed called the Blessings Journal @ Win at Life, I have a list of features, which is a simple text field. The content creator can click "add another item" in the Drupal UI to add another feature to the list. These features form the third level of the Drupal hierarchy.

Normally in Drupal theming, getting the features list to display as a HTML UL element would require a separate template file for the field in addition to the node.tpl.php.

With entity formatter, however, I can use a foreach command to do everything directly from the main node template file:

<ul class="area-nav"> 
<?php foreach ($page->getList() as $entry): ?>
<li> <?php print $entry->text(); ?> </li>
<?php endforeach;?>

Sub-fields and Paragraph module

The Paragraph module lets you put fields inside fields, which is a great way of creating a consistent node authoring experience for content creators as they can ensure their content always follows a set pattern.

Theming paragraph fields often requires separate templates for each paragraph instance. In some cases, it may even require additional template files for the fields inside the paragraph! With Entity Formatter, however, everything can be themed directly from the main node.tpl.php file.

Entity formatters and images

Entity Formatters handling of images is simply superb. On the main Win At Life site images on the actual node pages are full screen. On the index pages, they use a thumbnail.

Normally achieving this in Drupal would require digging around on the display mode screens or using an untidy code string.

With Entity Formatter, you can simply insert the name of your Image Cache preset: <?php print $page->getIntroImage()->setImageStyle('lead-image')->alt();?>

Commands such as alt() and src() give you more control over your images, allowing you to print just the alt text or the image source URL.

Entity formatters and Views theming

Entity Formatter even improves Views theming. By default, you can't use Entity Formatter code in a Views template.

However, you can make use of Drupal display modes. By default, all Drupal nodes have different display modes, such as teaser and full content. These can be themed by creating a template that has the following name: node—-content-type—-view-mode.tpl.php.

You can use Entity Formatter code in these display mode template files. Once you've made your template, go to your View and change the display from Fields to Content and then pick the view mode you want to use.

This is so much easier than adding fields to a View and then configuring them. You can quickly insert code snippets directly in the template files and add the markup you want.

If you need more view modes then the ones Drupal ships with check out the Entity View Modes module.

But what about UI theming modules?

In the past few years, we've seen the new trend of UI theming. Modules such as Panels, Display Suite, and Fences let you control the markup directly from the fields interface.

I personally don't like this for a couple of reasons. Firstly, it bloats your database with HTML code. Secondly, if you are doing magazine style layouts like the one on the Blessings Journal, it's not long before you have to switch between multiple screens to change the markup. Thirdly, it makes it harder to add other useful elements to your HTML such as data attributes.

Inserting and customising snippets with Entity Formatter allows for a more streamlined theming experience.


Ultimately, the best theming approach in Drupal will depend on your needs and design. For me Entity Formatter comes highly recommended as it allows me to get the exact mark-up I want with less fuss compared to traditional methods.

Check out a podcast covering this module on Design Mind.

Originally published at madhu.co.