Layout Builder Base
Provides a comprehensive plugin base for creating flexible, highly configurable layouts for Drupal's Layout Builder with extensive styling options.
layout_builder_base
Overview
Layout Builder Base is a developer-focused module that provides an extensible foundation for creating complex, configurable layouts for Drupal's Layout Builder. The module offers a comprehensive set of abstract base classes that developers can extend to create custom layouts with built-in support for styling options such as background colors, margins, padding, container widths, and grid properties.
The module includes a powerful configuration system that allows site administrators to set default values for all layout properties and override the available options through an administrative interface. This makes it possible to customize layout choices without writing any code. Developers can also use a rich set of alter hooks to programmatically modify available options.
The companion submodule, Layout Builder Base Library, provides ready-to-use layouts (one to four columns plus a customizable columns layout) that come with pre-configured CSS styling, making it immediately usable for site builders who want feature-rich layouts out of the box.
Features
- Abstract base classes (BaseLayoutBase, DefaultLayoutBase) for creating custom layout plugins with extensive configuration options
- Pre-built layouts through the Layout Builder Base Library submodule: one-column, two-column, three-column, four-column, and customizable columns
- Comprehensive background styling options including color, image upload, attachment (fixed/scroll), position, size, and overlay effects
- Flexible margin controls with individual (top, bottom, left, right) and equal (top/bottom, left/right) options in multiple sizes
- Flexible padding controls with individual (top, bottom, left, right) and equal (top/bottom, left/right) options in multiple sizes
- Container width options (default, small, large, none) for controlling maximum layout width
- Content container options for containing content within a full-width background
- Height options including 100vh and 80vh for hero sections
- Text color and alignment options
- Grid properties for multi-column layouts including column gap, row gap, breakpoint, and align items
- Column width options for two-column layouts (50-50, 33-67, 67-33, 25-75, 75-25)
- Column width options for three-column layouts (33-33-33, 25-50-25, 25-25-50, 50-25-25)
- Customizable columns layout with autofit, autofill, and fixed 2/3/4 column options
- Custom HTML ID and CSS classes support for each layout section
- Background image upload with image style selection
- Administrative interface to set global default values for all layout properties
- Override options system to customize available choices without code changes
- Over 25 alter hooks for programmatic customization of layout options
- Responsive breakpoint support for mobile-friendly layouts
Use Cases
Creating hero sections with background images
Use the one-column layout with background image upload, set height to 100vh or 80vh, apply a dark overlay for text readability, and use white text color. The content container option allows you to center content while having a full-width background.
Building responsive multi-column content sections
Use two, three, or four column layouts with appropriate column widths. Set column breakpoints to determine when columns stack on smaller screens. Adjust column and row gaps for spacing between content.
Customizing available styling options for content editors
Use the admin interface at /admin/config/content/layout_builder_base to override options. For example, limit background colors to your brand colors only, or add custom margin sizes that match your design system.
Extending layouts with custom styling through hooks
Implement alter hooks like hook_layout_builder_base_background_alter() to add custom background colors, or hook_layout_builder_base_modifiers_alter() to add special layout variants. Create corresponding CSS classes in your theme.
Creating custom layout plugins with the base classes
Extend DefaultLayoutBase or BaseLayoutBase to create custom layouts. Override methods like getBackgroundOptions() to define your own options. Declare the layout in your module's layouts.yml file with the custom class.
Building landing pages with varied section designs
Combine different layouts on a single page: hero section with one-column and full-height background, feature grid with three columns, call-to-action with two columns (image and text), and footer with four columns for navigation.
Tips
- Use the Override options feature to customize available choices without writing code - this is the recommended approach for most site-specific customizations
- The <none> value in override options completely hides a field from the layout configuration form, useful for simplifying the editor experience
- When extending layout classes, always call parent methods to ensure alter hooks are invoked
- Background images support image styles - use this to optimize image sizes for better performance
- The content container option is useful for hero sections where you want a full-width background but centered content
- For custom layouts, extend BaseOneColumnLayout or BaseMultipleColumnsLayout from the Library submodule to inherit all predefined options
Technical Details
Admin Pages 1
/admin/config/content/layout_builder_base
Configure global default values for all layout properties and override the available options for each layout property. This page provides a centralized way to customize layout behavior across the entire site without writing code.
Permissions 1
Hooks 30
hook_layout_builder_base_background_alter
Alters the background color options available in layout configuration forms
hook_layout_builder_base_background_attachment_alter
Alters the background attachment options (fixed, scroll) available in layout configuration forms
hook_layout_builder_base_background_position_alter
Alters the background position options available in layout configuration forms
hook_layout_builder_base_background_size_alter
Alters the background size options (cover, contain) available in layout configuration forms
hook_layout_builder_base_background_overlay_alter
Alters the background overlay options available in layout configuration forms
hook_layout_builder_base_top_margin_alter
Alters the top margin options available in layout configuration forms
hook_layout_builder_base_bottom_margin_alter
Alters the bottom margin options available in layout configuration forms
hook_layout_builder_base_left_margin_alter
Alters the left margin options available in layout configuration forms
hook_layout_builder_base_right_margin_alter
Alters the right margin options available in layout configuration forms
hook_layout_builder_base_top_bottom_margins_alter
Alters the equal top and bottom margin options available in layout configuration forms
hook_layout_builder_base_left_right_margins_alter
Alters the equal left and right margin options available in layout configuration forms
hook_layout_builder_base_top_padding_alter
Alters the top padding options available in layout configuration forms
hook_layout_builder_base_bottom_padding_alter
Alters the bottom padding options available in layout configuration forms
hook_layout_builder_base_left_padding_alter
Alters the left padding options available in layout configuration forms
hook_layout_builder_base_right_padding_alter
Alters the right padding options available in layout configuration forms
hook_layout_builder_base_top_bottom_paddings_alter
Alters the equal top and bottom padding options available in layout configuration forms
hook_layout_builder_base_left_right_paddings_alter
Alters the equal left and right padding options available in layout configuration forms
hook_layout_builder_base_container_alter
Alters the container width options available in layout configuration forms
hook_layout_builder_base_content_container_alter
Alters the content container width options available in layout configuration forms
hook_layout_builder_base_height_alter
Alters the height options available in layout configuration forms
hook_layout_builder_base_color_alter
Alters the text color options available in layout configuration forms
hook_layout_builder_base_alignment_alter
Alters the text alignment options available in layout configuration forms
hook_layout_builder_base_column_gap_alter
Alters the column gap options for multi-column layouts
hook_layout_builder_base_row_gap_alter
Alters the row gap options for multi-column layouts
hook_layout_builder_base_column_breakpoint_alter
Alters the column breakpoint options for responsive layouts
hook_layout_builder_base_align_items_alter
Alters the align items options for multi-column layouts
hook_layout_builder_base_two_column_width_alter
Alters the column width distribution options for two-column layouts
hook_layout_builder_base_three_column_width_alter
Alters the column width distribution options for three-column layouts
hook_layout_builder_base_modifiers_alter
Alters the modifier options for custom styling logic
hook_layout_builder_base_customizable_columns_alter
Alters the customizable columns options
Troubleshooting 4
Check that your layout class extends the appropriate base class and that you haven't overridden option methods to return empty arrays. Verify that override options in the admin are not set to <none>.
Ensure the Layout Builder Base Library submodule is enabled if using its layouts. Check that CSS classes match between your layout options and your stylesheet. Clear Drupal cache after changes.
Verify the file upload completed successfully and the file exists in public://layout_background/. Check file permissions and ensure the image style selected (if any) has been generated.
Verify the column breakpoint class is correctly applied and check your CSS media queries. The Library submodule provides default breakpoints at 600px, 800px, 1200px, and 1400px.