drupal-frontend（Drupal 前端）

Drupal Front End Development

Overview

Enable expert-level Drupal front end development capabilities. Provide comprehensive guidance for theme development, Twig templating, preprocessing, responsive design, and asset management for Drupal 8, 9, 10, and 11+.

When to Use This Skill

Invoke this skill when working with:

• Theme development: Creating or customizing Drupal themes
• Twig templates: Writing or modifying.twig template files
• Preprocessing: Implementing preprocess functions for templates
• Template suggestions: Adding custom template naming patterns
• CSS/JS libraries: Managing theme assets and dependencies
• Responsive design: Implementing breakpoints and mobile-first design
• Rendering system: Understanding Drupal's rendering pipeline
• Theme hooks: Implementing theme-related hooks and alterations

Core Capabilities

1. Theme Development

Build complete, standards-compliant Drupal themes with proper structure:

Quick start workflow:

1. Use theme template from assets/theme-template/ as starting point
2. Replace THEMENAME with your theme's machine name
3. Replace THEMELABEL with human-readable name
4. Customize templates, CSS, JS, and libraries
5. Enable theme and configure via Appearance UI

Theme components:

• .info.yml - Theme metadata and configuration
• .libraries.yml - CSS/JS library definitions
• .theme - Preprocess functions and theme logic
• .breakpoints.yml - Responsive breakpoints
• templates/ - Twig template files
• css/ - Stylesheets
• js/ - JavaScript files

Reference documentation:

• references/theming.md - Complete theming guide with examples

2. Twig Template System

Master Twig syntax and Drupal-specific extensions:

Twig fundamentals:

• {{variable}} - Print variables
• {% if/for/set %} - Control structures and logic
• {# comment #} - Comments and documentation
• {{var|filter}} - Apply filters to variables
• {% extends %} - Template inheritance
• {% block %} - Define overridable sections

Drupal-specific Twig:

• {{'Text'|t}} - Translate strings
• {{attach_library('theme/library')}} - Load CSS/JS
• {{url('route.name')}} - Generate URLs
• {{path('route.name')}} - Generate paths
• {{file_url('public://image.jpg')}} - File URLs
• {{content|without('field')}} - Exclude fields

Common templates:

• page.html.twig - Page layout structure
• node.html.twig - Node display
• block.html.twig - Block rendering
• field.html.twig - Field output
• views-view.html.twig - Views output

3. Preprocessing Functions

Modify template variables before rendering:

Preprocess pattern:

function THEMENAME_preprocess_HOOK(&$variables) {
  // Add or modify variables
  // Access entities, services, configuration
  // Prepare data for templates
}

Common preprocess hooks:

• hook_preprocess_page() - Page-level variables
• hook_preprocess_node() - Node-specific data
• hook_preprocess_block() - Block modifications
• hook_preprocess_field() - Field alterations
• hook_preprocess_html() - HTML document

Best practices:

• Keep logic in preprocess, markup in templates
• Use dependency injection when possible
• Cache properly with cache contexts/tags
• Document complex preprocessing

4. Template Suggestions

Provide specific templates for different contexts:

Suggestion patterns:

page--front.html.twig                  # Homepage
page--node--{nid}.html.twig            # Specific node
page--node--{type}.html.twig           # Content type
node--{type}--{viewmode}.html.twig     # Type + view mode
block--{plugin-id}.html.twig           # Specific block
field--{entity}--{field}.html.twig     # Specific field

Adding suggestions:

function THEMENAME_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  // Add custom suggestions
  $suggestions[] = 'custom__suggestion';
}

5. CSS & JavaScript Management

Organize and load theme assets efficiently:

Library definition:

# THEMENAME.libraries.yml
global-styling:
  version: 1.0
  css:
    base:
      css/base/reset.css: {}
    theme:
      css/theme/styles.css: {}
  js:
    js/custom.js: {}
  dependencies:
    - core/drupal

Loading libraries:

• Global: Define in .info.yml
• Conditional: Use attach_library() in templates
• Preprocessed: Attach in preprocess functions

Best practices:

• Separate CSS into layers (base, layout, component, theme)
• Use CSS aggregation in production
• Minimize JavaScript dependencies
• Leverage Drupal's asset library system

6. Responsive Design

Implement mobile-first, accessible designs:

Breakpoints definition:

# THEMENAME.breakpoints.yml
THEMENAME.mobile:
  label: Mobile
  mediaQuery: 'screen and (min-width: 0px)'
  weight: 0

THEMENAME.tablet:
  label: Tablet
  mediaQuery: 'screen and (min-width: 768px)'
  weight: 1

THEMENAME.desktop:
  label: Desktop
  mediaQuery: 'screen and (min-width: 1024px)'
  weight: 2

Mobile-first approach:

1. Design for smallest screens first
2. Enhance for larger viewports
3. Use responsive images
4. Test across devices
5. Follow accessibility standards (WCAG)

Development Workflow

Creating a New Theme

1. Scaffold the theme: cp -r assets/theme-template/ /path/to/drupal/themes/custom/mytheme/ cd /path/to/drupal/themes/custom/mytheme/ # Rename files mv THEMENAME.info.yml mytheme.info.yml mv THEMENAME.libraries.yml mytheme.libraries.yml mv THEMENAME.theme mytheme.theme
2. Update theme configuration:

- Edit mytheme.info.yml - Set name, regions, base theme - Edit mytheme.libraries.yml - Define CSS/JS libraries - Replace THEMENAME with your machine name - Replace THEMELABEL with your label

1. Enable the theme: ddev drush cr # Enable via UI at /admin/appearance or: ddev drush config:set system.theme default mytheme -y
2. Enable Twig debugging:

