WordPress как на ладони
wordpress jino

Carbon Fields — обзор плагина и начало работы

Carbon Fields - это библиотека (плагин) для удобного создания произвольных полей в административной части WordPress, а также вывода сохранённых данных во фронт-энде. Она позволяет разработчикам быстро добавлять новые поля для записей, таксономий, меню и так далее. Но всё это создаётся с помощью кода, потому данный плагин больше подходит для разработчиков.

Carbon Fields - плагин для создания произвольных полей в WordPress

При создании Carbon Fields были учтены недостатки и достоинства таких популярных плагинов, как Advanced Custom Fields и CMB2, а синтаксис создания полей позаимствован у Django Models.

Чтобы понимать по какому принципу работает Carbon Fields и вообще о чем идёт речь, читайте заметку о произвольных полях в WordPress. Эта библиотека (плагин) делает тоже самое, только в разы удобнее, плюс куча дополнительных возможностей.

Carbon Fields использует пространства имен PHP, а значит требует PHP 5.3+.

Carbon Fields можно скачать:

Принцип работы

Плагин рассчитан в первую очередь на разработчиков и не имеет визуального интерфейса. Все создается и работает через создание объектов и указания им параметров. Но не смотря на это, логика продумана и довольна удобна.

Основными компонентами библиотеки являются:

1. Container (контейнер) – группа полей

Создаем контейнер, то есть место, куда будут складываться поля. Создание контейнера в первую очередь определяет, где и как будут отображаться произвольные поля. Например, при создании контейнера указываем его тип - Post Meta. Теперь он будет отображаться только на странице редактирования Записи, если Term Meta - таксономии (рубрики, теги и т.п.). Carbon Fields имеет в своём составе контейнеры для всех возможных типов контента WordPress.

2. Field (поле) – одиночное поле

Создаем поля в выбранном контейнере. Каждое поле имеет свой внешний вид и предназначение. Carbon Fields предоставляет широкий выбор видов полей, покрывающих большинство задач при web-разработке. Это простые текстовые поля и области текста, поля для загрузки файлов или изображений, поля для выбора цвета или сайдбара и так далее - более 20 типов полей! Ко всему прочему, вы в праве создать своё уникальное поле!

3. Data Storage (хранилище) – базовое хранилище данных для значений полей

Вывод сохраненных данных в шаблоне темы или оперирование этими данными для реализации логики web-приложения.

Все данные хранятся как нативные данные WordPress: если это записи, то в таблице *_postmeta, комменты - *_commentmeta, термы - *_termmeta, пользователи - *_usermeta, ну и опции в таблице опций.

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

Пример

Большое количество примеров вы найдете на страницах описания контейнеров и полей, а сейчас небольшая демонстрация кода и результата работы Carbon Fields.

Страница настроек темы

Пример настроек темы

<?php
use Carbon_Fields\Container;
use Carbon_Fields\Field;

Container::make( 'theme_options', 'Пульт' )
		 ->add_tab( 'Наша команда', array(
			 Field::make( 'complex', 'crb_places', 'Список' )
				  ->add_fields( array(
					  Field::make( 'image', 'photo', 'Фото' )->set_value_type( 'url' )->set_width( 33 ),
					  Field::make( 'text', 'job', 'Должность' )->set_width( 33 ),
					  Field::make( 'text', 'fio', 'Фамилия, имя и отчество' )->set_width( 33 )
				  ) )
		 ) )
		 ->add_tab( 'Контакты', array(
			 Field::make( 'text', 'url_fb', 'Фейсбук' ),
			 Field::make( 'text', 'url_vk', 'вКонтакте' ),
			 Field::make( 'text', 'url_tw', 'Твиттер' ),
			 Field::make( "map", "crb_company_location", "Местоположение" )
				  ->help_text( 'Перетащите указатель на карту, чтобы выбрать местоположение' ),
		 ) )
		 ->add_tab( 'СЕО', array(
			 Field::make( 'text', 'title-lp', 'Title лендинга' ),
			 Field::make( 'text', 'description-lp', 'Description лендинга' ),
			 Field::make( "header_scripts", "header_google_analytics", 'Код счётчика Гугл.Аналитикс' ),
			 Field::make( "header_scripts", "header_script_yandex_metrika", 'Код счётчика Яндекс.Метрики' ),
		 ) );

