W3cubDocs

/WordPress

WP_Widget::form_callback( int|array $widget_args = 1 )

Generates the widget control form (Do NOT override).

Parameters

$widget_args

(int|array) (Optional) Internal order number of the widget instance, or array of multi-widget arguments.

  • 'number'
    (int) Number increment used for multiples of the same widget.

Default value: 1

Return

(string|null)

Source

File: wp-includes/class-wp-widget.php 

public function form_callback( $widget_args = 1 ) {
		if ( is_numeric( $widget_args ) ) {
			$widget_args = array( 'number' => $widget_args );
		}

		$widget_args   = wp_parse_args( $widget_args, array( 'number' => -1 ) );
		$all_instances = $this->get_settings();

		if ( -1 == $widget_args['number'] ) {
			// We echo out a form where 'number' can be set later.
			$this->_set( '__i__' );
			$instance = array();
		} else {
			$this->_set( $widget_args['number'] );
			$instance = $all_instances[ $widget_args['number'] ];
		}

		/**
		 * Filters the widget instance's settings before displaying the control form.
		 *
		 * Returning false effectively short-circuits display of the control form.
		 *
		 * @since 2.8.0
		 *
		 * @param array     $instance The current widget instance's settings.
		 * @param WP_Widget $this     The current widget instance.
		 */
		$instance = apply_filters( 'widget_form_callback', $instance, $this );

		$return = null;
		if ( false !== $instance ) {
			$return = $this->form( $instance );

			/**
			 * Fires at the end of the widget control form.
			 *
			 * Use this hook to add extra fields to the widget form. The hook
			 * is only fired if the value passed to the 'widget_form_callback'
			 * hook is not false.
			 *
			 * Note: If the widget has no form, the text echoed from the default
			 * form method can be hidden using CSS.
			 *
			 * @since 2.8.0
			 *
			 * @param WP_Widget $this     The widget instance (passed by reference).
			 * @param null      $return   Return null if new fields are added.
			 * @param array     $instance An array of the widget's settings.
			 */
			do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
		}
		return $return;
	}

Uses

Uses Description
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/plugin.php: do_action_ref_array()

Calls the callback functions that have been added to an action hook, specifying arguments in an array.
wp-includes/class-wp-widget.php: WP_Widget::get_settings()

Retrieves the settings for all instances of the widget class.
wp-includes/class-wp-widget.php: widget_form_callback

Filters the widget instance’s settings before displaying the control form.
wp-includes/class-wp-widget.php: in_widget_form

Fires at the end of the widget control form.
wp-includes/class-wp-widget.php: WP_Widget::_set()

Sets the internal order number for the widget instance.
wp-includes/class-wp-widget.php: WP_Widget::form()

Outputs the settings update form.

Changelog

Version Description
2.8.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/classes/wp_widget/form_callback