Site Settings and Labels
Provides a content entity system for managing site-wide settings and labels that clients can edit without affecting site configuration.
site_settings
Install
composer require 'drupal/site_settings:^2.0'
Overview
The Site Settings and Labels module provides a robust, content-based system for managing site-wide configurable settings without modifying site configuration. Unlike standard configuration entities, site settings are treated as content, allowing non-technical users to manage them while keeping the structure under version control.
The module introduces three entity types: Site Setting Entity (content entity for actual values), Site Setting Entity Type (config entity defining available setting types/bundles), and Site Setting Group Entity Type (config entity for organizing settings into groups). Administrators can define custom setting types with any Drupal field types, specify whether multiple entries are allowed, and organize settings into logical groups.
Site settings can be accessed in templates via Twig functions, in code via loader plugins, and anywhere tokens are available. The module provides two loader strategies: Full Site Settings Loader (recommended) which returns complete entity objects respecting display settings, and Flattened Site Settings Loader (legacy) which returns simplified arrays for quick access.
Key capabilities include multilingual content support with translations, full revision history, bulk replication of settings, two block plugins for displaying settings, Views integration with a default administrative view, and granular permissions including an optional submodule for per-type permissions.
Features
- Custom content entity system for site settings with fieldable bundles
- Flexible grouping system to organize settings logically (e.g., 'Footer Settings', 'Social Links')
- Multiple entries support - choose whether a setting type allows single or multiple values
- Six Twig functions for rendering settings in templates: site_setting(), site_settings_by_name(), all_site_settings(), site_settings_by_group(), site_setting_field(), site_setting_entity_by_name()
- Token integration for using settings anywhere tokens are accepted (emails, blocks, etc.)
- Two loader plugin strategies: Full (recommended, entity-based) and Flattened (legacy, array-based)
- Multilingual support with full translation capabilities
- Revision history with revert and delete capabilities
- Bulk replication feature to quickly create multiple similar settings
- Two block plugins: Simple Site Settings Block and Rendered Site Settings Block
- Views integration with default administrative view and custom area plugin
- Auto-loading of settings into all Twig templates (configurable)
- Per-type permissions via optional submodule
- Navigation module integration with custom icon
- Simple teaser mode for cleaner admin display
Use Cases
Social Media Links
Create a 'social_links' setting type in a 'Footer' group with multiple entries enabled. Add link field and icon field. Content editors can add/remove social networks without developer involvement. In your theme: {{ site_settings_by_name('social_links') }}
Footer Copyright Text
Create a 'footer_copyright' setting type with a text field. A single setting stores the copyright notice. Use {{ site_settings_by_name('footer_copyright') }} in your footer template.
Contact Information
Create setting types for phone, email, address in a 'Contact' group. Load all at once with {{ site_settings_by_group('contact') }} or individually by name.
Homepage Hero Settings
Create 'hero_settings' type with image, title, subtitle, and CTA link fields. Editors can update homepage hero without touching templates.
Email Template Variables
Create settings for email content (e.g., 'welcome_email_intro', 'signature') and use tokens in email templates like [site_settings:welcome_email_intro].
Feature Flags
Create boolean settings for feature toggles. Use site_setting_entity_by_name('feature_name') in code to get the entity and check field values programmatically.
Multilingual Labels
Create translatable setting types for UI labels that need different content per language but aren't suitable for interface translation.
Tips
- Use the Full Site Settings Loader (default) for better Drupal integration and proper cache handling
- Reuse existing fields across setting types to improve performance - the module warns about this during setup
- Enable 'simple_summary' for cleaner admin displays when you have many settings
- Use groups logically (Footer, Header, Contact, etc.) to organize settings and enable group-based loading in templates
- For complex settings with multiple fields, create custom view mode displays rather than using the simple block
- The site_setting_entity_by_name() Twig function returns the entity object for programmatic field access in templates
- Export your setting type configurations to version control - content remains in the database
- Consider per-type permissions submodule when different editors manage different setting types
- Clear caches after changing 'show_groups_in_menu' setting for menu changes to appear
Technical Details
Admin Pages 7
/admin/content/site-settings
Administrative listing of all site setting entities. Displays a table view with ID, Group, Type, Description, rendered Value (using Teaser view mode or simple summary), and Operations. Includes filters for Group and Language. Shows 'not yet created' settings in the header with quick-add buttons.
/admin/config/site-settings/config
Configure how the Site Settings module behaves including loader plugin selection, auto-loading behavior, and administrative display options.
/admin/structure/site-settings
Overview page for managing the Site Settings structure. Provides links to manage setting types and groups.
/admin/structure/site_setting_entity_type
Manage the available Site Setting types (bundles). Each type defines a kind of setting with its own fields, group assignment, and multiple entry option. Types are config entities that can be exported and version controlled.
/admin/structure/site_setting_entity_type/add
Create a new site setting type with label, group assignment, and multiple entry option.
/admin/structure/site_setting_entity_type/{setting}/replicate
Bulk replicate an existing site setting type to create multiple similar setting types with different machine names, labels, and group assignments. Requires Replicate and Field Tools modules.
/admin/structure/site_setting_group_entity_types
Manage Site Settings Group entities. Groups allow site builders to organize multiple site settings together (e.g., 'Footer settings', 'Social links') and enable theme builders to load all settings in a group at once.
Permissions 10
Hooks 2
hook_site_settings_no_setting_token_alter
Override the string that tokens return when there is no setting defined. Allows customization of the 'Setting not found' default message.
hook_site_settings_loader_plugin_info_alter
Alter the site settings loader plugin definitions. Allows modules to modify loader plugin information.