WebDev - блог

В двух своих предыдущих статьях я уже описал что такое виджеты и как добавить поддержку виджетов в вашу тему. Думаю, что пора уже заняться созданием своих виджетов для WordPress.

Но для начала рассмотрим подробнее несколько функций, которые предназаначены для работы с динамическими сайдбарами и видетами. Функции для регистрации сайдбаров и их показа уже использовались в предыдущей статье. В дальнейшем мы будет подразумевать, что тема уже имеет динамические сайдбары и уделим внимание только созданию и настройке виджетов.

В этой статье я опишу функции WordPress, предназначенные для использования с виджетами. Функци этих совсем не много, так что эта часть будет кратенькой.

В следующей статье(Создаем виджеты для Wordpress) рассмотрим два способа создания виджетов и работы с ними: с помощью плагинов и с помощью добавление виджета в текущую тему WordPress.

Итак, рассмотрим функции API WordPress, используемые при создании и размещении виджетов на сайте.

Виджет-ориентированные функции(Widgets API)

Функции, используемые в темах

void register_sidebars ( [ int count [, mixed args ]] )

Функция предназначенадля регистрации одной или более панелей(колонок) темы, имеющих возможность показывать виджеты. Если панель только одна, то функция вызывается без параметра count. Паметры args будут переданы функции register_sidebar и описаны ниже. Кроме параметра name, с помощью которого вы можете задать шаблон имени для колонок. Шаблон имени проходит через функцию sprintf, то есть можно использовать шаблон форматирования строки, понимаемый этой функцией. Это позволяет нам, например, присваивать уникальный номер каждой колонке:
register_sidebars(2, array('name'=>'Колонка %d'));
В результате мы зарегистрируем две колонки, которые на странице управления виджетами будут обозначены как "Колонка 1" и "Колонка 2".

void register_sidebar ( [ mixed args ] )

Необязательный параметр args, передаваемый функции register_sidebar в виде ассоциативного массива, будет передан первым параметром в каждую функцию, зарегистрированную в качестве виджета(callback-функцию), для виджетов размещенных в колонке.(Если в парметр args вместо массива будет передана строка, то она будет сконвертирована в массив функцией parse_str()).
Как правило, этот параметр используется для передачи в виджеты специфичные для каждой темы HTML-тэги, которые будут использованы как контейнер для виджета и его заголовка. Значения по умолчанию приведены ниже:

'before_widget' => '<li id="%1$s" class="widget %2$s">',
'after_widget' => "</li>n",
'before_title' => '<h2 class="widgettitle">',
'after_title' => "</h2>n"

Как правило для регистрации сайдбаров должна использоваться функция register_sidebars. Единственный случай, при котором вам понадобится вызвать функцию register_sidebar - это необходимость задать индивидульные имена для сайдбаров(например, "Левая колонка" и "Нижняя панель") или если виджеты, входящие в разные сайдбары должны иметь различные, окружающие их, HTML тэги.
Имена сайдбаровпоказываются на странице управления виджетами, а также используются как индексы для сохранения расстановки виджетов. Таким образом, сайдбары, имеющие различные имена в разных темах, будут сохраняться отдельно. Если же имена сайдбаров будут одинаковые, то при смене темы, расстановка сайдбаров, сделанная для предыдущей темы будет сохрантяться. А ее изменение отразиться на все темы, имеющие одинаковые имена сайдаров.
Значения по умолчанию для before и after рассчтаны на случай, когда сайдбар формируется в виде списка с заголовками в виде тэга H2. Именно это рекомендуется разработчиками системы виджетов, что обеспечивает автоматическую совместимость тем и виджетов от разоичных авторов. Для случаев, когда верстка темы не позволяет применять списки, пригодится возможность определения before и after при регистрации сайдбара.

Регистрация сайдбаров с помощью функций register_sidebars и register_sidebar производится в файле functions.php, который должен быть создан в корне каталога темы.

bool dynamic_sidebar ( [ mixed sidebar ] )

Предназначена для использования в шаблонах темы. Генерирует колонку со всеми виджетами, добавленными в нее. Для этого последовательно вызываются callback-функции всех виджетов сайдбара. Если в теме зарегистрирован более чем один сайдбар, то при вызове функции необходимо указывать имя или номер требуемого сайдбара. Функия возвращает true в случае успешного выполнения и false в обратном случае.
Значение, возвращаемое функцией необходимо использовать для определения какой из сайдбаров показывать, динамический или статический, описанный в шаблоне sidebar.php.

Рекомендуемое использование функции dynamic_sidebar в файле sidebar.php:

<ul id="sidebar">
<?php if ( !function_exists('dynamic_sidebar')
|| !dynamic_sidebar() ) : ?>
<li>{static sidebar item 1}</li>
<li>{static sidebar item 2}</li>
<?php endif; ?>
</ul>

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

Функции регистрации виджетов

Описание и регистрация callback-функций для показа виджетов можно сделать либо в плагине, либо в файле functions.php темы. Подробнее это описано ниже.

Каждый виджет состоит как минимум из одной callback-функции, которая должна быть зарегистрирована с помощью специальной функции.

void register_sidebar_widget ( string name, callback [, string classname ]] )

Функция регистрирует callback-функцию для показа виджета с индексом, который формируется по имени(параметр name). Имена виджетов должны быть уникальными, так же, как и имена callback-функций.

Любой виджет это, в основном обычный HTML код. Для его включения в вывод и нужна регистрация.

Виджеты могут быть переопределены или удалены из списка активных виджетов как в плагинах так и в файле functions.php темы. Регистрация виджета с именем, ранее присвоенным другому виджеты, приведет к замене старого виджета на новый(то есть будет использована callback-функция указанная в последнем случае). Если при вызове register_sidebar_widget параметр callback = ''(пустая строка), то виджет будет деактивирован.

С помощью classname можно задать класс стиля для элемента списка. По умолчанию, виджет генерируется в таком виде:
<li id="{name}" class="{callback}">{callback output}</li>
Если же задан classname, то он будет подставлен вместо callback. Name используется в качестве id для элемента потому, что имя виджета всегда уникально.

В функцию register_sidebar_widget после classname, можно передать дополнительные параметры, которые будут переданы в callback-функцию при ее вызове. Например:
register_sidebar_widget('My Widget', 'my_unique_widget', null, 'Hello World!', 'h3')
В этом случае строки 'Hello World!' и 'h3' будут переданы виджету как второй и третий аргумент(первый всегда хэш $args).

void unregister_sidebar_widget ( string name )

Удаляет виджет из списка активных виджетов. Часто используется в темах или плагинах для отключения виджетов, которые не работают с данной темой или плагином.

void register_sidebar_widget_control ( string name, callback [, int width [, int height ] ] )

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

void unregister_widget_control ( string name )

Удаляет callback-функцию вывода конфигурационый формы.

Использование описанных функций мы рассмотрим в следующей статье, на кокретных примерах.

Если у вас возникли вопросы, постараюсь ответить на них в комментариях к статье.

Добавить в закладки: