Child Widgets

Including a child widget (embedding one widget's form and output inside another widget) lets you reuse existing widget functionality without duplicating form fields or front end code. A common example is the Call-to-Action widget, which embeds the Button widget instead of recreating every button field.

Defining a widget Form Field

Add a field of type => widget to your widget's $form_options array and specify the fully-qualified PHP class name of the widget you want to embed.

$form_options = array(
    'button_field' => array(
        'type'  => 'widget',
        'label' => __( 'Button', 'siteorigin-docs' ),
        'class' => 'SiteOrigin_Widget_Button_Widget',
        'hide'  => true, // Start collapsed (optional).
    ),
);

Loading the Child Widget Class

Make sure the child widget class is available before the parent form is built. For Widgets Bundle widgets:

if ( ! class_exists( 'SiteOrigin_Widget_Button_Widget' ) ) {
    SiteOrigin_Widgets_Bundle::single()->include_widget( 'button' );
}

Rendering the Child Widget on the Front-End

The child widget's instance data is stored under the same key you used (button_field in this example). To output the widget inside your template:

Using $wp_widget_factory

if ( ! empty( $instance['button_field'] ) ) {
    global $wp_widget_factory;

    $button_widget = $wp_widget_factory->widgets['SiteOrigin_Widget_Button_Widget'];

    if ( $button_widget ) {
        // Render the child widget without extra wrapper markup
        $button_widget->widget( array(), $instance['button_field'] );
    }
}

Using the_widget()

the_widget( 'SiteOrigin_Widget_Button_Widget', $instance['button_field'] );

Note: the_widget() adds a default <div class="widget"> wrapper. Use $wp_widget_factory if you need full control over the markup.

Customizing the Child Widget Form

Sometimes the child widget has fields that are irrelevant in your parent widget. You can remove or tweak these fields in two ways.

Overriding modify_child_widget_form()

class My_Parent_Widget extends SiteOrigin_Widget {
    function modify_child_widget_form( $child_form, $child_widget ) {
        // Remove alignment controls from the Button widget.
        unset( $child_form['design']['fields']['align'] );
        unset( $child_form['design']['fields']['mobile_align'] );
        return $child_form;
    }
}

Using a form_filter Callback

'button_field' => array(
    'type'        => 'widget',
    'class'       => 'SiteOrigin_Widget_Button_Widget',
    'form_filter' => array( $this, 'filter_child_form' ),
),

function filter_child_form( $form, $child_widget ) {
    unset( $form['design']['fields']['align'] );
    return $form;
}

Examples in Core Widgets

Browse these files in the Widgets Bundle source to see working implementations.