Module 3.4 – Template Overrides

By saroj 19 December, 2025 Difficulty: Intermediate

Template overrides are one of the most tested theming skills in the Acquia Developer exam.

Acquia wants to know if you understand:

  • How Drupal chooses templates
  • How specificity works
  • When to override templates vs use configuration
  • How security, performance, and maintainability are preserved

Most wrong answers happen when developers override templates unnecessarily or incorrectly.

What template overrides are

Template overrides allow you to:

  • Change HTML markup
  • Change structure of output
  • Customize presentation for specific contexts

They do not:

  • Change stored data
  • Replace business logic
  • Bypass access control

Overrides are purely about presentation.

Where template overrides fit in the request–response lifecycle

High-level flow:

  1. Request comes in
  2. Drupal routing resolves controller
  3. Controller returns a render array
  4. Render array contains #theme
  5. Theme system selects Twig template
  6. Twig renders HTML
  7. Response is sent

Template overrides happen at step 5.

The #theme key (very important)

Render arrays define which theme hook to use via #theme.

Example (conceptual PHP):

$build = [
  '#theme' => 'node',
  '#node' => $node,
];

Drupal uses #theme to:

  • Identify the base template
  • Generate template suggestions

Themes never bypass #theme; they extend it.

Template suggestion system (core concept)

Drupal generates a list of template suggestions ordered from least specific to most specific.

Example for an Article node teaser:

  • node.html.twig
  • node--article.html.twig
  • node--article--teaser.html.twig

Drupal picks the most specific available template.

This system allows precise overrides without duplication.

How to override a template (mechanics)

Steps:

  1. Identify the base template (using Twig debug)
  2. Create a more specific template name
  3. Place it in the theme templates/ directory
  4. Clear cache

No configuration export is required. This is code.

Twig auto-escaping (security deep dive)

What automatic escaping means

Twig automatically escapes variables before rendering them as HTML.

Example:

{{ title }}

If title contains HTML or scripts, Twig converts them into safe text.

This protects against Cross-Site Scripting (XSS).

What XSS is (simple explanation)

XSS occurs when:

  • User input is rendered as executable code
  • Malicious scripts run in the browser

Example attack:

  • User enters <script>alert('hack')</script>

Without escaping, this script would execute.

Twig prevents this by default.

Why auto-escaping improves security and performance

Security:

  • Blocks script execution
  • Protects users

Performance:

  • Escaping is handled efficiently
  • Avoids custom sanitization logic
  • Keeps templates simple

Exam signal:
If a question mentions security concerns in templates, auto-escaping is the expected answer.

The |raw filter (danger zone)

Using |raw disables auto-escaping.

{{ content.body|raw }}

This should be avoided unless:

  • Content is already sanitized
  • You fully trust the source

Exam signal:
Unnecessary |raw usage is almost always wrong.

Attributes object (Drupal-specific and important)

Drupal passes an attributes object to templates.

Purpose:

  • Preserve classes
  • Preserve ARIA roles
  • Preserve accessibility metadata

Example:

<div{{ attributes.addClass('card') }}>

This merges classes safely instead of overwriting them.

Why attributes improve maintainability

Attributes allow:

  • Modules to add classes
  • Layout Builder to add metadata
  • Accessibility tools to function

Hardcoding attributes breaks this chain.

Exam signal:
If modifying markup, always use attributes.

Real scenario: Custom card markup

Scenario:
Homepage shows cards for Articles and Events.

Correct solution:

  • Create node--article--card.html.twig
  • Create node--event--card.html.twig
  • Use view modes

Incorrect solution:

  • One giant Twig file with conditionals

Real scenario: Removing unwanted markup

Scenario:
Design requires removing wrapper divs.

Correct approach:

  • Override the specific template
  • Keep render array intact

Incorrect approach:

  • Alter output using JavaScript

Performance considerations

Good overrides:

  • Minimal logic
  • Specific templates
  • Reused structures

Bad overrides:

  • Duplicate templates
  • Heavy conditional logic
  • Ignoring caching

Common exam traps in Module 3.4

  • Overriding templates instead of using view modes
  • Using |raw unnecessarily
  • Hardcoding classes
  • Ignoring template suggestions
  • Mixing logic into Twig

Correct answers favor specificity and safety.

Key exam takeaways

  • Template overrides control markup only
  • #theme drives template selection
  • Auto-escaping protects against XSS
  • Attributes preserve accessibility
  • View modes reduce override needs
  • Security and performance are built-in when used correctly