Несмотря на всю шумиху, которую он вызвал в 2018 году, вам нужно быть отшельником (или, по крайней мере, кем-то, кто не работает в веб-разработке), чтобы не слышать о WordPress версии 5. Я, конечно, имею в виду ее игру. возможность изменения — новый блочный редактор Gutenberg. Новый редактор радикально меняет процесс написания в WordPress благодаря своей блочной системе. Авторы контента теперь могут относиться к редактированию контента с помощью подхода к созданию страниц, похожего на популярные конструкторы страниц, такие как Elementor и Divi.

Gutenberg по умолчанию поставляется с несколькими типами блоков, которые должны покрывать стандартные потребности в обновлении веб-контента. Тем не менее, у него также есть отличный Block API для добавления пользовательских типов блоков, если они вам нужны для отображения специально разработанных компонентов для нашего веб-сайта. В этом руководстве вы добавите пользовательский тип блока Gutenberg, чтобы на выходе было окно уведомления с несколькими предопределенными стилями, которое принимает произвольный ввод текста от пользователя.

Это то, к чему вы стремитесь.

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

А вот как это выглядит со стороны администратора.

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

Ладно, приступим к кодированию!

Шаг 1: Создайте плагин для нового типа блока

Вы будете создавать собственный тип блока в виде плагина WordPress. Это позволит вам отделить его от любых тем, которые вы используете, и в случае, если что-то пойдет не так, вы можете просто деактивировать его.

Итак, создайте новую папку в папке плагинов WP и назовите ее gutenberg-notice-block. В этой новой папке создайте файл plugin.php со следующим кодом:

/**
* Plugin Name: Gutenberg Notice Block
* Author: Shaiful
* Description: A notice box with a few predefined styles that accepts arbitrary text input.
* Version: 1.0
*/
// Load assets for wp-admin when editor is active
function shaiful_gutenberg_notice_block_admin() {
   wp_enqueue_script(
      'gutenberg-notice-block-editor',
      plugins_url( 'block.js', __FILE__ ),
      array( 'wp-blocks', 'wp-element' )
   );
wp_enqueue_style(
      'gutenberg-notice-block-editor',
      plugins_url( 'block.css', __FILE__ ),
      array()
   );
}
add_action( 'enqueue_block_editor_assets', 'shaiful_gutenberg_notice_block_admin' );
// Load assets for frontend
function shaiful_gutenberg_notice_block_frontend() {
wp_enqueue_style(
      'gutenberg-notice-block-editor',
      plugins_url( 'block.css', __FILE__ ),
      array()
   );
}
add_action( 'wp_enqueue_scripts', 'shaiful_gutenberg_notice_block_frontend' );

По сути, этот файл инициализирует плагин, загружая необходимые файлы JS и CSS в нужном месте и в нужное время. Приведенный выше код ищет block.js и block.css, которые вы сейчас создадите.

На этом этапе вы должны увидеть новый плагин, указанный на странице администратора WP Plugins. Идите вперед и активируйте его.

Двигаясь вперед, весь ваш код будет выполняться на JavaScript с некоторой разновидностью ReactJS для взаимодействия с API блоков Gutenberg.

Шаг 2: Зарегистрируйте новый тип блока

Создайте файл с именем block.js в папке вашего пользовательского плагина. Этот файл будет содержать всю логику пользовательского типа блока для административной части и внешнего интерфейса вашего веб-сайта.

Начните с добавления следующего базового кода.

var el = wp.element.createElement;
wp.blocks.registerBlockType('shaiful-gutenberg/notice-block', {
 title: 'Notice',  // Block name visible to user
 icon: 'lightbulb', // Toolbar icon can be either using WP Dashicons or custom SVG
 category: 'common', // Under which category the block would appear
 attributes: {   // The data this block will be storing
  type: { type: 'string', default: 'default' },   // Notice box type for loading the appropriate CSS class. Default class is 'default'.
  title: { type: 'string' },   // Notice box title in h4 tag
  content: { type: 'array', source: 'children', selector: 'p' }  /// Notice box content in p tag
 },
 edit: function(props) {
  // How our block renders in the editor in edit mode
 },
 save: function(props) {
  // How our block renders on the frontend  
 }
});

Приведенный выше код регистрирует ваш новый тип блока с именем Уведомление, используя лампочку Dashicon и помещая его под панель Общие блоки в браузере блоков Гутенберга. На этом этапе вы должны увидеть новый блок в своем редакторе.

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

Наконец, есть две функции, называемые edit() и save(). Функция edit () отвечает за рендеринг вашего блока в редакторе, а функция save () выводит HTML-код вашего блока на интерфейс нашего веб-сайта.

Давайте изучим их сейчас.

Шаг 3: Функция редактирования()

Функция edit() управляет тем, как блок будет отображаться в редакторе Гутенберга для взаимодействия с пользователем.

Для вашего пользовательского типа блока уведомлений цель состоит в том, чтобы выполнить две вещи:

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

Добавьте следующий код в функцию edit().

