Mapping

Overview

CivicTheme separates its component Twig files from its Drupal implementation. This separation requires preprocess functions to extract data from Drupal entities, process it as necessary, and map it to the expected properties of the UI Kit Twig file. This approach encourages building CivicTheme components in a reusable fashion where the HTML is more generalised and less Drupal-specific.

---

Quick Start

Prerequisites

• A CivicTheme subtheme

• Basic understanding of Drupal preprocess functions

• Familiarity with Twig templating

Basic Implementation

1. Create a custom include file for your field processing logic

2. Implement a preprocess hook to call your custom function

3. Update the Twig template to reference the CivicTheme component

---

Utilities

CivicTheme provides utilities to simplify preprocess function development:

• Utilities - Helper functions for common Drupal operations

---

Implementation Example

The following example demonstrates how to map a Drupal field to display as a CivicTheme tag component. This covers the fundamentals of gathering data from an entity in a preprocess function, passing it through the *.html.twig template, and setting it on the civictheme:tag component.

Step 1: Theme File

File: subtheme.theme

require_once __DIR__ . '/includes/custom_field.inc';

function subtheme_preprocess_field(array &$variables): void {
  _civictheme_preprocess_custom_field($variables);
}

What this does:

• Includes the custom field processing logic

• Calls the custom preprocess function when the field preprocess hook is triggered

Step 2: Custom Field Processing

File: includes/custom_field.inc

use Drupal\Core\Entity\FieldableEntityInterface;

function _civictheme_preprocess_custom_field(array &$variables): void {
  if ($variables['field_name'] !== 'field_custom_field') {
    return;
  }

  $node = $variables['element']['#object'] ?? NULL;
  if ($node instanceof FieldableEntityInterface) {
    $variables['custom_value'] = civictheme_get_field_value($node, 'field_c_n_custom', TRUE);
  }
}

What this does:

• Checks that the correct field is being processed

• Retrieves the node attached to the field and validates its type

• Uses the civictheme_get_field_value utility to extract the field value

• Adds the processed value to the custom_value property

Step 3: Twig Template

File: templates/field/field--node--field-c-n-custom.html.twig

{% include 'civictheme:tag' %}

What this does:

• References the CivicTheme tag component

• Passes all available properties through to the component

• Can be modified to reference custom components if needed

---

Field Naming Conventions

CivicTheme uses field prefixes to indicate scope and determine how much built-in support is available:

Prefix	Scope	What it means
field_c_n_*	CivicTheme node fields	CivicTheme already has preprocess functions and templates. Less custom code needed.
field_c_p_*	CivicTheme paragraph fields	Same as above, but for paragraph entities.
field_n_*	Custom node fields	No built-in support. You must write your own preprocess functions and templates.
field_p_*	Custom paragraph fields	Same as above, but for paragraph entities.

The most common approach is to mix both — use CivicTheme standard fields where they fit and custom fields where they don't.

Drupal Integration via Paragraph Types

To use a component in Drupal's content authoring workflow, create a paragraph type that matches the component's props. For example, a feature card component would have:

• Paragraph type: feature_card

• Fields: field_c_p_title (Text), field_c_p_summary (Text, long), field_c_p_icon (Text), field_c_p_link (Link), field_c_p_theme (List — light/dark)

Then create a preprocess include to extract field values and a Drupal Twig template that includes the component. See the Implementation Example above.

Best Practices

File Organisation

• Place custom code in dedicated *.inc files specific to the feature being implemented

• Use descriptive file names that clearly indicate the purpose

• Keep preprocess functions focused and single-purpose

Template Structure

As much HTML as possible should live in the components. The Drupal Twig templates should act as connectors to the components. It should be common for Drupal *.html.twig templates to contain only an include of a component Twig file.

Data Processing

• Always validate field names before applying custom processing

• Use CivicTheme utilities for common operations

• Ensure proper type checking for entities and fields

• Follow Drupal coding standards and best practices

---

Next Steps

• Explore the CivicTheme utilities for additional helper functions

• Review other component implementations for patterns and approaches

• Consider contributing improvements to the mapping system