УрокПишем плагин к Panels с помощью Ctools

Не так давно я очень плотно подружился связкой модулей Views + Panels + Page manager (входит в Ctools). Как оказалось, с их помощью можно много времени сэкономить на многих задачах. В добавок ко всему производительность отличная (выяснилось, что Panels работает быстрее, чем стандартные блоки ядра). Вдохновиться можно посмотрев скринкасты по работе с этой связкой. Живой пример могу показать на примере своей работы - footballtop.ru. Около 90% страниц построено именно на этой связке.

В общем, ближе к теме разговора. Передо мной стояла задача написать не совсем обычную форму голосования, со своими плюшками. Далее эту форму надо было закинуть через Panels в материалы, т.к. все ноды были уже переделаны с помощью панелей, и hook_node_view() уже не срабатывал. Саму реализацию голосования я оставлю за рамками статьи, а вот на написании плагина остановлюсь подробнее.

Первое, на что я бы хотел обратить внимание - это то, что для Panels плагины не пишутся. Они пишутся с помощью API модуля Ctools. Поэтому по сути, плагин пишется именно к Ctools (или с его помощью, как вам угодно), а далее он нам будет автоматически доступен при работе с Panels через веб интерфейс.

Итак, давайте пошагово пройдёмся по этапам создания плагина.

Шаг первый. Описываем папку с плагином.

Первым делом надо указать в какой папке будут храниться плагины. По традиции они хранятся в папке plugins внутри модуля. Папка указывается с помощью имплементирования в модуле хука hook_ctools_plugin_directory(). После описания папки, Ctools автоматически подхватит все плагины из неё.

/**
 * Implements hook_ctools_plugin_directory().
 */
function ИМЯМОДУЛЯ_ctools_plugin_directory($owner, $plugin_type) {
  if ($owner == 'ctools') {
    return 'plugins/' . $plugin_type;
  }
}

Здесь надо отметить, что плагины хранятся не сразу в директории plugins, а они ещё и по категориям разбиты разбиты. Вот список категорий:

• access - плагины к уровням доступа. Позволяют указывать проверки, при которых пользователь получит или не получит доступ к содержимому.
• arguments - плагины, описывающие возможные аргументы, которые можно получить из урла страницы.
• cache - плагины, описывающие возможные механизмы кэширования.
• content_types - плагины, которые выводят содержимое. Например, элементы материала, формы, произвольно заданное содержимое и т.д.
• context - плагины, описывающих возможные контексты, которые могут быть использованы в настройках панелей или передаче их в другие сущности.
• relationships - плагины, описывающие возможные взаимосвязи между сущностями.

Так как в моём случае надо было писать плагин по выводу содержимого, то он у меня хранился по адресу plugins/content_types/ftop_vote_widget.inc, где ftop_vote_widget - название плагина.

Шаг второй. Предоставляем информацию о плагине.

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

if (module_exists('ftop_vote')) {
  $plugin = array(
    'single' => TRUE,
    'title' => t('FootballTop Vote Widget'),
    'description' => t('Voting widget for footballtop.ru.'),
    'category' => t('Node'),
    'render callback' => 'ftop_vote_widget_content_type_render',
    'required context' => new ctools_context_required(t('Node'), 'node'),
  );
}

Таким образом я смог сказать Ctools, что мой плагин должен быть помещён в категорию Node, и для его подключения ему необходимо передать объект ноды из контекста (если в контекстах ноды не будет, то я не смогу выбрать этот плагин). Однако я использовал не все параметры в описании, которые доступны. Вот более полный список:

$plugin = array(
 
  // Название плагина, которое будет отображено при его выборе.
  'title' => t('Simplecontext content type'),
 
  // Описание плагина, которое будет отображено при его выборе.
  'description' => t('Simplecontext content type - works with a simplecontext context.'),
 
  // Конструктор.
  'content_types' => 'simplecontext_content_type',
 
  // Показывает, является ли плагин подтипом другого. В данном случае - не является.
  'single' => TRUE,
 
  // Название функции, которая будет создавать блок с данными.
  'render callback' => 'simplecontext_content_type_render',
 
  // Иконка, отображаемая при выборе плагина.
  'icon' => 'icon_example.png',
 
  // Контекст, который необходимо передать плагину для его работы.
  'required context' => new ctools_context_required(t('Simplecontext'), 'simplecontext'),
 
  // Форма с дополнительными настройками плагина.
  'edit form' => 'simplecontext_content_type_edit_form',
 
  // Административный заголовок модуля, который может быть изменён через веб интерфейс.
  'admin title' => 'ctools_plugin_example_simplecontext_content_type_admin_title',
 
  // Создаёт блок предпросмотра результата в Panels.
  'admin info' => 'ctools_plugin_example_simplecontext_content_type_admin_info',
 
  // Категория, в которую будет помещён плагин, и его вес.
  'category' => array(t('CTools Examples'), -9),
 
  // Контексты, передаваемые по умолчанию.
  'defaults' => array(),
);

Шаг третий. Реализуем функции из описания плагина.

В моём это только одна функция - ftop_vote_widget_content_type_render(), которая с помощью полученных в Panels данных подгружает форму с голосованием:

/**
 * Render the custom content type.
 */
function ftop_vote_widget_content_type_render($subtype, $conf, $panel_args, $context) {
 
  // На всякий случай, если вдруг контекст был, плагин включили, а потом контекст убрали.
  if (empty($context) || empty($context->data)) {
    return;
  }
 
  // Забираем нашу ноду из контекста.
  $node= $context->data;
 
  // Создаём блок с формой и передаём ей ноду.
  $block = new stdClass();
  $block->module  = 'ftop_vote';
  $block->content = drupal_get_form('ftop_vote_form', $context->data);
  return $block;
}

Эта функция получает следующие параметры:

• $subtype - используемый подтип. В моём случае его нет, поэтому будет передано 'ftop_vote_widget'.
• $conf - массив с пользовательскими настройками плагина. По умолчанию здесь может быть только заголовок блока, но если вы описывали форму с дополнительными настройками - то они окажутся в этом массиве.
• $panel_args - аргументы, которые были переданы в Panels в их необработанном виде.
• $context - контексты, который (или которые) выбрал пользователь для передачи в плагин.

Вот, собственно, и всё. В итоге плагин с описанием директории и его самого у меня занял ровно 36 строк кода (и это вместе с комментариями и отступами!). Совсем немного, для подключения модуля к такой машине, как Panels, не так ли ? :)