Функция the_widget() в WordPress

Функция the_widget() позволяет выводить на страницу произвольные виджеты. Это делается через специальный шаблонный тег.

Хуки функции

• widget_display_callback — хук, который можно использовать для изменения отображения виджета.
• the_widget — хук, который активируется при вызове функции the_widget().

Возвращаемое значение

Функция the_widget() ничего не возвращает (null).

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

Синтаксис

the_widget( $widget, $instance, $args );

Параметры

1. $widget (string) (обязательный) — имя PHP-класса виджета. Например, WP_Widget_Categories.
2. $instance (array) — настройки конкретного экземпляра виджета. По умолчанию — пустой массив.
3. $args (array) — массив аргументов, которые настраивают отображение виджета.

По умолчанию параметры отображения заданы так:

• before_widget (string) — HTML-код, который будет добавлен перед выводом самого виджета. По умолчанию: <div class="widget %s">, где %s — имя класса виджета.
• after_widget (string) — HTML-код, который будет добавлен после вывода виджета. По умолчанию: </div>.
• before_title (string) — HTML-код, который будет добавлен перед заголовком виджета. По умолчанию: <h2 class="widgettitle">.
• after_title (string) — HTML-код, который будет добавлен после заголовка виджета. По умолчанию: </h2>.

Примеры

1. Показать виджет с настройками по умолчанию

2. Показать виджет с настройками

3. Показать виджет с собственными параметрами

 1,
    'count'    => 1,
);

$args = array(
    'before_widget' => '
',
    'after_widget' => '
',
    'before_title' => '
',
    'after_title' => '
'
);

the_widget( 'WP_Widget_Categories', $instance, $args );
?>

Примечания

• Глобальный объект: $wp_widget_factory — используется для работы с виджетами.

История изменений

• Функция the_widget() была представлена в версии 2.8.0 WordPress.

Как работает код функции the_widget()

Ниже представлен упрощенный код функции the_widget(), который объясняет, как она работает:

function the_widget( $widget, $instance = array(), $args = array() ) {
    global $wp_widget_factory;

    // Проверяем, зарегистрирован ли виджет
    if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) {
        _doing_it_wrong(
            __FUNCTION__,
            sprintf( __( 'Виджеты должны быть зарегистрированы с помощью %s, прежде чем их можно будет отобразить.' ), 'register_widget()' ),
            '4.9.0'
        );
        return;
    }

    $widget_obj = $wp_widget_factory->widgets[ $widget ];
    if ( ! ( $widget_obj instanceof WP_Widget ) ) {
        return;
    }

    // Задаем параметры отображения
    $default_args = array(
        'before_widget' => '
',
        'after_widget'  => '
',
        'before_title'  => '
',
        'after_title'   => '
',
    );
    $args = wp_parse_args( $args, $default_args );
    $args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] );

    // Применяем наст��ойки экземпляра
    $instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args );

    if ( false === $instance ) {
        return;
    }

    // Выводим виджет
    do_action( 'the_widget', $widget, $instance, $args );
    $widget_obj->_set( -1 );
    $widget_obj->widget( $args, $instance );
}

Эта функция проверяет, зарегистрирован ли виджет, подготавливает данные и затем выводит его на экран.