Обобщенные символы в элементах меню

До сих пор мы использовали в элементах меню обычные имена путей Drupal, такие как menufun и menufun/farewell. Однако в Drupal часто применяются пути вида user/4/track или node/15/edit, где части пути формируются динамически. Рассмотрим этот процесс подробнее.

Основные обобщенные символы

Символ % играет в элементах меню Drupal роль обобщенного символа и означает, что точное значение определяется во время выполнения на основе символа в той позиции URL, где находится обобщенный символ. Вот элемент меню, в котором применяется обобщенный символ:

function menufun_menu() {
 $items['menufun/%'] = array(
 'title' => 'Hi',
 'page callback' => 'menufun_hello',
 'access callback' => TRUE,
 );
return $items;
}

Этот элемент меню срабатывает для путей Drupal menufun/hi, menufun/foo/bar, menufun/123 и menufun/file.html. Однако он не будет работать для пути menufun — для такого пути необходимо написать отдельный элемент меню, потому что он содержит только одну часть, а выражение menufun/% соответствует лишь строкам из двух частей. Символ % часто применяется для обозначения числа (как в user/%/edit для user/2375/edit), однако он соответствует любому тексту в данной позиции.

Обобщенные символы и параметры обратного вызова страницы

Обобщенный символ в конце пути меню не мешает передаче дополнительных путей URL в обратный вызов пути, поскольку обобщенный символ соответствует тексту только до ближайшей наклонной черты. Вернемся к примеру пути menufun/%: в адресе http://example.com/?q=menufun/foo/Fred строка foo соответствует обобщенному символу, а последняя часть пути (Fred) передается в качестве параметра в обратный вызов страницы.

Использование значения обобщенного символа

Чтобы использовать соответствующую часть пути, нужно указать номер этой части в ключе page arguments:

function menufun_menu() {
 $items['menufun/%/bar/baz'] = array(
 'title' => 'Hi',
 'page callback' => 'menufun_hello',
 'page arguments' => array(1), // Фрагмент, соответствующий обобщенному символу
 'access callback' => TRUE,
 );
 return $items;
}

/**
* Обратный вызов страницы.
*/
function menufun_hello($name = NULL) {
 return t('Hello. $name is @name', array('@name' => $name));
}

Параметры, переданные функции обратного вызова страницы menufun_hello(), будут такими, как показано на рис. 4.11. Первый параметр $name передается с помощью обратного вызова страницы. Элемент array(1) для обратного вызова страницы означает: “передать часть 1 пути, какой бы она ни была”. Нумерация начинается с 0, так что частью 0 будет menufun, частью 1 — то, что соответствует обобщенному символу, частью 2 — bar и т.д. Второй параметр $b передается в соответствии с правилом передачи в Drupal части пути за пределами пути Drupal в качестве параметра (см. раздел “Аргументы обратного вызова страницы” ранее в главе).

Обобщенные символы и замена параметров

На практике части пути Drupal обычно используются для просмотра или изменения какого-либо объекта — вроде ноды или пользователя. Например, путь node/%/edit применяется для редактирования ноды, а путь user/% — для просмотра информации о пользователе по его идентификатору. Рассмотрим элемент меню для последнего случая, который можно найти в реализации hook_menu() в модуле modules/user/user.module. URL, соответствующий данному пути, будет иметь вид, подобный http://example.com/?q=user/2375. Такой URL предназначен для того, чтобы, щелкнув на нем, увидеть страницу My account (Моя учетная запись) на сайте Drupal.

$items['user/%user_uid_optional'] = array(
 'title' => 'My account',
 'title callback' => 'user_page_title',
 'title arguments' => array(1),
 'page callback' => 'user_view_page',
 'page arguments' => array(1),
 'access callback' => 'user_view_access',
 'access arguments' => array(1),
 'weight' => -10,
 'menu_name' => 'user-menu',
);

Когда среда Drupal создает меню на основе пути user/%user_uid_optional, она заменяет фрагмент %user_uid_optional согласно описанному ниже процессу.

1. Во втором сегменте находится строка, соответствующая % с последующими символами до ближайшей наклонной черты. В данном случае это user_uid_optional.
2. К этой строке добавляется _load для получения имени функции. В данном случае именем функции будет user_uid_optional_load.
3. Эта функция вызывается с передачей ей в качестве аргумента значения обобщенного символа из пути Drupal. Если URL выглядит как http://example.com/?q=user/2375, путем Drupal является user/2375, и обобщенный символ соответствует второму сегменту — 2375. Поэтому производится вызов user_uid_optional_load('2375').
4. Затем результат этого вызова используется вместо обобщенного символа. Поэтому при обратном вызове заголовка с аргументами заголовка array(1) вместо передачи части 1 пути Drupal (2375) передается результат вызова user_uid_optional_load('2375') — т.е. объект пользователя. Этот процесс можно рассматривать как замену части пути Drupal соответствующим объектом.
5. В обратных вызовах страницы и доступа также используется объект замены. Поэтому в предыдущем элементе меню будет выполнен вызов user_view_access() для доступа и user_view() для генерации контента страницы, и в обоих вызовах будет передан объект пользователя 2375.

Передача дополнительных аргументов функции загрузки

Если функции загрузки необходимо передать дополнительные аргументы, их можно определить в ключе load arguments. Ниже приведен пример из модуля node — элемент меню для просмотра ревизии ноды. И идентификатор ноды, и идентификатор ревизии необходимо передать функции загрузки — в данном случае node_load().

$items['node/%node/revisions/%/view'] = array(
 'title' => 'Revisions',
 'load arguments' => array(3),
 'page callback' => 'node_show',
 'page arguments' => array(1, TRUE),
 'access callback' => '_node_revision_access',
 'access arguments' => array(1),
);

Специальные предопределенные аргументы загрузки %map и %index

Сборка путей из обобщенных символов с помощью функций to_arg()

1. Первоначальный путь Drupal — user/%user_uid_optional.
2. При построении ссылки Drupal ищет функцию с именем user_uid_optional_to_arg(). Если такая функция не определена, Drupal не может выяснить, как построить путь, и не выводит ссылку.
3. Если функция определена, Drupal использует результат ее вызова для замены обобщенного символа в ссылке. Функция user_uid_optional_to_arg() возвращает идентификатор текущего пользователя, поэтому если это пользователь 4, то Drupal связывает ссылку My account с адресом http://example.com/?q=user/4.

Специальные варианты обобщенных символов и функции to_arg()

/**
* Реализация hook_menu().
*/
function menufun_menu() {
 $items['menufun/%a_zoo_animal'] = array(
 'title' => 'Hi',
 'page callback' => 'menufun_hello',
 'page arguments' => array(1),
 'access callback' => TRUE,
 'type' => MENU_NORMAL_ITEM,
 'weight' => -10
 );
return $items;
}

function menufun_hello($animal) {
 return t("Hello $animal");
}

function a_zoo_animal_to_arg($arg) {
 // $arg содержит '%', т.к. это обобщенный символ.
 // Заменим его животным из зоопарка.
return 'tiger';
}