Creating a custom formatter for field outputfor Drupal 8 , 9 , 10 , and 11

With the foundations of creating a custom widget now covered, the natural progression is mastering how to display your field data. Creating a custom formatter gives you control over how data is presented, enhancing user engagement and site aesthetics. This lesson guides you through defining a custom formatter in Drupal, leveraging the flexibility and dynamism of your site content.

What is a Field Formatter?

A field formatter in Drupal determines how field data is displayed to users. It is responsible for taking the stored field data and transforming it into presentable output on the site. Formatter flexibility is crucial for tailoring content presentation to meet a specific brand aesthetic or communication goal.

Developing a Custom Field Formatter

Let’s extend the geolocation example from the previous discussions. We will develop a custom formatter that displays the coordinates wrapped in HTML tags, styled for emphasis.

Step 1: Create the Formatter Plugin

Start by setting up a directory for your field formatter, typically structured as src/Plugin/Field/FieldFormatter. Then create a file named GeoLocationStylishFormatter.php.

namespace Drupal\your_module\Plugin\Field\FieldFormatter;

use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Field\FieldItemListInterface;

/**
 * Plugin implementation of the 'geolocation_stylish' formatter.
 *
 * @FieldFormatter(
 *   id = "geolocation_stylish",
 *   label = @Translation("Stylish Geolocation"),
 *   field_types = {
 *     "geolocation"
 *   }
 * )
 */
class GeoLocationStylishFormatter extends FormatterBase {

    /**
     * {@inheritdoc}
     */
    public function viewElements(FieldItemListInterface $items, $langcode) {
        $elements = [];

        foreach ($items as $delta => $item) {
            $elements[$delta] = [
                '#type' => 'markup',
                '#markup' => '
Lat: ' . $item->lat . ' | Lng: ' . $item->lng . '
',
                '#allowed_tags' => ['div', 'strong'],
            ];
        }

        return $elements;
    }
}

This formatter takes the latitude and longitude, formats them within a custom-styled HTML structure, and ensures only specified tags are rendered, enhancing security and design.

Step 2: Implement the Formatter

When the content type using your geolocation field is displayed, this formatter will ensure the coordinates maintain the specified styling, allowing you to showcase important data compellingly.

Integration with Themes and CSS

To further customize presentation, you can integrate your formatter with custom CSS by adding a class to the HTML output. Here’s a simple CSS integration:

.geo-coordinates {
    font-size: 1.2em;
    color: #2e6da4;
    padding: 8px;
    margin: 5px 0;
    background-color: #f7f7f9;
    border-radius: 4px;
}

Such enhancements maintain consistency with your site’s overall design language, enriching the user interface.

Utilizing Custom Formatters

Once created, your custom formatter becomes selectable within the "Manage display" tab for content types, allowing site builders to choose the most relevant output style. This mechanism makes your content flexible and aligns it more closely with user expectations and aesthetic goals.

Field Formatter Rationale

By creating custom field formatters, you not only gain power over presentation but also over how field content becomes integral to user stories, contributing to narratives that engage and inform site visitors.

Conclusion

Creating a custom formatter for field output in Drupal allows you to enhance how information is displayed across your site. This lesson has guided you through building a stylish and customized display for your field data, leveraging the Block API’s capabilities not just to grab attention but to enrich user interactions with your content.

In the next lesson, "Defining Custom Views Handlers or Plugins," you’ll learn to craft complex data displays with ease, integrating your newfound knowledge in formatters and widgets with Views API tools to achieve stunning results. Continue to advance your Drupal module expertise, crafting experiences that captivate and engage!