Page Widgets Filters

The Widgets page template is built from an ACF Flexible Content Field, which has Layouts added to it using the filter group_tk_page_widgets. Each layout consists of a set of ACF field definitions which are responsible for collecting the data for the widget.

Example

The following example will add a new page widget to the widgets page template, which requires the input of text, an image and a link (internal or external):

// function containing ACF field definitions to be used as a 
// layout for the widgets page template
function tk_add_button_page_widget( $widgets )
{
    $widgets[] = array (
        'key' => 'field_tk_page_widgets_button',
        'name' => 'button_widget', // name of the layout
        'label' => 'Button Widget',
        'display' => 'row',
        'sub_fields' => array (
            array (
                'key' => 'field_tk_page_widgets_button_text',
                'label' => 'Text',
                'name' => 'button_text',
                'type' => 'text',
                'maxlength' => 75
            ),
            array (
                'key' => 'field_tk_page_widgets_button_image',
                'label' => 'Image',
                'name' => 'tk_page_widgets_button_image',
                'type' => 'image',
                'return_format' => 'array',
                'preview_size' => 'thumbnail',
                'library' => 'all',
            ),
            array (
                'key' => 'field_tk_page_widgets_button_link_type',
                'label' => 'Link',
                'name' => 'tk_page_widgets_button_link_type',
                'type' => 'radio',
                'layout' => 'horizontal',
                'choices' => array (
                    'internal' => 'Internal link',
                    'external' => 'External link',
                ),
                'default_value' => 'internal',
                'return_format' => 'value',
            ),
            array (
                'key' => 'field_tk_page_widgets_button_link_internal',
                'label' => 'Internal link',
                'name' => 'internal_link',
                'type' => 'page_link',
                'conditional_logic' => array (
                    array (
                        array (
                            'field' => 'field_tk_page_widgets_button_link_type',
                            'operator' => '==',
                            'value' => 'internal',
                        ),
                    ),
                ),
                'allow_null' => 0,
                'allow_archives' => 1,
            ),
            array (
                'key' => 'field_tk_page_widgets_button_link_external',
                'label' => 'External link',
                'name' => 'external_link',
                'type' => 'url',
                'conditional_logic' => array (
                    array (
                        array (
                            'field' => 'field_tk_page_widgets_button_link_type',
                            'operator' => '==',
                            'value' => 'external',
                        ),
                    ),
                ),
            ),
        )
    );
    return $widgets;
}
add_filter( 'group_tk_page_widgets', 'tk_add_button_page_widget', 6 );

Once you have added this code to a child theme, you should see the option to add a button widget to a page using this template (the option is placed under the Banner widget using the priority of 6 - please see lib/acf/widgets-page-template.php for the priorities used by other widgets).

Now you need to create a template to display the content collected by this layout.

The widgets page template displays content using a set of sub-templates (one for each layout) in the templates/widgets directory of the theme or child theme. To display the button widget on a page using the widgets page template, you need to add a template file to the templates/widgets directory with the name tk-button_widget.php - this filename should correspond to the layout name button_widget prefixed with tk-.

<?php
// get the URL of the button
$button_link_type = get_sub_field('link_type');
if ( $button_link_type === 'internal' ) {
    $button_link_url = get_sub_field('internal_link');
} else {
    $button_link_url = get_sub_field('external_link');
}
$button_image = get_sub_field('button_image');
if ( $button_image ) {
    $button_background = " style=\"background-image: url('$button_image');\"";
}
?>
<!--Button Widget-->
<div class="button-widget">
    <div class="wrapper-md wrapper-pd-md">
        <a class="button"<?php echo $button_background; ?> href="<?php echo $button_link_url; ?>">
            <?php the_sub_field('button_text'); ?>
        </a>
    </div>
</div>
<!--/Button Widget-->

Note: this example is simplistic and contains no error checking - before you write your own page widgets, please review how the exsting widgets are added to the template and how they are rendered on the page.