- Copy sites/default/default.services.yml to sites/default/services.yml - Set twig.config.debug: true - Set twig.config.auto_reload: true - Set twig.config.cache: false - Run ddev drush cr

1. Develop and iterate:

- Modify templates in templates/ - Update CSS in css/ - Clear cache frequently: ddev drush cr - Check browser console for errors

Standard Development Workflow

1. Enable development settings (Twig debug, disable CSS/JS aggregation)
2. Create/modify templates based on suggestions from Twig debug
3. Implement preprocessing in .theme file for complex data manipulation
4. Add CSS/JS via libraries system
5. Test across browsers and devices
6. Clear cache after changes: ddev drush cr

Finding Template Names

With Twig debugging enabled, inspect HTML source:

<!-- FILE NAME SUGGESTIONS:
   * page--node--123.html.twig
   * page--node--article.html.twig
   * page--node.html.twig
   x page.html.twig
-->

The x indicates the active template. Others are suggestions you can create.

Common Patterns

Adding Custom Variables in Preprocess

function mytheme_preprocess_page(&$variables) {
  // Add site slogan
  $variables['site_slogan'] = \Drupal::config('system.site')->get('slogan');

  // Add current user
  $variables['is_logged_in'] = \Drupal::currentUser()->isAuthenticated();

  // Add custom class
  $variables['attributes']['class'][] = 'custom-page-class';
}

Template Inheritance

{# templates/page--article.html.twig #}
{% extends "page.html.twig" %}

{% block content %}
  <div class="article-wrapper">
    {{ parent() }}
  </div>
{% endblock %}

Conditional Library Loading

function mytheme_preprocess_node(&$variables) {
  if ($variables['node']->bundle() == 'article') {
    $variables['#attached']['library'][] = 'mytheme/article-styles';
  }
}

Accessing Field Values in Twig

{# Get field value #}
{{ node.field_custom.value }}

{# Check if field has value #}
{% if node.field_image|render %}
  {{ content.field_image }}
{% endif %}

{# Loop through multi-value field #}
{% for item in node.field_tags %}
  {{ item.entity.label }}
{% endfor %}

Best Practices

Theme Development

1. Base theme: Choose appropriate base (Olivero, Claro, or none)
2. Structure: Organize CSS logically (base, layout, components, theme)
3. Naming: Use BEM or similar CSS methodology
4. Comments: Document complex Twig logic and preprocessing
5. Performance: Optimize images, minimize CSS/JS, lazy load when possible

Twig Templates

1. Logic: Keep complex logic in preprocess, not templates
2. Filters: Use appropriate filters (|t, |clean_class, |safe_join)
3. Whitespace: Use {% spaceless %} to control output
4. Debugging: Enable Twig debugging during development only
5. Suggestions: Use specific templates only when needed

Preprocessing

1. Services: Use dependency injection in theme service subscribers
2. Caching: Add proper cache contexts and tags
3. Performance: Avoid heavy operations in frequently-called preprocessors
4. Organization: Group related preprocessing logically

CSS & JavaScript

1. Libraries: Group related assets into logical libraries
2. Dependencies: Declare all library dependencies
3. Loading: Load globally only when necessary
4. Aggregation: Enable in production for performance

Accessibility

1. Semantic HTML: Use proper elements (header, nav, main, etc.)
2. ARIA: Add labels and roles when needed
3. Keyboard: Ensure keyboard navigation works
4. Contrast: Meet WCAG color contrast requirements
5. Alt text: Provide for all images

Responsive Design

1. Mobile-first: Design for small screens, enhance for large
2. Breakpoints: Define logical breakpoints
3. Images: Use responsive image styles
4. Testing: Test across devices and screen sizes
5. Performance: Optimize for mobile networks

Troubleshooting

Template Changes Not Showing

• Clear cache: ddev drush cr
• Verify file location and naming
• Check Twig debug for active template
• Ensure library is properly defined

CSS/JS Not Loading

• Check library definition in .libraries.yml
• Verify file paths are correct
• Ensure library is attached (globally or conditionally)
• Clear cache and check browser console

Variables Not Available in Template

• Check preprocess function naming
• Verify variables are being set correctly
• Use Twig debugging: {{dump()}}
• Clear cache after preprocessing changes

Twig Debugging Not Working

• Verify sites/default/services.yml exists
• Check twig.config.debug: true is set
• Clear cache: ddev drush cr
• Check file permissions

Resources

Reference Documentation

• references/theming.md - Comprehensive theming guide

- Twig syntax and filters - Template suggestions - Preprocessing patterns - Library management - Responsive design - Best practices

Asset Templates

• assets/theme-template/ - Complete theme scaffold

- .info.yml with regions and configuration - .libraries.yml with CSS/JS examples - .theme with preprocess examples - Page template - CSS and JS starter files

Searching References

# Find specific Twig filter
grep -r "clean_class" references/

# Find preprocessing examples
grep -r "preprocess_node" references/

# Find library patterns
grep -r "libraries.yml" references/

Version Compatibility

Drupal 8 vs 9 vs 10 vs 11

• Twig syntax: Consistent across all versions
• Base themes: Some legacy themes removed in 10+
• Libraries: Same structure across versions
• jQuery: Drupal 9+ doesn't load jQuery by default
• Claro: Admin theme standard in 9+
• Olivero: Frontend theme standard in 10+

Migration Notes

• When upgrading, check for deprecated base themes
• Review jQuery dependencies
• Test with current Twig version
• Check for removed core templates

See Also

• drupal-backend - Module development, hooks, APIs
• drupal-tooling - DDEV and Drush development tools
• Drupal Theming Guide - Official documentation
• Twig Documentation - Twig syntax reference