Хей, имам нещо специално за теб!
Попълни имейл адрес, на който до минута ще получиш обещаното ;)
Създаване на Gutenberg блокове с Advanced Custom Fields
Научи как да създаваш нови Gutenberg блокове с помощта на Advanced Custom Fields.
Disclaimer: информацията в този урок изисква Advanced Custom Fields PRO плъгин
Какво е Gutenberg?
След официалното си представяне във версия 5.0 на WordPress през 2018, Gutenberg редактора (кръстен на Йоханес Гутенберг) се развива ежедневно и ако допреди 4 години е бил просто „по-fancy“ начин за създаване и публикуване на съдържание, то днес е инструмент за модулно съдържание, full site editing experience и още. Благодарение на модулната си природа, Gutenberg дава възможност на разработчиците да са максимално гъвкави, когато говорим за персонализирани решения.
Повече за проектът може да видиш и научиш на официалната страница тук.
Какво представляват блоковете на Gutenberg?
Gutenberg блоковете представляват модули с най-различни предназначение и употреба – от текстови редактор, през слайдер, до изглед на WooCommerce продукт. Така казано, за потребителя тип редактор това са блокове, посредством които се създава изглед на съдържанието в уеб сайта. От гледната точка на разработчика, обаче, това са React базирани блокове, за чието създаване и надграждане са необходими солидни JavaScript познания.
Какво обаче ако искаш да имаш възможността за по-персонализирани решения по отношение на блокове и гъвкавост на темата, но същевременно React не е най-голямата ти сила?
Точно тук идва ACF (Advanced Custom Fields) плъгина, посредством който на чист PHP можеш да създаваш блокове from scratch.
Advanced Custom Fields – какво е?
Докато WordPress няма възможност за добавяне на потребителски полета, решението, което от ACF – freemium плъгин, предоставят, ни дава възможност да сериозно да надградим дадената WP инсталация и да я превърнем в изцяло индивидуален CMS.
➡️ Какво прави ACF?
В едно изречение – дава възможност за добавяне на потребителски полета за съдържание в страници, публикации, менюта и, както ще видим – в Gutenberg блокове.
➡️ Какво са потребителските полета?
Това са полета, чрез които съхраняваме информация от под формата на metafields. Дори никога да не си чувал за такива полета, вероятността да си се сблъсквал със същите е огромна, тъй като множество теми и плъгини работят именно с тях. Продуктът в WooCommerce и по-конкретно – неговите данни (цена, допълнителна информация) са все потребителски полета.
Ако, да речем, правиш ревюта на филми в сайта си, и искаш да имаш поле за добавяне на рейтинг в администрацията, чиято стойност да се визуализира в публичната част, то ACF е решение, с което бързо и без много промени ще постигнеш целта.
➡️ Как да създадеш потребителско поле?
Първо е необходимо да инсталираш плъгина на Advanced Custom Fields, като безплатната му версия дава не малък брой възможности.
За да създадеш ново потребителско поле, навигирай до менюто на ACF, след което избери Create new field group и избери какъв тип искаш да е полето (text, number, link, image…).
Важно уточнение тук е, че можеш да задаваш за кои post type-ове, страници или блокове, както ще видим, да се появява това поле.
За да асоциираш новосъздаденото поле със съществуващ елемент от front-end-а на уеб сайта, е нужно да го „повикаш“ с ACF функцията get_field(); :
<h2 class="blue-text txt-size-20"> <?php get_field('heading_text'); ?> </h2>Така, например, ако приемем, че в single.php файла на темата ти искаш да имаш полето с рейтинг, за което споменах по-горе, то файлът ти би изглеждал по този начин:
<?php get_header(); ?>
<div class="article-wrapper">
<article>
<h1> <?php echo the_title(); ?> </h1>
<?php the_content(); ?>
<p class="rating"> <?php get_field('rating'); ?> </p>
</article>
</div>
<?php get_footer(); ?>Регистриране на нов Gutenberg блок с ACF
След като вече знаеш основната концепция на ACF и как можеш да направиш темата си още по-функционална и гъвкава, е време да ти покажа и как да регистрираш първият си Gutenberg блок, който ще бъде „захранван“ от ACF.
Disclaimer: за да регистрираш блок с ACF е необходимо да имаш PRO версията на плъгина.
➡️ acf_register_block_type();
Първата стъпка към регистриране на нов Gutenberg блок посредством ACF е да използваш функцията acf_register_block_type();. За да го направиш, отиди във functions.php файла (или файлът, в който „живеят“ всички функции на темата ти) и инициализирай функцията за добавяне на блокове. Ето и как изглежда тя, заедно с няколко аргумента:
add_action('acf/init', 'my_acf_blocks_init');
function my_acf_blocks_init() {
// Check function exists.
if( function_exists('acf_register_block_type') ) {
// Register a testimonial block.
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Testimonial'),
'description' => __('A custom testimonial block.'),
'render_template' => 'template-parts/blocks/testimonial/testimonial.php',
'category' => 'formatting',
));
}
}В примерът горе регистрираме блок с име Testimonial, който има темплейт, намиращ се в папка template-parts/blocks/testimonial. Добавени са и аргументи за описание и категория. Освен тези аргументи, можем да добавим и:
- icon – с този аргумент добавяме иконка към блока, което ще го направи по-лесен за разпознаване при работа с редактора. Иконките се зареждат от Dashicons или от персонално svg.
// Specifying a dashicon for the block
'icon' => 'book-alt',
// Specifying a custom HTML svg for the block
'icon' => '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>',
// Specifying colors
'icon' => array(
// Specifying a background color to appear with the icon e.g.: in the inserter.
'background' => '#7e70af',
// Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
'foreground' => '#fff',
// Specifying a dashicon for the block
'src' => 'book-alt',
),- keywords – масив от ключови думи, с чиято помощ потребителя ще намира блока по-лесно –
'keywords' => array('quote', 'testimonial', 'opinion', 'client'), - post_types – масив от post type-ове, за които искаш да се появява този блок (тоест да е ограничен по тип пост) –
'post_types' => array('post', 'page'), - mode – начинът, по който се появява блокът в администарция. Възможните стойности тук са
auto,previewиedit. Preview режимът е по подразбиране, но се променя на edit, когато блокът е селектиран –'mode' => 'auto', - align – подравняването по подразбиране на блока. Възможните стойности са
left,center,right,wideиfull–'align' => 'full', - align_text – подравняването по подразниране на текстовото съдържание в блока. Възможните стойности са
left,centerиright–'align_text' => 'center', - render_template – с този аргумент указваме пътя до директорията, където се съхранява php файлът със сорс кода на блока, като пътя може да е релативен –
'render_template' => 'template-parts/blocks/testimonial/testimonial.php',или абсолютен –'render_template' => plugin_dir_path( FILE ) . 'template-parts/blocks/testimonial/testimonial.php', - render_callback – вместо да подаваме път към директория, в която се съхранява темплейта на блока, с render_callback може да подадем callback функция –
'render_callback' => 'my_acf_block_render_callback', - enqueue_style – път към директория, в която има .css файл, който да бъде извикан, когато блокът се използва –
'enqueue_style' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css', - enqueue_script – път към директория, в която има .js файл, който да бъде извикан, когато блокът се използва –
'enqueue_style' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js, - enqueue_assets – callback функция, която се изпълнява ако блокът е повикан, зарежда скриптове и стилове:
// Specifying a function name
'enqueue_assets' => 'my_acf_block_enqueue_assets',
// Specifying a class method
'enqueue_assets' => array($this, 'block_enqueue_assets'),
// Specifying an anonymous function
'enqueue_assets' => function(){
wp_enqueue_style( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css' );
wp_enqueue_script( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js', array('jquery'), '', true );
},- example – списък от структурирани данни, чрез който може да добавиш preview на блока (при hover):
'example' => array(
'attributes' => array(
'mode' => 'preview',
'data' => array(
'testimonial' => "Your testimonial text here",
'author' => "John Smith"
)
)
)➡️ Създаване на темплейт за новият блок
След като вече имаме основните аргументи, които могат да бъдат подадени на един блок, нека видим и как да създадем темплейт за него.
Първото нещо, което е необходимо да направиш, е да създадеш нова папка в основната директория на темата, която разработваш (или доработваш). Може да я наречеш blocks с цел по-лесно ориентиране за в бъдеще.
Следващото нещо, което е необходимо да направиш, е да създадеш подпапка (не е задължително) с името на блока, който предстои да създадеш, а в нея – php файл, отново с името на блока. В случая пътя към нашия блок би изглеждал така: blocks/testimonial/testimonial.php
По-горе ти показах как да го регистрираш във functions.php файла, но ще го направя и тук:
// ACF Gutenberg blocks
add_action('acf/init', 'my_acf_blocks_init');
function my_acf_blocks_init() {
// Check function exists.
if ( function_exists('acf_register_block_type') ) {
// Register a testimonial block.
acf_register_block_type(array(
'name' => 'testimonial',
'title' => __('Testimonial'),
'description' => __('A custom testimonial block.'),
'render_template' => 'blocks/testimonial/testimonial.php',
'category' => 'formatting',
));
}
}В новосъздадения testimonial.php файл ще „живее“ кода (markup-a) за самия блок, най-често това е обикновен HTML (когато говорим за класически теми). В примера по-долу съм добавила заглавие, текст и име на автор, като всичко към този момент е статично:
<?php /* block markup */ ?>
<div class="testimonial-wrapper">
<h4>Highlighted text from the author</h4>
<p>Testimonial itself: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iure, vero. Placeat officiis est quae animi voluptas repudiandae quibusdam, dolorem culpa, incidunt tempora possimus molestias dolore accusantium vitae exercitationem quo commodi ipsa cum quidem ratione. Consequatur neque beatae, tenetur iure quae accusantium sed unde illum totam? Facere enim neque laboriosam reiciendis?</p>
<p>Name of the author</p>
</div>Така създаден, блокът може да се извиква във всяка публикация и страница (тъй като не сме го ограничили). Съдържанието в него, обаче, все още е статично и всеки път, когато го повикаме ще ни показва едно и също:
➡️ Създаване на нова група полета в ACF
За да направиш блокът динамичен и да имаш уникално съдържание всеки път, е необходимо да използваш ACF и по-конкретно – създаване на група полета, които да се прилагат към блок.
За целта, навигирай до ACF менюто в администрацията на темата и започни да създаваш нова група.
Hint: използвай името на блока като име на групата, така ще ти бъде по-лесно да нанасяш корекции в бъдеще
В testimonial блока, който създадохме, имаме три полета, за кито имаме необходимост да съдържат динамична информация: заглавие, текстово поле и име на автор. И трите могат да бъдат обикновени text полета, но в случай, че потребителя желае да форматира текстът, това няма да е възможно, за това и за основния testimonial text ще избера WYSIWYG field.
Важно: след като създадеш полетата, най-долу избери да са валидни за Block и по-конкретнo Testimonial
➡️ Асоцииране на ACF полетата с блока
Последната стъпка към създаването на персонализиран Gutenberg блок с помощта на ACF е да асоциираш създадените полета в ACF групата с testimonial.php файла. За да се случи това, е необходимо да използваш функцията get_field();, като за параметър подаваме label-a на полето. В случая ние имаме три полета и ето как биха изглеждали те в testimonial.php markup-a:
<?php /* block markup with ACF fields */ ?>
<div class="testimonial-wrapper">
<h4><?= get_field('heading'); ?></h4>
<p><?= get_field('main_text'); ?></p>
<p><?= get_field('testimonial_author'); ?></p>
</div>Сега, в администрацията и по-конкретно когато извикаме блока, ще се зареждат полета за писане, вместо hard code-натия текст, който виждахме преди малко:
Заключение
Gutenberg става все по-мощен и функционален, давайки възможност на разработчиците да постигат зададени цели с гъвкавост и лекота. В статията разгледахме един от начините за създаване на Gutenberg блокове, като примерите са значително прости с цел лесно възприемане.
В действителност с ACF могат да се постигнат забележителни резултати и персонализация в лицето на редактор, изцяло съобразен с UX/UI дизайна на темата.
Stay blond 😉