edit: function(props) {
   // How our block renders in the editor in edit mode
  
   function updateTitle( event ) {
      props.setAttributes( { title: event.target.value } );
   }
   function updateContent( newdata ) {
      props.setAttributes( { content: newdata } );
   }
   function updateType( event ) {
      props.setAttributes( { type: event.target.value } );
   }
   return el( 'div', 
      { 
         className: 'notice-box notice-' + props.attributes.type
      }, 
      el(
         'select', 
         {
            onChange: updateType,
            value: props.attributes.type,
         },
         el("option", {value: "default" }, "Default"),
         el("option", {value: "success" }, "Success"),
         el("option", {value: "danger" }, "Danger")
      ),
      el(
         'input', 
         {
            type: 'text', 
            placeholder: 'Enter title here...',
            value: props.attributes.title,
            onChange: updateTitle,
            style: { width: '100%' }
         }
      ),
      el(
         wp.editor.RichText,
         {
            tagName: 'p',
            onChange: updateContent,
            value: props.attributes.content,
            placeholder: 'Enter description here...'
         }
      )   
   ); // End return
}, // End edit()

Строка 16–49 — это основной код, который вы будете использовать для отображения пользовательского интерфейса таким образом, чтобы вы могли обновлять содержимое в вашем типе блока. Код написан на ReactJS, в частности функция React.createElement() используется для создания новых элементов DOM. Не волнуйтесь, если ReactJS вам незнаком. Вы можете использовать этот специальный инструмент для компиляции кода шаблона JSX в функции React.createElement().

Вот пример.

Рекомендуется создать файл block.css прямо сейчас, чтобы вы могли протестировать функцию предварительного просмотра в реальном времени в редакторе. Убедитесь, что файл CSS сохранен в папке вашего плагина.

div.notice-box {
   border: 1px LightSkyBlue solid;
   border-left-width: 5px;
   padding: 10px 15px;
   margin: 30px;
}
div.notice-box.notice-success {
   border-color: MediumSpringGreen ;
}
div.notice-box.notice-danger{
   border-color: LightCoral ;
}
div.notice-box h4 {
   font-size: 18px;
   margin:0 0 10px 0;
}
div.notice-box p {
   font-size: 16px;
   line-height: 24px;
   margin:0;
}

На этом этапе вы сможете добавить свой тип блока уведомлений в редактор и увидеть три разных поля для настройки окна уведомлений. Раскрывающийся список для выбора типа окна уведомления также должен давать вам предварительный просмотр в реальном времени между типами полей по умолчанию (синий), успех (зеленый) и опасность (красный).

Шаг 4: Функция save()

Функция save() для вашего типа блока уведомлений довольно проста. Вам просто нужно построить правильную структуру HTML и заполнить заголовок и содержание в поле уведомления <div>. И снова код создания DOM-элементов приходится писать на ReactJS.

Вот код:

save: function(props) {
   // How our block renders on the frontend
  
   return el( 'div', 
      { 
         className: 'notice-box notice-' + props.attributes.type
      }, 
      el(
         'h4', 
         null,
         props.attributes.title
      ),
      el( 
         wp.editor.RichText.Content, 
         {
            tagName: 'p',
            value: props.attributes.content
         }
      )
   
   ); // End return
     
} // End save()

Вот и все!

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

Вот ссылка для скачивания готового плагина.

Что нужно иметь в виду

Глядя на функцию save(), вы можете себе представить, что обновление вывода HTML приведет к глобальному обновлению всех экземпляров поля «Уведомление», которое вы заполнили на своем веб-сайте. Это естественно ожидать (по крайней мере, исходя из нашего опыта работы с шорткодами WP). К сожалению, этого не происходит.

Внесение любых изменений в вывод блока HTML приведет к конфликту со всеми существующими экземплярами заполненных блоков. Что еще хуже, единственный способ исправить это — повторно заполнить блоки один за другим. Это предостережение статических типов блоков.

Чтобы обойти это, используйте функцию Динамические блоки, которая передает функцию save() из JS в PHP для генерации блочного вывода HTML на лету.

Последние мысли

Возможность создавать пользовательские типы блоков очень крутая и открывает множество возможностей для настройки контента. Попробовав это на себе, я бы сказал, что основная концепция довольно проста для понимания. Однако реальная проблема заключается в том, чтобы представить пользовательский блок наилучшим образом, чтобы дать авторам контента лучший опыт редактирования, особенно для блоков со сложными функциями. Я обнаружил, что официальная документация разработчика для различных конфигураций атрибутов или работы, например, с полем RichText, все еще отсутствует. Это, безусловно, улучшится, но лучшие справочные материалы, которые у нас есть на данный момент, — это онлайн-статьи и существующие блоки, которые вышли из коробки с WP5.

С другой стороны, я лично с нетерпением жду, когда плагин Advanced Custom Fields (ACF) возьмет на себя типы настраиваемых блоков с их собственными ACF Blocks for Gutenberg. Это новое дополнение должно снизить барьер для разработчиков WP, чтобы использовать возможности блоков Gutenberg более интуитивно понятным способом.

Эта история была первоначально опубликована в Stampede Blog в феврале 2019 года.

О Stampede
Stampede, основанное в 2006 году, — это малайзийское креативное агентство, занимающееся пользовательским интерфейсом и цифровыми технологиями. Мы разрабатываем ориентированный на пользователя опыт и создаем цифровые продукты для бизнеса по всему миру. Узнайте больше о нас здесь.