register_sidebar

Регистрирует панель виджетов (место, куда размещаются виджеты в админ-панели, чтобы потом вывести их в лицевой части).

register_sidebar() регистрирует панель (место, контейнер) для виждетов и формат вывода для каждого виджета: html тег заголовка, html тег до и после виджета. Зарегистрировав панель, в админ-панели появится место, куда можно помещать виджеты. Разместив виджеты в панели, мы сможем вывести панель с виджетами в шаблоне с помощью функции dynamic_sidebar(), (см. пример 2).

Функцию нужно подключать к событию widgets_init.

Функция поддержки виджетов: add_theme_support(‘widgets’) должна быть активирована для темы, в functions.php. Если этого нет, то register_sidebar() активирует её автоматически.

Не используйте названия идентификаторов для параметра ID из этого списка. Там же, по ссылке, вы найдете небольшую функцию, которая собирает уже используемые ID в WordPress.

Используйте register_sidebars(), чтобы создать несколько панелей за раз. Это позволит создать уникальное имя для каждой панели, например: “Правый сайдбар”, “Левый сайдбар”. Несмотря на то, что эти названия видны только в админ-панели, важно дать пользователю представление о том где будет выводиться панель.

register_sidebars() также рекомендуется использовать, если нужно зарегистрировать несколько однотипных панелей для виждетов (названия отличаются числами), например: Панель 1, Панель 2, Панель 3.


Дефолтные значения параметров before/after рассчитаны на темы, которые создают боковые панели в виде LI списка с заголовками в H2 теге. Такая регистрация рекомендуется разработчиками WordPress для всех тем.

Если по каким-то причинам, маркировку нужно изменить, рекомендуется скопировать id (id="%1$s") и class (class="widget %2$s") атрибуты как указано по умолчанию и не указывать их жестко. Нужно это, чтобы они создавались динамически с помощью функции sprintf().


Нельзя оставлять параметры name и id пустыми!

Их можно либо не указывать вообще, либо обязательно указать при этом, нужно чтобы они были уникальными и не пустыми.

Если не определить id или name, то для них будут использованы значения по умолчанию с инкрементом:

register_sidebar( $args );

Шаблон использования

add_action( 'widgets_init', 'register_my_widgets' );
function register_my_widgets(){
	register_sidebar( array(
		'name'          => sprintf(__('Sidebar %d'), $i ),
		'id'            => "sidebar-$i",
		'description'   => '',
		'class'         => '',
		'before_widget' => '<li id="%1$s" class="widget %2$s">',
		'after_widget'  => "</li>n",
		'before_title'  => '<h2 class="widgettitle">',
		'after_title'   => "</h2>n",
	) );
}
$args(строка/массив)

Аргументы для регистрации панели виджетов. Можно указывать в виде строки или массива:
Если в виде строки, тогда аргументы нужно разделять знаком &:

'name=Sidebar&id=my_prefix_sidebar'

Те же аргументы в массиве:

array(
	'name' => 'Sidebar',
	'id'   => 'my_prefix_sidebar',
)

По умолчанию: параметры по умолчанию.

Аргументы параметра $args

name(строка)
Название панели виджетов. Название будет видно в админ-панели WordPress. По умолчанию “Боковая колонка 1” (локализация от Sidebar $i, где $i порядковый номер сайдбара). Значение не должно быть пустым!
По умолчанию: sprintf(__(‘Sidebar %d’), $i )
id(строка)
Идентификатор виджета. Строка, в которой не должно быть заглавных букв и пробелов. Значение не должно быть пустым, если оставить этот параметр пустым, то в режиме разработки (при дебаге) получите заметку типа E_USER_NOTICE.
По умолчанию: “sidebar-$i”
description(строка)
Текст описывающий где будет выводиться панель виджетов. Показывается в панели управления виджетами.
По умолчанию: ”
class(строка)
CSS класс, который будет добавлен главному HTML тегу панели виджетов.
По умолчанию: ”
before_widget(строка)
HTML код, который будет расположен перед каждым виджетом в панели. Например: <li class=”my-widget”>. Конструкции %1$s и %2$s будут заменены на id и class используемого в сайдбаре виджета.
По умолчанию: ‘<li id=”%1$s” class=”widget %2$s”>
after_widget(строка)
HTML код, который будет расположен после каждого виджета в панели. Например: </li>.
По умолчанию: “</li>n
before_title(строка)
HTML код перед заголовком виджета.
По умолчанию: ‘<h2 class=”widgettitle”>
after_title(строка)
HTML код после заголовка виджета.
По умолчанию: “</h2>n
Основное назначение этих аргументов, указать подходящие для темы теги оборачивающие каждый виджет и его заголовок. В WordPress принято оборачивать виджет в li тег, а заголовок виджета в тег h2.

