GB HTML Blocks for Advanced Custom Fields

Description

Adds a ready-made “HTML blocks” Flexible Content field group to pages, posts and products and renders it on the front end.

Full guide with screenshots and examples: https://gregbialowas.com/custom-html-blocks-acf-pro

Two layouts inside the field:
* Regular content (“Section Content”): a title, an intro text and one or two columns (image with a caption, title, text and a button in each).
* Hero (“Hero Image/Video”): an image or a looped, muted video, optionally stretched edge-to-edge.

Features:
* Field group loads automatically from the plugin (ACF Local JSON), no import needed
* Section with title, intro and one or two columns, plus an “Options” row (custom CSS classes, column order and widths, remove top margin)
* Per-column image (with caption), title, content, link and alignment
* Images with a caption inside the editor text (insert an image, fill in “Caption”, pick left/right/center): a dedicated html-blocks_page-figure block with the caption below the image; text wraps around left/right images
* “Show on page?” switch, “second column first” (mobile) and “Reverse columns” (desktop) options
* Optional 65/35 column widths
* “Remove top margin”: the section touches the previous one, so several sections look like one block
* Optional “Admin section label”: your own name of the section in the editor (internal only)
* Lightweight CSS (plain CSS, no dependencies), loaded only on pages that use sections
* Readable section titles in the editor: the Admin section label, otherwise the Title, otherwise the first words of the content
* Every block has a place for your own CSS classes (the “Custom class(es)” option), so you can restyle the content and the columns freely in your theme (see “Style it your way” below)
* Template can be overridden in the theme
* Filters and actions for developers

Requires Advanced Custom Fields PRO. The Flexible Content field is not part of the free ACF. If it is missing, the plugin shows a notice in the admin.

How to use

1. Install and activate Advanced Custom Fields PRO, then this plugin.
2. Edit a page (or a post). Under the title you will find the “Flex Blocks” field group. Click + New Page Section and choose a layout: Section Content (title, intro text and one or two columns) or Hero Image/Video (an image or a looped video, optionally edge-to-edge).
3. Fill in what you need. Empty fields are not printed. The Options row has custom CSS classes, “second column first” on mobile, 65/35 widths, reversed columns and “Remove top margin” (the section touches the previous one, so a few sections look like one block).
4. To put an image inside the text, use Add Media, fill in Caption and choose the alignment: the text wraps around it and the caption sits below.
5. Update the page. The sections are printed after the page content.

A longer guide with screenshots: https://gregbialowas.com/custom-html-blocks-acf-pro

Style it your way (custom CSS)

Every block has the ability to add its own CSS classes, so you can change the look of the content, the columns, the buttons and the images in your own theme, without touching the plugin. Type your own class in the Custom class(es) option of a section and style it in your theme’s CSS. You can also override the CSS variables (see “CSS variables”) or the classes of the plugin (see “CSS classes”). To use only your own styles, return false from the gb_html_blocks_enqueue_styles filter. You can also override the HTML itself with a template in your theme (see “Theme override”).

CSS classes

Every class generated by the plugin starts with html-blocks_page-section, so it can’t clash with theme classes: html-blocks_page-section, __inner, __content, __columns, __column, __column-content and __button. Section modifier: remove_top_margin. Image with a caption: html-blocks_page-figure (--left, --right, --center, __caption). Hero layout: html-blocks_page-section media (+ is-full-width). Modifiers of the columns wrapper: reversed, desktop-reversed, columns-65-35, hide-second-column. A column also gets its alignment class (to_left, centered or to_right).

Theme override

Copy templates/section.php to {your-theme}/gb-html-blocks/section.php. The theme file is used instead of the plugin one.

CSS variables

Set any of these (for example on :root) to match your theme:

• –gb-section-width (1200px)
• –gb-section-padding (20px)
• –gb-section-spacing (80px)
• –gb-section-gap (clamp(32px, 5vw, 80px))
• –gb-section-color (inherit)
• –gb-section-color-muted (inherit)
• –gb-section-accent (#222222)
• –gb-section-accent-contrast (#ffffff)
• –gb-section-radius (0)
• –gb-section-caption-bg (transparent)
• –gb-section-caption-border (rgba(0, 0, 0, 0.15))
• –gb-section-transition (0.2s ease)

Hooks

Filters:
* gb_html_blocks_field_name ( $name, $post_id ) – name of the Flexible Content field, default html_blocks
* gb_html_blocks_sections ( $sections, $post_id ) – all rows before rendering
* gb_html_blocks_section_visible ( $visible, $section, $index, $post_id ) – show or hide one section
* gb_html_blocks_template ( $file, $layout, $section ) – template path for a layout
* gb_html_blocks_custom_captions ( $enabled ) – use the plugin’s markup for image captions in the sections (default true)
* gb_html_blocks_auto_output ( $enabled, $post_id ) – add the sections after the content automatically (default true)
* gb_html_blocks_section_classes ( $classes, $data ) – classes of the section element
* gb_html_blocks_inner_classes ( $classes, $data ) – classes of the inner wrapper (default: html-blocks_page-section__inner internal --copy, or --contained when $data['_narrow'] is false)
* gb_html_blocks_image_size ( $size, $which, $data ) – image size, $which is first or second
* gb_html_blocks_section_html ( $html, $layout, $section, $index, $post_id ) – final HTML of one section
* gb_html_blocks_enqueue_styles ( $enqueue ) – return false to skip the plugin CSS
* gb_html_blocks_layout_title ( $title, $description, $field, $layout, $i ) – section title shown in the ACF editor

Actions:
* gb_html_blocks_before_section ( $layout, $section, $index, $post_id )
* gb_html_blocks_after_section ( $layout, $section, $index, $post_id )

Example (theme functions.php):

add_filter( 'gb_html_blocks_section_classes', function ( $classes, $data ) {
    $classes[] = 'my-extra-class';
    return $classes;
}, 10, 2 );