UI Patterns Settings
Extends UI Patterns to make patterns configurable through settings without requiring hook_preprocess implementations.
ui_patterns_settings
Install
composer require 'drupal/ui_patterns_settings:8.x-2.4'
composer require 'drupal/ui_patterns_settings:8.x-2.2'
Overview
UI Patterns Settings is a powerful extension for the UI Patterns module that enables pattern configuration through declarative settings. It allows site builders and developers to define configurable settings for UI Patterns directly in their pattern definitions, making patterns more flexible and reusable without custom preprocess code.
The module provides a comprehensive plugin-based architecture with over 20 built-in setting types including text fields, dropdowns, checkboxes, media library integration, color widgets, and more. It seamlessly integrates with Layout Builder, Display Suite, and Field Groups, and supports dynamic values through the Token module.
Key capabilities include variant-specific settings overrides, conditional visibility based on variants or other settings, exposed fields that map pattern settings to entity fields, and data providers for complex setting types like menus and breadcrumbs.
Features
- Plugin-based setting type system with over 20 built-in types (textfield, select, boolean, checkboxes, radios, number, url, token, attributes, media_library, colorwidget, coloris, machine_name, group, links, role_access, role_checkboxes, language_access, language_checkboxes, publish, value, enumeration)
- Token integration allowing dynamic value replacement in settings using Drupal's token system
- Layout Builder integration for configuring pattern settings directly in the layout builder interface
- Display Suite integration for pattern settings in field display configuration
- Variant-specific settings that can override default values or completely change setting definitions per variant
- Conditional visibility using states system to show/hide settings based on variant selection or other setting values
- Exposed fields feature allowing pattern settings to be mapped to entity fields for programmatic access
- Data providers plugin system for complex setting types (menu, breadcrumb) that supply dynamic data
- Media Library setting type with support for image styles, responsive image styles, view modes, and inline editing
- Group setting type for organizing settings into fieldsets, details, and horizontal tabs
- Role-based and language-based access settings for conditional rendering based on user roles or current language
- Publish/unpublish setting type for controlling pattern visibility
- Twig extension providing pattern_configuration() function for accessing settings in templates
- Hooks for altering settings and variants before rendering (hook_ui_pattern_settings_settings_alter, hook_ui_pattern_settings_variant_alter)
- Field Groups support for organizing pattern settings
- Pattern preview support with configurable preview values for settings
Use Cases
Configurable Card Component
Create a card pattern with settings for modifier classes, URL links, and HTML attributes. Site builders can configure card variants, add custom CSS classes, and set dynamic URLs using tokens like [node:url] without writing any preprocess code.
Dynamic Navigation Patterns
Use the links setting type with the menu data provider to create navigation components. Configure which menu to display, the initial visibility level, and depth directly in the Layout Builder or Display Suite interface.
Role-Based Content Display
Use role_access settings to show or hide pattern elements based on user roles. For example, show a promotional banner only to anonymous users or display admin-only content to administrators.
Multilingual Content Control
Use language_access settings to control pattern visibility based on the current site language. Show language-specific promotional content or region-specific features.
Variant-Based Settings
Define pattern variants where each variant automatically applies specific setting values. For example, a 'product' variant could automatically set modifier classes and shadow attributes without manual configuration.
Token-Based Dynamic Values
Use allow_token: true in settings to enable token replacement. Site builders can enter tokens like [node:title] or [user:display-name] that are replaced with actual values at render time.
Media Integration in Patterns
Use the media_library setting type to allow site builders to select images or media directly in pattern configuration. Configure image styles or responsive image styles to be applied automatically.
Exposed Fields for Programmatic Access
Map pattern settings to entity fields using the expose feature. This allows pattern settings to be populated from entity field values, enabling content editors to control pattern behavior through familiar field interfaces.
Tips
- Use 'preview' property in settings to define preview values for the Pattern Library display.
- Use 'group' property to organize related settings into fieldsets or tabs for better UI organization.
- Use 'states' property for conditional visibility - show settings only when specific variants are selected or other settings have certain values.
- Use 'required: true' to make settings mandatory with form validation.
- Use 'forced_value' to set a value that cannot be changed by the UI - useful for programmatic overrides.
- Use 'form_visible: false' to hide settings from the UI while still processing them.
- Combine variant settings with setting definitions to override not just values but entire setting configurations per variant.
- Use the pattern_configuration() Twig function to access pattern configuration values in your templates.
- Use data providers for complex setting types like links to dynamically populate settings with menu or breadcrumb data.
Technical Details
Hooks 2
hook_ui_pattern_settings_settings_alter
Alter UI Patterns Settings settings before they are rendered. Allows overriding configured pattern settings for specific patterns or implementing custom setting logic.
hook_ui_pattern_settings_variant_alter
Alter UI Patterns variant before it is passed to settings processing. Allows overriding the configured pattern variant programmatically.
Troubleshooting 5
Ensure your pattern definition includes a 'settings' section with properly configured setting types. Verify that the UI Patterns module is enabled and patterns are correctly registered.
Install the required modules: media_library_form_element and media_library_edit. The media_library setting type requires these modules to function.
Ensure the setting has 'allow_token: true' in its definition. Also verify that the Token module is installed and the token syntax is correct.
Install the Color Widget module which provides the colorwidget form element type.
Verify that your pattern template uses the setting variables (e.g., {{ modifier }}, {{ attributes }}). Settings are passed as template variables matching their names.