Примеры

#1 Регистрация виджетов для боковой панели сайта

Код ниже, зарегистрирует панель под названием “Правая боковая панель сайта”. Название панели будет обвёрнуто в теги <div class=”title”> и </div>:

function register_my_widgets(){
	register_sidebar( array(
		'name' => "Правая боковая панель сайта",
		'id' => 'right-sidebar',
		'description' => 'Эти виджеты будут показаны с правой колонке сайта',
		'before_title' => '<h1>',
		'after_title' => '</h1>'
	) );
}
add_action( 'widgets_init', 'register_my_widgets' );

После того, как мы разместим этот код в файл темы functions.php, в админ-панели на странице виджетов, появится панель, куда мы сможем добавить виджеты. В шаблоне эта панель выводится с помощью функции dynamic_sidebar():

<?php
	if ( function_exists('dynamic_sidebar') )
		dynamic_sidebar('right-sidebar');
?>

#2 Зарегистрируем панель виджетов для главной страницы сайта

Добавим код в functions.php:

function register_my_widgets(){
	register_sidebar( array(
		'name' => 'Боковая панель на главной странице',
		'id' => 'homepage-sidebar',
		'description' => 'Выводиться как боковая панель только на главной странице сайта.',
		'before_widget' => '<li class="homepage-widget-block">',
		'after_widget' => '</li>',
		'before_title' => '<h2 class="widgettitle">',
		'after_title' => '</h2>',
	) );
}
add_action( 'widgets_init', 'register_my_widgets' );

В файл home.php вставим вывод панели:

<div class="custom">
	<?php
	if ( function_exists('dynamic_sidebar') )
		dynamic_sidebar('homepage-sidebar');
	?>
</div>

Код из


wp-includes/widgets.php

WP 4.7.2

<?php
function register_sidebar($args = array()) {
	global $wp_registered_sidebars;

	$i = count($wp_registered_sidebars) + 1;

	$id_is_empty = empty( $args['id'] );

	$defaults = array(
		'name' => sprintf(__('Sidebar %d'), $i ),
		'id' => "sidebar-$i",
		'description' => '',
		'class' => '',
		'before_widget' => '<li id="%1$s" class="widget %2$s">',
		'after_widget' => "</li>n",
		'before_title' => '<h2 class="widgettitle">',
		'after_title' => "</h2>n",
	);

	$sidebar = wp_parse_args( $args, $defaults );

	if ( $id_is_empty ) {
		/* translators: 1: the id argument, 2: sidebar name, 3: recommended id value */
		_doing_it_wrong( __FUNCTION__, sprintf( __( 'No %1$s was set in the arguments array for the "%2$s" sidebar. Defaulting to "%3$s". Manually set the %1$s to "%3$s" to silence this notice and keep existing sidebar content.' ), '<code>id</code>', $sidebar['name'], $sidebar['id'] ), '4.2.0' );
	}

	$wp_registered_sidebars[$sidebar['id']] = $sidebar;

	add_theme_support('widgets');

	/**
	 * Fires once a sidebar has been registered.
	 *
	 * @since 3.0.0
	 *
	 * @param array $sidebar Parsed arguments for the registered sidebar.
	 */
	do_action( 'register_sidebar', $sidebar );

	return $sidebar['id'];
}

Комментарии:


Оставить комментарий

Your email address will not be published. Required fields are marked *