Виджеты в MaxSite CMS

Сегодня меня посетила муза :-) и я смог придумать, как реализовать виджеты. Задача на самом деле сложная. Если сравнивать с WordPress, то сразу же приходит на ум АЯКС, JS и насколько сложно и запутано там все получается.

Виджет это не просто блок для вывода в сайдбаре, но еще и его настройка. Таким образом для разработчика стоит сразу несколько задач.

• Сайдбары (или любой другой блок) зависит от шаблона. В шаблоне необходимо предусмотреть функцию, которая будет подключать/сообщать, что существует такой-то сайдбар.
• Сайдбар содержит разные виджеты в разном порядке. То есть сайдбар имеет какие-то свои опции. Порядок и список виджетов необходимо определять в админке.
• Виджеты сами по себе имеют свои опции, которые тоже следует сохранять.
• Все виджеты должны быть множественны. То есть один и тот же виджет можно размещать в сайдбарах сколько угодно раз. Но поскольку каждый виджет может иметь собственные настройки, необходимо как-то их различать.
• Поскольку виджеты могут иметь свои опции, то должна быть и функция, которая будет выводить форму и обрабатывать полученные данные.

Вот в кратце начальное ТЗ. Теперь о том, что получилось.

Я не стал изобретать велосипед и виджеты оформил в виде плагина. То есть любой плагин может содержать виджет. Рассмотрим его структуру на примере плагина Календаря (calendar).

function calendar_autoload($args = array())
{
    mso_register_widget('calendar_widget', 'Календарь'); 
}

Функция «..._autoload» будет автоматически выполняться при инициализации включенного плагина. В ней мы регистрируем виджет. Первый параметр указывает имя функции виджета (по сути она и будет выполняться в сайдбаре). Второй параметр просто название виджета.

function calendar_widget($num = 1) 
{
    $widget = 'calendar_widget_' . $num;
    $options = mso_get_option($widget, 'plugins', array() );
    return calendar_widget_custom($options, $num);
}

Данная функция и есть виджет. У ней только один параметр - номер. Для того, чтобы различать виджеты (одной функции), мы указываем его номер. По этому номеру мы и получаем опции этого виджета (mso_get_option). Последняя строчка (в return) - это функция, которая непосредственно выводит календарь. Мы ей передаем наши опции и номер.

Впрочем вызов «рабочей» функции может быть различен и зависит от конкретного плагина.

Теперь посмотрим, как оформлять форму настроек виджета.

function calendar_widget_form($num = 1) 
{
    $widget = 'calendar_widget_' . $num;
    $options = mso_get_option($widget, 'plugins', array());
    
    // вывод самой формы
    $CI = & get_instance();
    $CI->load->helper('form');
    
     $form = '<p><b>Заголовок:</b> '
             . form_input( array( 
                                'name'=>$widget . 'header', 
                                'value'=>$options['header'] 
                                ) 
                          );
    return $form;
}

Прежде всего следует обратить внимание на название функции. Оно получается из «виджет_form». То есть когда в админке происходит обработка всех виджетов, то для вывода формы будет использоваться именно такое именование. Такое соглашение позволяет упростить разработку виджетов.

Сама функция работает очень просто. Вначале мы получаем опции по нашему ключу. Далее подключается хэлпер CodeIgniter, который упрощает вывод элементов формы. В конце мы формируем поле для заголовка календаря. В качестве name поля (input) нужно указывать «виджет_опция». Это телается для того, что в админке все формы отображаются на одной странице и нужно как-то различать все эти элементы.

В завершении мы возвращаем подготовленную форму. Кстати еще одно замечание. Почти во всех функциях я использую return, а не echo. Это позволяет получив результат еще что-то с ним сделать, а уже потом вывести. Все виджеты же должны всегда возвращать результат в виде return, поскольку их непосредственный вывод осуществляется совсем другой функцией (в сайдбаре).

Последняя функция виджета - это функция, которая срабатывает, когда происходит обновление опций.

function calendar_widget_update($num = 1) 
{
    // имя виджета
    $widget = 'calendar_widget_' . $num;
    // получаем опции
    $options = $newoptions = mso_get_option($widget, 'plugins', array());
    
    // получаем данные из _POST указаного name
    $newoptions['header'] = mso_widget_get_post($widget . 'header');
    
    // обновляем-сохраняем опции
    if ( $options != $newoptions ) 
       mso_add_option($widget, $newoptions, 'plugins');
}

Тут тоже все довольно просто. Мы получаем текущие опции; проверяем данные _POST (как раз здесь и указывается имя нужного нам элемента формы input). Для упрощения я сделал функцию mso_widget_get_post, которая принимает _POST и возвращает значение указанного элемена формы. В случае, если поля нет, возвращается пустая строка.

В завершении мы проверяем изменились ли опции и, если изменились, то добавляем новые опции (обновлять или добавлять определяется автоматически в mso_add_option).

С самим плагином на этом всё. Разберемся теперь с шаблоном.

Виджеты располагаются в сайдбарах. Строго говоря, сайдбар совершенно не обязательно должен быть именно sidebar. Это может быть любой блок в любом месте шаблона. Просто такое именование принято в WordPress и я не стал его менять.

Для того, чтобы сообщить системе, что у нас есть сайдбары мне пришлось ввести в шаблон файл functions.php. Такой же файл есть и в WordPress. Он подключается при инициализации системы. В нем мы и зарегистрируем наши сайдбары.

    mso_register_sidebar('1', 'Первый сайдбар');
    mso_register_sidebar('2', 'Второй сайдбар');

Первый параметр - название, второй - заголовок. Данная функция только сообщает системе, что в нашем шаблоне будет использовано два сайдбара. Больше он ничего не делает.

Для вывода виджетов нужно в файле сайдбара (нашего шаблона), например в sidebar-1.php, написать:

    mso_show_sidebar('1', '<div class="widget">', '</div>' );

Первый параметр - название сайдбара, второй - текст в начале каждого виджета, третий - в конце каждого виджета.

На этом все программирование и заканчивается. :-) Идем в админку.

Для настройки сайдбаров есть отдельный пункт меню. В нем две закладки: «Настройки сайдбаров» и «Настройка виджетов».

В первой закладке располагаются многострочные текстовые поля (textarea) для каждого зарегистрированного сайдбара. Поскольку я решил (пока) не использовать AJAX, то в каждом текстовом поле нужно указать необходимые виджеты. Их полный список приведен внизу в качестве подсказки. Поэтому вся операция по сути сводится к копированию. После того, как система будет отлажена небольшая «прививка» JS позволит добавлять виджеты просто кликая на их название. Пока же так.

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

calendar_widget 1
calendar_widget 2
calendar_widget 3

После сохранения сайдбаров, можно настроить сами виджеты. Для этого переключаемся на вкладку «Настройка виджетов», где отображены сайдбары с указанными виджетами. Каждый виджет имет свою форму настройки. Заполняем как нужно и сохраняем изменения.

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