Сложные поля в Carbon fields, действуют как контейнеры, в которые можно добавить несколько групп полей. Они представлены в виде таблицы, где каждая строка является группой полей. Пользователь может добавлять бесконечные строки каждой группы. Это позволяет многократно повторять набор полей, создавая настраиваемые и сортируемые списки. Это полезно при создании галерей изображений, списков данных или расширенного содержимого и элементов макета.
<?php Field::make( 'complex', 'crb_slider', __( 'Slider' ) ) ->add_fields( array( Field::make( 'text', 'title', __( 'Slide Title' ) ), Field::make( 'image', 'photo', __( 'Slide Photo' ) ), ) )
В приведенном выше примере показано, как сделать слайдер. Мы создали одно сложное поле с именем slide, к которому мы прикрепили одну группу полей, представляющую один слайд – заголовок и фотографию. Пользователь сможет добавить несколько строк заголовка и фотографии, таким образом, создавая список слайдов для слайд-шоу.
Более расширенное использование сложного поля показано ниже:
Field::make( 'complex', 'crb_media_item' ) ->add_fields( 'photograph', array( Field::make( 'image', 'image' ), Field::make( 'text', 'caption' ), ) ) ->add_fields( 'movie', array( Field::make( 'file', 'video' ), Field::make( 'text', 'title' ), Field::make( 'text', 'length' ), ) )
Здесь мы должны создать список медиа-элементов, скажем, для художественной выставки. Существует два типа элементов-фотографии (определяемые изображением и подписью) и фильмы (имеющие название, длину и сам видеофайл). Поскольку элементы имеют разные свойства, нам нужно определить отдельную группу для каждого из них. Группы также должны иметь название, по которому они будут распознаны позже – фотография и фильм.
Как вы можете видеть, в зависимости от их использования, сложные поля могут содержать либо одну безымянную группу, либо несколько именованных групп.
Несколько групп
Для добавления нескольких групп полей используется add_fields ($name, $fields ), где:
$ name — уникальное имя группы.
$ fields — числовой массив полей.
Field::make( 'complex', 'crb_media' ) ->add_fields( 'photograph', array( Field::make( 'text', 'caption', __( 'Caption' ) ), Field::make( 'image', 'image', __( 'Image' ) ) ->set_value_type( 'url' ), ) ) ->add_fields( 'movie', array( Field::make( 'text', 'length', __( 'Length' ) ), Field::make( 'text', 'title', __( 'Title' ) ), Field::make( 'file', 'video', __( 'Video' ) ) ->set_value_type( 'url' ), ) )
Каждый вызов add_fields ($name, $fields ) создает новую группу и добавляет ее в сложное поле.
Вы также можете дать каждой группе метку, отличную от имени, используя add_fields( $name, $label, $fields ).
Все данные, хранящиеся в сложном поле, возвращаются в виде двумерного массива следующего формата:
array ( 0 => array ( '_type' => 'photograph', 'caption' => 'Lorem Ipsum', 'image' => 'http://example.com/wp-content/uploads/2012/12/Jellyfish.jpg', ), 1 => array ( '_type' => 'movie', 'length' => '1:56', 'title' => 'Dolor sit amet', 'video' => 'http://example.com/wp-content/uploads/2012/12/video_new.mp4', ), 2 => array ( '_type' => 'photograph', 'caption' => 'Consectetur adipiscing elit', 'image' => 'http://example.com/wp-content/uploads/2012/12/Koala.jpg', ), )
Каждый элемент представляет значения, хранящиеся в одной группе. Название группы хранится в элементе с ключом _type. Когда сложное поле содержит только одну группу, его тип будет пустой строкой – «».
Сложные значения полей извлекаются с помощью carbon_get_post_meta() или carbon_get_theme_option() (или другой функции извлечения, в зависимости от контейнера, в который она добавляется) и передают строку «complex» в качестве аргумента $type.
Методы Конфигурации
set_duplicate_groups_allowed( $allowed = true ) — установите, разрешены ли повторяющиеся группы.
Этот метод применим только к определению сложных полей нескольких групп. Использование его с одной группой не будет иметь никакого эффекта.
Field::make( 'complex', 'crb_media' ) ->set_duplicate_groups_allowed( false ) ->add_fields( 'photograph', array( Field::make( 'text', 'caption', __( 'Caption' ) ), Field::make( 'image', 'image', __( 'Image' ) ) ->set_value_type( 'url' ), ) ) ->add_fields( 'movie', array( Field::make( 'text', 'length', __( 'Length' ) ), Field::make( 'text', 'title', __( 'Title' ) ), Field::make( 'file', 'video', __( 'Video' ) ) ->set_value_type( 'url' ), ) )
Сложные поля могут быть вложенными
Ниже будет определен контейнер, который создает несколько слайдов и позволяет позиционировать несколько фрагментов текста на каждом слайде:
Container::make( 'post_meta', 'Slider Data' ) ->where( 'post_type', '=', 'post' ) ->add_fields( array( Field::make( 'complex', 'crb_slides' ) ->add_fields( array( Field::make( 'image', 'image' ), Field::make( 'complex', 'slide_fragments' ) ->add_fields( array( Field::make( 'text', 'fragment_text' ), Field::make( 'select', 'fragment_position' ) ->add_options( array( 'Top Left', 'Top Right', 'Bottom Left', 'Bottom Right' ) ), )) )), ));
Сложные значения полей извлекаются с помощью carbon_get_post_meta() или carbon_get_theme_option() (или другой функции извлечения, в зависимости от контейнера, в который она добавляется).
Формат возвращаемых данных представляет собой многомерный массив, как показано ниже:
array ( 0 => array ( 'photo' => 'http://example.com/lorem.jpg', 'people_on_photo' => array ( 0 => array ( 'name' => 'John', ), 1 => array ( 'name' => 'Karen', ), ) ), 1 => array ( 'photo' => 'http://example.com/ipsum.jpg', 'people_on_photo' => array ( 0 => array ( 'name' => 'Paul', ), 1 => array ( 'name' => 'Kasper', ), 2 => array ( 'name' => 'Julie', ), ) ), )
Добавление предопределенных сложных групп
Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'complex', 'crb_complex', 'My Complex Field' ) ->add_fields( array( Field::make( 'text', 'my_text_field', 'My Text Field' ) ) ) ->set_default_value( array( array( 'my_text_field' => 'Hello', ), array( 'my_text_field' => 'World!', ), ) ), ) );
Методы конфигурации
Для настройки и настройки сложного поля можно использовать следующие методы.
add_fields( $fields ) — этот метод идентичен методу Container add_fields, где $fields-это массив полей.
set_layout( $layout ) — макеты.
Есть 3 макета, доступные для отображения сложного поля:
grid (по умолчанию) — список сложных групп в виде сетки. Каждое поле в группе отображается в новой строке с первой меткой и элементами управления формы после нее
tabbed-horizontal-группы отображаются в виде горизонтальных вкладок
tabbed-vertical-группы отображаются в виде вертикальных вкладок
Для макетов с вкладками метка группы будет отображаться в навигации по вкладкам.
Макеты с вкладками предназначены для очистки пользовательского интерфейса от тяжелых страниц.
set_collapsed( $collapsed )Измените начальное состояние визуального сворачивания групп. Должно быть логическим. По умолчанию false.
set_min( $min ) Минимальное количество строк. Должно быть больше 0. По умолчанию -1 (без ограничений).
set_max( $max )Максимальное количество строк. Должно быть больше 0. По умолчанию -1 (без ограничений).
set_duplicate_groups_allowed( $allowed ) Укажите, следует ли разрешить пользователю создавать дубликаты групп. По умолчанию true.
setup_labels( $labels ) Позволяет коду клиента изменять метки для этого сложного поля. Принимаются следующие пункты:
plural_name — метка множественного числа. Значение по умолчанию — “ entries”.
singular_name — метка единственного числа. По умолчанию “entry”.
Пример использования:
use Carbon_Fields\Container; use Carbon_Fields\Field; $employees_labels = array( 'plural_name' => 'Employees', 'singular_name' => 'Employee', ); Container::make( 'post_meta', 'Дополнительные данные статьи' ) ->show_on_post_type( 'page' )// отобразим контейнер только на страницах (post_type = page) ->add_fields( array( Field::make( 'complex', 'crb_employee_data' ) ->setup_labels( $employees_labels ) ->add_fields( array( Field::make( 'text', 'name')->set_help_text('Name of employee' ), Field::make( 'text', 'position')->set_help_text('Position title' ), Field::make( 'image', 'image' ), Field::make( 'rich_text', 'description' ), ) ) ) );
Вывод значений комплексных полей
Создадим контейнер
Container::make( 'post_meta', 'Заметки автора статьи' ) ->show_on_post_type( 'page' )// отобразим контейнер только на страницах (post_type=page) ->add_fields( array( Field::make( 'complex', 'fio', 'Соавторы статьи' ) ->add_fields( array( Field::make( 'text', 'name', 'ФИО' ) ->set_width( 33 ), Field::make( 'text', 'spec', 'Специальность' ) ->set_width( 33 ), ) ) ->help_text( 'Перечислите всех, кто помогал Вам написать статью.' ) ) );
Посмотрим, как будет выглядеть массив данных. Для этого в шаблоне страницы в пропишем следующих код:
<?php $data = carbon_get_post_meta( get_the_ID(), 'fio' ); print_r( $data );?>
Получим:
Array ( [0] => Array ( [_type] => _ [name] => Иванов [spec] => машинист ) [1] => Array ( [_type] => _ [name] => Петров [spec] => пианист ) ).
Выведем полученные значения в таблице. Для этого в шаблоне страницы в пропишем следующих код:
$table = carbon_get_post_meta( get_the_ID(), 'fio' ); if ( ! empty( $table ) ): ?> <table> <thead> <tr> <th>ФИО</th> <th>Специальность</th> </tr> </thead> <tbody> <?php foreach ( $table as $tr ): ?> <tr> <td><?php echo $tr['name'] ?></td> <td><?php echo $tr['spec'] ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?php endif; ?>
Переходим на страницу и видим