Программный вывод полей в Drupal 7

При работе с проектами на Drupal 7 нередко возникает необходимость вывода данных нестандартно, т. е. без использования инструментов пользовательского интерфейса. Несмотря на то, что даже стандартный способ вывода данных или полей достаточно гибок и универсален, однако бывают ситуации, когда лучше и проще прибегнуть к программному способу. Другими словами, выводить поля, написав соответствующий код, используя API Drupal. В данной статье будет показано, в каких ситуациях и как вывести поля программным способом.

Когда нужно выводить поля программно?

Поле необходимо выводить программно в следующих случаях:

• Когда изначально не представляется возможным задействовать стандартный инструментарий пользовательского интерфейса, по-умолчанию предоставляемого Drupal. Например, когда разрабатывается новый модуль, который работает с данными полей, которые необходимо определённым образом отображать;
• Когда необходимо вывести поле в непредусмотренном для него месте.

Все эти ситуации объединяет один фактор: поле выводится вне своей сущности. Любое поле в Drupal принадлежит какой-либо структуре данных. Когда из этой структуры данных берётся отдельное поле (или его значение) и далее выводится отдельно от его структуры данных, то это в частности, и есть программный вывод поля. Сама же структура данных, к которой принадлежит поле — это и есть сущность.

Для примера можно рассмотреть распространённую ситуацию. Пусть требуется вывести в боковой колонке содержимое самого популярного или высокооценённого комментария для какой-либо из статей. Сам комментарий — это целостная структура данных, состоящая из таких полей как: тема, автор, дата размещения, количество лайков, ну и конечно же — само основное содержимое комментария. Именно это содержимое (т. е. поле) необходимо вывести отдельно без остальных полей структуры данных в совершенно другом месте страницы. Для этого используется программный вывод вручную с помощью специальных функций API Drupal.

Конечно, для подобных задач можно использовать такие замечательные модули как Views и/или Panels. Однако, в простых случаях, проще и быстрее сделать это программно. Всё-таки Views и Panels разрабатывались как раз для очень сложного вывода полей и их компоновок.

В итоге, программный вывод полей применяется для их вывода вне их сущностей. Теперь, для более полного понимания, необходимо разобраться с «сущностями» Drupal.

Что такое сущности Drupal 7?

Сущность Druapl – это уровень абстракции, характеризующий структуры данных Drupal. Таких структур в Drupal очень много, поэтому в 7-й версии этой CMS разработчиками было введено такое понятие — сущность или entity.

Как можно догадаться из предыдущей главы, комментарий — это сущность типа «comment». Тип материала, нода (node – узел), пользователи, термины таксономии, блоки — это также сущности, состоящие из определённого набора полей. Сущности можно формировать и создавать самостоятельно. После этого они будут готовы к выводу как единое целое.
Поле Drupal является базовым элементом в структуре объектов Drupal. Что касается ноды Drupal, то с технической точки зрения, нода — это верхушка иерархии этих объектов, наиболее общая сущность, практически объединяющая все остальные. Визуально для пользователя, нода — это отображаемая в конечном виде страница Drupal. Содержащая материал, блоки, комментарии, теги и т. д. Которые, в свою очередь, также являются сущностями. Получить доступ к отдельным полям сущностей, и автоматически настроить их вывод позволяет функция field_view_field() из API Drupal 7.

Использование функции field_view_field()

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

• получает доступ к самому полю, используя в качестве входных параметров тип его сущности, идентификатор сущности, а также машинное имя самого поля;
• с помощью дополнительных параметров (если так будет угодно программисту) настраивает поле для последующего вывода.

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

• выводить ли поле вместе с его меткой (Label);
• если это текст, то в каком объёме (по количеству символов) его вывести;
• если это изображения (или ссылка на него), то какой формат (размер, графические эффекты) к нему применить;
• и многие другие.

В итоге функция field_view_field() вернёт отформатированный набор данных, который остаётся только отрендерить на странице в нужном месте с помощью функции render().

Синтаксис функции field_view_field() следующий:

<?php
field_view_field($entity_type, $entity, $field_name, $display, $langcode)

Назначение её параметров:

• $entity_type – тип сущности (например комментарий или нода), к полю которого нужно получить доступ;
• $entity – идентификатор сущности;
• $field_name – машинное имя поля, к которому нужно получить доступ;
• $display – настройки отображения поля, которые могут быть заданы в составе массива опций, определяющих вывод;
• $langcode – опционально, задаёт язык кода, на котором должно отображаться значение поля.

Небольшой пример:

<?php
$nid = node_load($node);
$output = field_view_field(‘node’, $nid, ‘field_preamble’, array(
         ‘label’ => ‘hidden’,
         ‘type’ => ‘test_summary_or_trimmed’,
         ‘settings’ => array(‘trim_length’ => 150)));
render($output);

В данном примере опущена HTML-разметка для чистоты восприятия кода, который в произвольном месте страницы выводит поле «field_preamble». Хранящее содержимое преамбулы к статье. Также производится его форматирование, которое заключается в том, чтобы не выводилась метка этого поля, а содержимое было обрезано до 150 символов. Возвращаемый результат присваивается переменной $output. После чего она передаётся в функцию render() для рендеринга на странице.

А как быть, когда сущность имеет несколько значений одного поля? Например, когда для поля «field_image» определено несколько значений, т. е. изображений. Нужно сначала получить список всех значений поля с помощью функции field_get_items(). А затем, отобрав нужное значение, обработать его функцией field_view_value(). Которая аналогична field_view_field(), но предназначена для работы с конкретным значением поля. Пример:

<?php
$image = field_get_items(‘node’, $nid, ‘field_image’);
$output = field_view_value(‘node’, $nid, ‘field_image’, $image[0], array(
       ‘label’ => ‘hidden’,
       ‘type’ => ‘image’,
       ‘settings’ => array(
               ‘image_style’ => ‘thumbnail’,
               ‘image_link’ => ‘content’,
      ),
));

Как можно видеть, сначала определяется список значений поля «field_image», который присваивается переменной $image. Далее, функция field_view_value() получает доступ к переданному ей нужному значению поля «field_image» (по индексу списка или массива $image[]) и форматирует его вывод для последующего рендеринга.

Заключение

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