changing-form-structure.md

Changing Form Structure

When you change the structure of a widget's form, such as moving fields into a section, saved widgets still hold data in the old structure. Override the modify_instance() method of SiteOrigin_Widget to convert an instance from the old structure to the new one.

Updating the Form

This example groups a few of a widget's fields into a section. First, update the array that get_widget_form() returns.

The old form:

$form_options = array(
	'employee_name'    => array(
		'type'  => 'text',
		'label' => __( 'Name', 'example-text-domain' ),
	),
	'employee_surname' => array(
		'type'  => 'text',
		'label' => __( 'Surname', 'example-text-domain' ),
	),
);

The new form:

$form_options = array(
	'employee' => array(
		'type'   => 'section',
		'label'  => __( 'Employee', 'example-text-domain' ),
		'fields' => array(
			'name'    => array(
				'type'  => 'text',
				'label' => __( 'Name', 'example-text-domain' ),
			),
			'surname' => array(
				'type'  => 'text',
				'label' => __( 'Surname', 'example-text-domain' ),
			),
		),
	),
);

Overriding modify_instance()

Override modify_instance() to move the old values into the new structure. The Widgets Bundle calls modify_instance() when it renders the widget, renders the form and saves the form, so the method must leave an instance that already has the new structure unchanged.

function modify_instance( $instance ) {
	// Only apply the transformation if the instance does not already have the new structure.
	if ( empty( $instance['employee'] ) ) {
		$instance['employee'] = array();
		if ( isset( $instance['employee_name'] ) ) {
			$instance['employee']['name'] = $instance['employee_name'];
		}
		if ( isset( $instance['employee_surname'] ) ) {
			$instance['employee']['surname'] = $instance['employee_surname'];
		}

		unset( $instance['employee_name'] );
		unset( $instance['employee_surname'] );
	}
	return $instance;
}