четверг, 7 апреля 2011 г.

Как создавать плагины стиля для панелей.


Создание плагинов паналей — это очень сильная вещь, точнее - правильный путь работы с панелями. Вы можете определять различные стили для вашего клиента, из которых он может выберать, какой тип вывода панелей использовать, как он будет выглядеть. Придерживая этого вы сделаете вашу работу более чистой, ваш код под контролем версии, дизайнер будет работать как он и работал, ваша совесть остаётся чистой.
Оригинал статьи(Английский)

Статья предполагает, что вы знаете об работе с панелями, больше чем как только название. Вы должны знать, что панели используют модуль ctools, который в ходит состав API и инструментов для облегчения процесса разработки.
Далее мы будем создавать ctools плагин, что бы применить новый стиль панелей. Извеняюсь, если я вас уже чем то напугал. Мы должны просто двигаться вперёд, мы должны будем сделать вот это:
choose_style.png
... а потом это:
choose_style2.png
Назовём наш модуль ctoolsplugins.

1. Создаём новый модуль, уведомляем ctools об нашем плагине.

Ничего особенного вам не требуется, только info, module файлы, ничего нового.

1.1 Объявление зависимостей.

Очевидно, что нам нужен ctools модуль, также панели не будут работать без page_manager модуля, потому:
; $Id:
name = Ctools Plugins
description = Our custom ctools plugins
core = 6.x
dependencies[] = ctools
dependencies[] = panels
dependencies[] = page_manager
package = Chaos tool suite

1.2 Реализуем hook_ctools_plugin_directory для того чтобы оповестить ctools об нашем плагине.

В файле модуля мы реализуем эту функцию, если ctools проверяет плагин, мы говорим ему о нашем существовании:
/**
  * Implementation of hook_ctools_plugin_directory().
  */
function ctoolsplugins_ctools_plugin_directory($module, $plugin) {
  if (
$module == 'panels' && $plugin == 'styles') {
    return
'plugins/' . $plugin;
  }
}
?>

2. Готовим файловую структуру для гаших плагинов, создаём файл плагина..

Рисунок — наилучшее объяснение:
ctoolsplugin_directories.png
Назовём наш плагин 'collapsible', потому мы создаём внутри ctoolsplugins/plugins/styles/ файл collapsible.inc.

3. Реализуем плагин нашего стиля в collapsible.inc

3.1 Определим наши цели и потребности.

Хорошо, теперь мы должны подумать, что будет реализовано в нашем плагине и для чего.
  • Используется только для разметки?
  • Будут ли предоставлены дополнительные настройки?
  • Будет ли встроен javascript?
Пользуясь случаем, научим вас использовать возможность ctools - collapsible div(Сворачивающийся div). Наш стиль будет в основном конвертировать любую панель в сворачивающуюся панель:
collapsed_pane.png
Так как мы дружественные разработчики, дадим возможность настраивать другим пользователям самостоятельно, какая панель будет открытой, а какая закрытой. Это означаем, что нам надо создать дополнительную форму настройки, что мы получили следующее:
ctools_style_options.png

3.2 Реализация hook_panels_style_info

Наименавоние играет важную роль, оно должно быть похожим на навзваниемодуля_stylename_panels_style. Возращается массив определяющий ваш стиль:
/**
* @file
* Definition of the 'collapsible' panel style.
*/


/**
* Implementation of hook_panels_style_info().
*/
function ctoolsplugins_collapsible_panels_styles() {
  return array(
     
'title' => t('Collapsible div'),
     
'description' => t('Display the pane in a collapsible div.'),
     
'render pane' => 'ctoolsplugins_collapsible_style_render_pane',
     
'pane settings form' => 'ctoolsplugins_collapsible_style_settings_form',
  );
}
?>
'title' , 'description' нет необходимости в объяснении.
'render pane' — указываем название функции, которое будет проводить преобразование вида панели.
'pane settings form' — указывает на функцию, которая обеспечивает форму дополнительных настроек.

3.3 Определение функции обратного вызова формы настраивания панели.

Название функции должносоответсвовать тому, что вы указали в 'pane settings form' раньше. Достаточно просто определить массив формы настройки используя FAPI documentation.
/**
* Settings form callback.
*/
function ctoolsplugins_collapsible_style_settings_form($style_settings) {
 
$form['collapsed'] = array(
   
'#type' => 'select',
   
'#title' => t('Startup behaviour'),
   
'#options' => array(
     
0 => t('Start opened'),
     
1 => t('Start collapsed'),
    ),
   
'#default_value' => (isset($style_settings['collapsed'])) ? $style_settings['collapsed'] : 'opened',
   
'#description' => t('Choose whether you want the pane to start collapsed or opened'),
  );

  return
$form;
}
?>



В данном случае предоставляется одна настройка начального положения. Если настройка не установлення, все выводятся развёрнутыми, если установлена — свёрнутыми.

3.4 Определение функции обратного вызова преобразования вывода.

Название должно совпадать с тем, что определенно в 'render pane'. Это просто функция темизации, где появляется возможность изменить, то что будет показано на странице.
/**
* Render callback.
*
* @ingroup themeable
*/
function theme_ctoolsplugins_collapsible_style_render_pane($content, $pane, $display) {
 
$style_settings = $pane->style['settings']; // good idea for readability of code if you have a ton of settings
 
$start_settings = $style_settings['collapsed']; // we can do this be cause the only values possible are 0 or 1

 
$pane_content = $content->content;

  if (
$content->title) {
   
$pane_title = '

'. $content->title .'

';

   
// theme('ctools_collapsible', $handle, $content, $collapsed);
   
$result = theme('ctools_collapsible', $pane_title, $pane_content, $start_settings);
  }

 
// if we don't have a pane title, we just print out the content as normaly, since there's no handle
 
else {
   
$result = $pane_content;
  }

  return
$result;
}
?>
Важно отметить, что настройки указанные пользователем хранятся в $pane->style['settings']. В этом примере мы проверяем наличие заголовка, для того что бы применить ctools_collapsible, сделать нашу страницу с сворачивающимся/ разворачивающимся панелями, иначе мы выводим контент без изменений.



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

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

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