Минимум кода - максимум возможностей! И пример отражает лишь их малую часть. Но даже тут уже видно как можно быстро создать блоки для комфортного управления сайтом. Подобные контейнеры можно создавать для различных типов записей, таксономий, меню, юзеров, опций и так далее - обо всех них поговорим в отдельной статье о контейнерах в Carbon Fields.

Установка и подключение Carbon Fields

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

На данный момент плагин имеет версию 1.6, а библиотека уже имеет версию 2. Это значит, что плагин отстаёт по функционалу от актуальной библиотеки. Так как Carbon Fields больше рассчитан для разработчиков, то в данных материалах будет рассматриваться библиотека.

Как Плагин

Плагин устанавливается из репозитория как обычно. Этот способ позволяет следить за обновлением библиотеки.

Но если отключить плагин, то все функции Carbon Fields, которые использовались в теме/плагине перестанут работать, поэтому, если устанавливается плагин, то в теме рекомендуется прописать «страховку» для функций библиотеки. Этот код сохранит работоспособность темы, если плагин отключить.

if ( ! function_exists( 'carbon_get_post_meta' ) ) {
	function carbon_get_post_meta( $id, $name, $type = null ) {
		return false;
	}   
}

if ( ! function_exists( 'carbon_get_the_post_meta' ) ) {
	function carbon_get_the_post_meta( $name, $type = null ) {
		return false;
	}   
}

if ( ! function_exists( 'carbon_get_theme_option' ) ) {
	function carbon_get_theme_option( $name, $type = null ) {
		return false;
	}   
}

if ( ! function_exists( 'carbon_get_term_meta' ) ) {
	function carbon_get_term_meta( $id, $name, $type = null ) {
		return false;
	}   
}

if ( ! function_exists( 'carbon_get_user_meta' ) ) {
	function carbon_get_user_meta( $id, $name, $type = null ) {
		return false;
	}   
}

if ( ! function_exists( 'carbon_get_comment_meta' ) ) {
	function carbon_get_comment_meta( $id, $name, $type = null ) {
		return false;
	}   
}

Как Библиотека

Этот способ лишает вас обновлений, но гарантирует неизменную работоспособность кода.

Установить Carbon Fields как библиотеку можно двумя методами.

Установка библиотеки с помощью composer

  1. Перейдите в каталог с темой/плагином.
  2. Выполните команду
composer require htmlburger/carbon-fields
  1. Добавьте в верхнюю часть вашего файла (functions.php - если тема, основной файл - если плагин) следующее:
use Carbon_Fields\Container;
use Carbon_Fields\Field;

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
	Container::make( 'theme_options', __( 'Theme Options', 'crb' ) )
		->add_fields( array(
			Field::make( 'text', 'crb_text', 'Text Field' ),
		) );
}

add_action( 'after_setup_theme', 'crb_load' );
function crb_load() {
	require_once( 'vendor/autoload.php' );
	\Carbon_Fields\Carbon_Fields::boot();
}

Данным кодом мы не просто подключили библиотеку, но и создали контейнер для опций темы (ради примера).

  1. Откройте свой сайт по ссылке /wp-admin/ - теперь у вас есть совершенно новый раздел «Параметры темы» с текстовым полем.

Без использования composer

