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, выберите свежую версию и скачайте архив самостоятельно.
  2. Разархивируйте и поместите в каталог carbon-fields в папке с темой/плагином.
  3. Добавьте в верхнюю часть вашего файла (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' ),
		) );
}
campusboy 1832wp-plus.ru
WordPress-разработчик. Разработка сайтов и лендингов. Доработка существующих проектов. Сопровождение ресурсов.
Carbon Fields - обзор плагина и начало работы 72 комментария
Полезные 2 Вопросы 2 Все
  • Артем cайт: entropiya-blog.ru @

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

    Мои действия

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

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

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

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

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

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

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

    Ответитьмесяц назад #
    • campusboy1832 cайт: wp-plus.ru

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

      Ответитьмесяц назад #
      • campusboy1832 cайт: wp-plus.ru

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

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

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

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

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

        Получил:

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

        Итог

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

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

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

          Ответить29 дней назад #
          • campusboy1832 cайт: wp-plus.ru

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

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

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

            Ответить29 дней назад #
            • Dimox

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

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

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

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

              Ответить29 дней назад #
              • campusboy1832 cайт: wp-plus.ru

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

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

                Ответить29 дней назад #
  • Евгений

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

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

    Ответитьмесяц назад #
    • campusboy1832 cайт: wp-plus.ru

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

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

        Спасибо. Вот уже есть исходник Carbon Fields Gallery Field, но пока не тестил

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

          Что то у меня при подключении ругается, что нет метода add_template Может это не к 2 версии?

          Ответить19 дней назад #
  • Roman523 cайт: forweb52.ru

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

    Ответить23 дня назад #
    • campusboy1832 cайт: wp-plus.ru

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

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

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

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

        Ответить23 дня назад #
    • 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
      Ответить23 дня назад #

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

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