Drupal 7: определение шаблонов tpl.php и функций темизации. Хуки темизации.

Для облегчения жизни темизаторам, в Drupal существует система шаблонов. Расширяется она с помощью хука hook_theme().

Определенный в функции hook_theme хук темизации, можно будет переопределить в теме при помощи функции темизации либо шаблона, определим в модуле example_template:

function example_template_theme() {
  return array(
    'custom_template' => array( // название хука темизации
      'variables' => array( // переменные которые будут доступны в шаблоне
        'body' => NULL,
        'title' => NULL,
      ),
    ),
  );
}

Теперь для вызова данного хука темизации нужно воспользоваться конструкцией:

theme('custom_template', array('body' => 'Some body', 'title' => 'Some title'));

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

В модуле необходимо определить либо функцию темы либо шаблон, которые будут использоваться по умолчанию и браться из модуля. Для этого нужно создать функцию с именем theme_ИМЯ_ХУКА_ТЕМИЗАЦИИ()

Определяем функцию в модуле:

function theme_custom_template($variables) {
  $output = '<div class="custom-template-wrapper">';
  $output .=    '<div class="body">';
  $output .=      $variables['body'];
  $output .=    '</div>';
  $output .=    '<div class="title">';
  $output .=      $variables['title'];
  $output .=    '</div>';
  $output .= '</div>';
  return $output;
}

Для того что бы использовать шаблон из модуля по умолчанию необходимо в определение хука темизации в hook_theme добавить параметр расположения шаблона:

function example_template_theme() {
  return array(
    'custom_template' => array(
      'variables' => array( // переменные которые будут доступны в шаблоне
        'body' => NULL,
        'title' => NULL,
      ),
      // имя шаблона, в данном случае custom_template.tpl.php в корне модуля
      'template' => 'custom_template',
    ),
  );
}

После определение хука темизации, его можно переопределить в любой теме:

function MYTHEME_custom_template($variables) {
  $output = '<div class="mytheme-custom-template-wrapper">';
  $output .=    $variables['title'] . ' - ' . $variables['body'];
  $output .= '</div>';
  return $output;
}

Для использования шаблона, а не функции, нужно создать шаблон c именем хука example_template.tpl.php и положить в папку с темой либо вложенную в тему папку templates.

ВАЖНО! Одновременно не могут использоваться функция темизации и шаблон, больший приоритет имеет функция и поэтому будет использоваться именно она.

Полный код:

/**
 * @file
 * Example template
 */

/**
 * Implemets hook_menu().
 */
function example_template_menu() {
  $items['example_template'] = array(
    'title' => 'Example template',
    'page callback' => 'example_template_callback',
    'access callback' => TRUE,
    'type' => MENU_NORMAL_ITEM,
  );
  return $items;
}

/**
 * Implements hook_theme().
 */
function example_template_theme() {
  return array(
    'custom_template' => array( // название хука темизации
      'variables' => array( // переменные которые будут доступны в шаблоне
        'body' => NULL,
        'title' => NULL,
      ),
      // имя шаблона, в данном случае custom_template.tpl.php в корне модуля
      'template' => 'custom_template',
    ),
  );
}

/**
 * Page callback.
 */
function example_template_callback() {
  return theme('custom_template', array('body' => 'Some body', 'title' => 'Some title'));
}

/**
 * Returns HTML for a custom template.
 *
 * @param $variables
 *   An associative array containing:
 *   - body: body text.
 *   - title: title text.
 *
 * @ingroup themeable
 */
function theme_custom_template($variables) {
  $output = '<div class="custom-template-wrapper">';
  $output .=    '<div class="body">';
  $output .=      $variables['body'];
  $output .=    '</div>';
  $output .=    '<div class="title">';
  $output .=      $variables['title'];
  $output .=    '</div>';
  $output .= '</div>';
  return $output;
}

Github