Если вы не хотите использовать composer для установки Carbon Fields, вы также можете использовать один из готовых zip архивов, для этого:

  1. Скачайте архив библиотеки с последней версией или проследуйте на страницу с релизами Carbon Fields, выберите свежую версию и скачайте архив самостоятельно.
    2a. Установка как библиотека. Разархивируйте и поместите каталог carbon-fields в папку с темой/плагином и подключите файл carbon-fields-plugin.php.
    2b. Установка как плагин. Загрузите скачанный архив в разделе Плагины -> Установить новый -> Загрузить плагин и активируйте.
  2. Добавьте в верхнюю часть вашего файла (functions.php - если тема, основной файл - если плагин) следующее:
use Carbon_Fields\Container;
use Carbon_Fields\Field;

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
	Container::make( 'theme_options', __( 'Theme Options', 'crb' ) )
		->add_fields( array(
			Field::make( 'text', 'crb_text', 'Text Field' ),
		) );
}

add_action( 'after_setup_theme', 'crb_load' );
function crb_load() {
	require_once( 'vendor/autoload.php' );
	\Carbon_Fields\Carbon_Fields::boot();
}

Код очень похож на предыдущий.

  1. Откройте свой сайт по ссылке /wp-admin/ - теперь у вас есть совершенно новый раздел «Параметры темы» с текстовым полем.

В zip архивах используются классы PHP автозагрузчика Composer, но не требуется, чтобы у вас он был установлен.

Пользовательские файлы

Независимо от способа подключения библиотеки, нужно определить контейнеры с полями. Это можно сделать как в примерах выше, то есть сразу в функции или же подключить пользовательские файлы с определением полей.

Разработчики Carbon Fields рекомендуют использовать хук carbon_fields_register_fields. Например, код ниже можно разместить в теме (functions.php) или в коде плагина:

add_action( 'carbon_fields_register_fields', 'crb_register_custom_fields' );
function crb_register_custom_fields() {
	// путь к пользовательскому файлу определения поля (полей), измените под себя
	require_once __DIR__ . '/inc/custom-fields/post-meta.php';
}

В примере, post-meta.php - это файл (имя произвольное, как и путь к файлу), где вы можете создать свои собственные контейнеры с предпочтительными полями. Файлов может быть несколько, ограничений нет.

Любой пользовательский php файл с определением полей должен начинаться с конструкции

use Carbon_Fields\Container;
use Carbon_Fields\Field;

И только после неё описывать (создавать) произвольные поля.

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

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
function crb_attach_theme_options() {
	Container::make( 'theme_options', __( 'Theme Options', 'crb' ) )
		->add_fields( array(
			Field::make( 'text', 'crb_text', 'Text Field' ),
		) );
}

Переход с версии 1.6 на 2

Carbon Fields был значительно доработан. Изменения коснулись не только функционала, но и именования элементов библиотеки. В этом руководстве перечислено, что на что поменялось, что добавилось, что удалилось.

  • Все расширенные поля должны быть переработаны.
  • Carbon Fields теперь вызывается так \Carbon_Fields\Carbon_Fields::boot();, а лучшее место для вызова хук hook_after_setup_theme. Смотрите примеры выше в разделе подключения.
  • Предупреждение: контейнеры theme_options теперь доступны только пользователям с правами manage_options и выше. Чтобы отключить это поведение, чтобы разрешить условия пользовательской возможности, используйте фильтр carbon_fields_theme_options_container_admin_only_access.

Переименованные и обновленные экшены

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

carbon_after_save_custom_fields
carbon_fields_post_meta_container_saved
crb_container_activated
carbon_fields_container_activated
crb_field_activated
carbon_fields_field_activated
carbon_after_save_nav_menu_item
carbon_fields_nav_menu_item_container_saved
carbon_after_save_post_meta
carbon_fields_post_meta_container_saved
carbon_after_save_term_meta
carbon_fields_term_meta_container_saved
carbon_after_save_theme_options
carbon_fields_theme_options_container_saved
carbon_after_save_user_meta
carbon_fields_user_meta_container_saved
carbon_association_options_{field_name}_{type}_{subtype}
carbon_fields_association_field_options_{field_name}_{type}_{subtype}
carbon_after_register_fields
carbon_fields_fields_registered
carbon_register_fields
carbon_fields_register_fields

