Adding a custom page element

Adding a custom page element to you child theme involves the following:

1. Add an acf-json folder
2. Create an Advanced Custom Fields Field Group
3. Assign the field group to the Page Builder Layout location rule
4. Add a properly-named PHP file to your child theme with your page element template code

1. Add an acf-json folder

Your child theme must have a top-level folder named acf-json. This is where Advanced Custom Fields will save the setting for your field group.

acf-json/
functions.php
style.css
other_child_theme_files...

2. Create an Advanced Custom Fields Field Group

In the Custom Fields area of wp-admin, create a new Field Group for your custom page element.

The name of the Field Group will be the name of your page element as it appear in the Page Builder UI.

Add all the fields your page element will need.

3. Assign the field group to the Page Builder Layout location rule

In the Location section of the Field Group, add a new rule to indicate whether your page element should appear in One-, Two-, or Three-Column layout rows in the theme’s Page Builder. For example, to have your custom element available in only One- or Two-Column layouts, you would add two rules as shown below. Note that the two rules use an OR logic, not AND.

After saving the ACF Field Group, its corresponding JSON file should get saved to your child theme’s acf-json folder.

At this point your custom element should appear in the Page Builder page elements menu corresponding to the layouts you designated it for. For example, a field group named My Custom Page Element will appear as follows:

If you select your custom element, your ACF fields should appear and get saved with the page.

At this point, after saving the page, if you view it, you will see a message reading Page element not found where you added your custom page element to the layout.

4. Add a PHP template for rendering your custom page element

UW Theme’s page builder will look for a PHP template file in your child theme’s content-parts/page-elements/ directory path. Specifically, it looks for a PHP file named corresponding to the ACF Field Group assigned key value. If you open the JSON file for your page element as saved in your child theme’s acf-json directory, the key value will be the first key-value pair. In the example below, the value is group_62acac06f3d0b:

{ 
    "key": "group_62acac06f3d0b", 
    "title": "My Custom Page Element", 
    ... 
}

That key value will be the name of the PHP file you save in your child theme’s content-parts/page-elements/ directory, with a .php extension appended. For the example above, you would save the following file:

content-parts/page-elements/group_62acac06f3d0b.php

(See below for how to replace the machine-generated key value with a human-friendly file name.)

In this file is where you add your custom page element’s PHP template code to output the content of your page element. For example, if my custom page element had a simple ACF text field named mammal, I could output it as follows:

<?php 
    echo get_sub_field('mammal'); 
?>

Human-friendly PHP filenames

If your child theme has more than one custom page element, it can get difficult finding the right PHP file in content-parts/page-elements/ since the filenames are not based on the name of the page element.

UW Theme provides a WordPress filter you can add to you child theme to map a human-friendly filename to the machine-generated ACF field group key:

// map custom field group row layout value to human-friendly values 
add_filter( 'uw_theme_row_layout', function($row_layout) { 
    $custom_element_filename_map = [ 
        "group_62acac06f3d0b" => "my_custom_element", 
        "group_620bcfa8c6ca0" => "conference_schedule" 
    ]; 

    if (array_key_exists($row_layout, $custom_element_filename_map)) 
        return $custom_element_filename_map[$row_layout]; 

    return $row_layout; 
});

Then you would have page element template files in /content-parts/page-elements/ named my_custom_element.php and conference_schedule.php