in_widget_form │ хук-событие │ WP 2.8.0

Срабатывает в конце формы настроек виджета. Позволяет вывести дополнительные поля для классических виджетов.

Событие также срабатывает при формировании настроек блока «Устаревший виджет» через REST API.

Событие не сработает, если фильтр widget_form_callback вернул false.

Использование

add_action( 'in_widget_form', 'wp_kama_in_widget_form_action' );

/**
 * Function for `in_widget_form` action-hook.
 * 
 * @param WP_Widget $widget The widget instance (passed by reference).
 *
 * @return void
 */
function wp_kama_in_widget_form_action( $widget ){
	// action...
}

$widget(WP_Widget)

Объект текущего виджета. Передаётся по ссылке.

$return(null|string)

Значение, которое вернул метод формы виджета. Стандартный метод возвращает noform.
Передаётся по ссылке. Установите null, если добавляете поля к виджету без собственной формы.

$instance(массив)

Текущие настройки экземпляра виджета.

Примеры

#1 Добавление поля ко всем классическим виджетам

Добавим текстовое поле Заметка и сохраним его значение вместе с настройками виджета.

<?php
add_action( 'in_widget_form', 'wp_kama_add_widget_note_field', 10, 3 );

function wp_kama_add_widget_note_field( $widget, &$return, $instance ) {
	$value  = $instance['wp_kama_note'] ?? '';
	$id     = $widget->get_field_id( 'wp_kama_note' );
	$name   = $widget->get_field_name( 'wp_kama_note' );
	$return = null;
	?>
	<p>
		<label for="<?php echo esc_attr( $id ); ?>">
			<?php esc_html_e( 'Заметка', 'my-plugin' ); ?>
		</label>
		<input
			type="text"
			class="widefat"
			id="<?php echo esc_attr( $id ); ?>"
			name="<?php echo esc_attr( $name ); ?>"
			value="<?php echo esc_attr( $value ); ?>"
		>
	</p>
	<?php
}

add_filter( 'widget_update_callback', 'wp_kama_save_widget_note', 10, 4 );

function wp_kama_save_widget_note( $instance, $new_instance, $old_instance, $widget ) {
	if ( isset( $new_instance['wp_kama_note'] ) ) {
		$instance['wp_kama_note'] = sanitize_text_field( $new_instance['wp_kama_note'] );
	} else {
		unset( $instance['wp_kama_note'] );
	}

	return $instance;
}