Переименованные и обновленные фильтры

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

carbon_template
Фильтр удален и не имеет замены.
carbon_relationship_options_*
carbon_fields_association_field_options_{name}_{type} или carbon_fields_association_field_options_{name}_{type}_{subtype} в зависимости от условий
crb_gravity_form_options
carbon_fields_gravity_form_options
carbon_association_comment_length
carbon_fields_association_field_comment_length
carbon_association_title
carbon_fields_association_field_title
carbon_association_item_label
carbon_fields_association_field_item_label
carbon_association_options
carbon_fields_association_field_options
carbon_{container_title}_button_label
carbon_fields_{container_title}_button_label
carbon_relationship_title
carbon_fields_association_field_title
carbon_relationship_item_label
carbon_fields_association_field_item_label
carbon_relationship_comment_length
carbon_fields_association_field_comment_length
carbon_relationship_options
carbon_fields_association_field_options
carbon_map_api_key
carbon_fields_map_field_api_key
carbon_map_url
carbon_fields_map_field_api_url
carbon_custom_sidebar_default_options
carbon_fields_sidebar_default_options
carbon_custom_sidebar_options
carbon_fields_sidebar_options
carbon_custom_sidebars
carbon_fields_sidebars
campusboy 1946youtube.com/c/wpplus
WordPress-разработчик. Разработка сайтов и лендингов. Доработка существующих проектов. Сопровождение ресурсов.
Carbon Fields - обзор плагина и начало работы 77 комментариев
Полезные 2 Вопросы 2 Все
  • Артем cайт: entropiya-blog.ru

    Сделал по примеру. Ошибок нет, но и дополнительные поля не появились. Устанавливал плагин через репозиторий.

    Мои действия

    1. Установил через репозиторий плагин
    2. В файле темы function.php указал условия, которые были описаны в статье
    3. Поставил хук и функцию на подключение post-meta.php
    4. В файле моя_темы/inc/custom-fields/post-meta.php' прописал код, который указан в примере. И нечего не работает. Не могу понять, что сделал не так.
    1
    Ответить3 месяца назад #
    • campusboy1946 cайт: www.youtube.com/c/wpplus

      Привет. В репозитории теперь 2 версия этой библиотеки и она подключается иначе, оф. документация. Обновить эту статью времени не хватает.

      Ответить3 месяца назад #
      • Артем cайт: entropiya-blog.ru

        Привет. Спасибо за ответ. Буду смотреть.

        Ответить3 месяца назад #
  • Dimox

    Поставил сегодня Carbon Fields 2.0.4 и обнаружил, что некоторые строки не русифицировались, хотя перевод есть в файле carbon-fields-ru_RU.po. Например, у комплексного поля вот так:

    Кто-нибудь столкнулся с этим же?

    Ответить3 месяца назад #
    • campusboy1946 cайт: www.youtube.com/c/wpplus

      У меня та же проблема. Может потому что строки не 1 к 1? Во всяком случае какими бы я их одинаковыми ни делал - всё равно не переводится. Пока не пойму в чем дело.

      Ответить3 месяца назад #
      • campusboy1946 cайт: www.youtube.com/c/wpplus

        Вопрос решен. На скришоте выше видно, что у фразы стоит метка fuzzy, то есть "Перевод требует проверки" и в POedit такие фразы выделены оранжевым цветом и имеют специальную кнопку при выделении:

        Такие фразы при компилировании в MO не учитываются. Если убрать проверку и сохранить, то всё нормально становится. Но не в описанном случае. Программа ругается, так как в исходной фразе есть "переменная" %s, а в переводе её нет, что, по её словам, может привести к проблемам при отображении в теме/плагине, но всё равно сохраняет. В нашем случае, я проигнорировал ошибку, проверил - фраза перевелась и ошибок нет. Но затем для подстраховки сделал как надо, а именно вот так:

        %s пока нет. Нажмите <a href="#">здесь</a>, чтобы добавить первый элемент.

        Ну и полю указал метод с параметрами:

        ->setup_labels( [
        	'plural_name'   => 'Отделов',
        	'singular_name' => 'ещё отдел',
        ] )

        Получил:

        Конечно, фразу переводов можно подогнать под другой формат, чтобы не зависело от склонения или численности. Это как пример.

        Итог

        • Обращайте внимание на метку fuzzy.
        • Используйте метод setup_labels() у комплексного поля, чтобы задать индивидуальные лейблы при надобности.
        2
        Ответить3 месяца назад #
        • Dimox

          Спасибо за полезную информацию!

          То есть, получается, что придется самому редактировать po-файл? Может быть стоит написать разработчикам issue по этому поводу?

          Ответить3 месяца назад #
          • campusboy1946 cайт: www.youtube.com/c/wpplus

            Пожалуйста. А что я им скажу? Перевод есть, просто помечен, как "не проверен". Я думаю у них других проблем пока первоочередных хватает.

            придется самому редактировать po-файл?

            Не вижу как бы проблем с этим smile У меня это заняло ну минуту где-то, не больше.

            Ответить3 месяца назад #
            • Dimox

              А что я им скажу?

              Я бы и сам написал, но тоже не знаю, что именно.

              Не вижу как бы проблем с этим

              Отредактировать не сложно, просто это придется делать, возможно, при каждом обновлении библиотеки. В этом и неудобство.

              Ответить3 месяца назад #
              • campusboy1946 cайт: www.youtube.com/c/wpplus

                Отредактировать не сложно, просто это придется делать, возможно, при каждом обновлении библиотеки.

                Да можно пул реквест сделать и всё - они его примут и порядок. Я пока этого не делаю, что дел по горло. Как разгребусь, можно будет попушить и покоммитить вдоволь smile Не паханное поле.

                Ответить3 месяца назад #
  • Евгений

    Подскажите пожалуйста можно ли сделать галерею как в ACF?
    Ну или просто мульти выбор изображений?

    P.S. это было бы удобно для реализации галереи.

    Ответить3 месяца назад #
    • campusboy1946 cайт: www.youtube.com/c/wpplus

      Приветствую. Можно сделать через комплексные поля, что да - не очень удобно под это. Разработчики, судя по issue на github, в будущих обновлениях добавят это поле.

      2
      Ответить3 месяца назад #
  • Roman523 cайт: forweb52.ru

    Приветствую!
    Ставлю последнюю версию как не плагин.
    Скачиваю тут carbonfields.net/release-archive ( по инструкции carbonfields.net/docs/carbon-fields-quickstart/?crb_version=2-0-0 )
    В итоге папка весит 4.3 мб. Что можно поудалять такого не нужного, чтобы все это дело весило поменьше?
    Если скачивать плагин например с оф сайта wp, то он весит 1 мб.
    А тут библиотека почему то больше весит.

    Ответить2 месяца назад #
    • campusboy1946 cайт: www.youtube.com/c/wpplus

      Привет. Потому что в репозитории плагин основан на версии 1.6, а библиотека уже стала версии 2.0.

      Если отвечать прямо на вопрос, то я не заметил там чего-то лишнего и не экспериментировал с удалением чего-либо. Даже не особо представляю, зачем это может понадобиться. Самым большим файлом является carbon.vendor.js - 2Мб.

      1
      Ответить2 месяца назад #
      • Roman523 cайт: forweb52.ru

        Окей, понял, спасибо за ответ.
        Просто я подумал, может я чего то не понял при подключении, или чего не то скачал, если библиотека весит в 4 раза больше чем плагин scratch_one-s_head . А оказывается, что там старая версия плагина.

        Ответить2 месяца назад #
    • Dimox

      Я задался тем же вопросом, когда установил данную версию, так как для меня это важно. И даже спросил у разработчиков.

      В итоге удалил следующее:

      1) Из папки \carbon-fields\vendor\htmlburger\carbon-fields\assets\dist\ эти файлы:

      carbon.boot.js
      carbon.core.js
      carbon.vendor.js
      carbon.core.json
      carbon.core.min.json
      carbon.vendor.json
      carbon.vendor.min.json

      2) Из папки \carbon-fields\vendor\htmlburger\carbon-fields\ эти:

      .babelrc
      postcss.config.js
      webpack.base.js
      webpack.boot.js
      webpack.core.js
      webpack.vendor.js
      composer.json
      package.json
      package-lock.json
      README.md
      license.txt

      То есть все, кроме файла config.php.

      3) Из папки \carbon-fields\vendor\htmlburger\carbon-fields\languages\ все, кроме RU.

      В результате вес уменьшился примерно на 3.1 мегабайта.

      3
      Ответить2 месяца назад #
  • Приветствую!
    Подскажите, поставил библиотеку 2.
    Всё работает. Не получается подключить пользовательские файлы.
    Подключаю как показано, меняя директорию на свою, сайт выпадает в 500 ошибку и всё.
    Файл положил в папку темы. Подключаю в functions.php :

    add_action( 'carbon_fields_register_fields', 'crb_register_custom_fields' );
    function crb_register_custom_fields() {
    	// путь к пользовательскому файлу определения поля (полей), измените под себя
    	require_once __DIR__ . 'post_meta.php';
    }

    В post_meta.php

    <?php
    use Carbon_Fields\Container;
    use Carbon_Fields\Field;
    
    Container::make('post_meta', 'Настройки постов')
      ->show_on_post_type('page')
    	->add_fields(array(
    		Field::make('text', 'testtext1', 'Тестовое поле 1'),
    		Field::make('text', 'testtext2', 'Тестовое поле 2'),
    	));
    ?>

    Подскажите,пожалуйста, в чём ошибка?

    Ответить23 дня назад #
    • campusboy1946 cайт: www.youtube.com/c/wpplus

      Привет. Включи дебаг и смотри, какую ошибку выдаёт - это же просто определить. Как подключал саму библиотеку? Там 2 версия подключается по другому чутка, чем 1.6

      1
      Ответить23 дня назад #
      • Подключал:

        1. Скачал последнюю версию и залил папку в папку темы.
        2. в functions.php
        /* подключаем библиотеку Carbon_Fields */
        use Carbon_Fields\Container;
        use Carbon_Fields\Field;
        
        add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );
        function crb_attach_theme_options() {
        	Container::make( 'theme_options', __( 'Theme Options', 'crb' ) )
        		->add_fields( array(
        			Field::make( 'text', 'crb_text', 'Text Field' ),
        		) );
        }
        
        add_action( 'after_setup_theme', 'crb_load' );
        function crb_load() {
        	require_once( 'carbon-fields/vendor/autoload.php' );
        	\Carbon_Fields\Carbon_Fields::boot();
        }

        Сейчас разберусь и включу дебаг.) Спасибо!
        Сообщения об ответе и новых комментариях почему-то не пришло. Или может ещё придёт.

        Ответить23 дня назад #
        • campusboy1946 cайт: www.youtube.com/c/wpplus

          Путь довольно интересный в require_once smile надеюсь он реально такой

          1
          Ответить23 дня назад #
          • папка carbon-fields лежит в папке темы.
            .../themes/my_theme/carbon-fields/

            Всё заработало. @campusboy, спасибо!
            Открыл для меня такую хорошую штуку как дебаг.)
            Там слеша не хватало перед файлом, то видимо кодировка слетала, то подключал дефолтный файл, в котором не убирал первую строку.
            Всё получилось. Буду разбираться дальше.)
            Спасибо сайту, автору и активным пользователям!)

            Ответить23 дня назад #

Здравствуйте, !

Ваш комментарий