Config Pages
Provides fieldable configuration entities that can be placed anywhere in the menu system, with context-awareness support for language, domain, or custom contexts.
config_pages
Install
composer require 'drupal/config_pages:8.x-2.19'
Overview
Config Pages provides a powerful way to create custom configuration pages using Drupal's Field API. Instead of writing custom forms with Form API, you can leverage the full power of entity fields including file uploads, entity references, multi-value drag and drop, and AJAX interactions.
The module creates fieldable content entities that store configuration values, while their structure is defined by config entity bundles. Each config page type can be mounted at any path in the menu system and can be context-aware, meaning different values can be stored based on the current language, domain, or any custom context plugin.
This module is ideal for creating singleton pages like homepages, site-wide settings, or replacing complex custom configuration forms. It supports token integration, Views integration, and provides Drush commands for managing values programmatically.
Features
- Fieldable entity using Drupal's Field API - add any field type including text, images, entity references, paragraphs, etc.
- Mount config pages at any menu path (e.g., /admin/config/mysettings) with proper breadcrumbs and menu hierarchy
- Context-awareness system allowing different configuration values based on current language or domain
- Extensible context plugin system for creating custom context types beyond language and domain
- Context fallback mechanism to use default values when no context-specific config exists
- Token integration for exposing config page field values as replacement tokens
- Block plugin for displaying config page content anywhere in the site
- Visibility condition plugin for controlling block/element visibility based on config page field values
- Views integration with argument default plugin for context-aware queries
- Twig function for directly rendering config page fields in templates
- Drush commands for getting and setting field values programmatically
- Drupal Console commands for managing config page values
- Import functionality to copy field values between different contexts
- Clear values functionality to reset all fields to their defaults
- Granular permissions per config page type for view and edit access
- Contextual links for quick editing from displayed blocks
- Full Field UI integration for managing fields, display modes, and form settings
Use Cases
Homepage Configuration
Create a config page type with fields for homepage hero banner, featured content references, promotional text, and call-to-action buttons. Content editors can update homepage elements without developer intervention, using familiar field widgets for images, WYSIWYG text, and entity references.
Global Site Settings
Replace custom settings forms with a config page containing fields for social media links, company contact information, footer copyright text, and analytics tracking codes. Mount it at /admin/config/site-settings for easy access and enable token exposure to use values throughout the site.
Multilingual Configuration
Enable language context to store different promotional content, legal text, or regional information per language. The system automatically loads the appropriate config page based on the current site language, with fallback to a default language when no translation exists.
Featured Content Curation
Replace Nodequeue with a config page using entity reference fields with Views-powered autocomplete. Editors can curate featured articles, products, or media items using drag-and-drop ordering, with all the power of Views filtering for the selection interface.
Conditional Block Display
Use the ConfigPage field value visibility condition to show or hide blocks based on config page settings. For example, display a promotional banner only when a 'show_promo' boolean field is enabled, allowing content managers to toggle site-wide features.
Template Integration
Use the config_pages_field() Twig function to render config page fields directly in theme templates. For example, {{ config_pages_field('footer_settings', 'field_copyright_text') }} renders the copyright text in footer.html.twig without needing a block.
Tips
- Use the config_pages_config() helper function in custom code to easily load a config page by type: $config = config_pages_config('my_settings');
- For programmatic value retrieval, use the config_pages.loader service: \Drupal::service('config_pages.loader')->getValue('my_settings', 'field_name', 0, 'value');
- Custom context plugins can be created by extending ConfigPagesContextBase and placing them in Plugin/ConfigPagesContext directory
- Config page types and their field configurations are exportable via Drupal's configuration management, but the actual content (field values) is stored as content entities
- When using entity reference fields on config pages, enable the autocomplete widget with Views selection for powerful filtering capabilities
- The Twig function config_pages_field() automatically handles caching and returns an empty render array with appropriate cache tags when no config page exists
Technical Details
Admin Pages 4
/admin/structure/config_pages
Overview page listing all config page types with their context settings and token exposure status. From here, you can quickly access any config page for editing.
/admin/structure/config_pages/types
Administrative page for managing config page type definitions. Lists all available types with their context settings and provides access to edit, delete, and manage fields.
/admin/structure/config_pages/types/add
Form for creating a new config page type with menu path, context settings, and token configuration.
/admin/structure/config_pages/{config_pages_type}/edit
The actual config page form where users enter configuration values. Shows all configured fields and allows saving, clearing values, and importing from other contexts.
Permissions 9
Hooks 2
hook_config_pages_contexts_info_alter
Allows modules to alter the list of available context plugins
hook_config_pages_functions_alter
Allows modules and themes to add custom Twig functions to the config_pages extension
Drush Commands 2
drush config:pages-set-field-value
Set a value for a field of a config page
drush config:pages-get-field-value
Get the value of a field from a config page
Troubleshooting 4
The specified menu path conflicts with an existing route. Choose a different path or remove/modify the conflicting route.
Verify that context plugins are properly enabled on the config page type. Check if a config page entity exists for the current context. Review fallback settings if values should fall back to a default.
Ensure the 'Expose this ConfigPage values as tokens' checkbox is enabled on the config page type form. Clear caches after enabling.
Verify a config page entity exists (has been saved at least once). Check that the view mode has the fields configured in 'Manage display'. Ensure the user has 'view' permission for the config page type.
Security Notes 4
- Permissions are granular - assign 'edit [type] config page entity' for specific types rather than 'edit config_pages entity' which grants access to all types
- The 'administer config_pages types' permission grants significant power including the ability to create new config page types and modify field configurations - assign carefully
- Field values are not automatically sanitized for output - use appropriate field formatters and follow Drupal's render system best practices
- The 'access config_pages clear values option' permission allows users to reset all field values - this could result in data loss if misused