Strona główna / Wtyczki do Wordpressa / Jak stworzyć dodatkowy blok do Gutenberga z Advanced Custom Fields PRO?

Jak stworzyć dodatkowy blok do Gutenberga z Advanced Custom Fields PRO?

Jeżeli trafiłeś tutaj to z pewnością zastanawiałeś się nad tym czy można utworzyć niestandardowy, dodatkowy blok do Gutenberga. Na ostatnim WordCampie w Łodzi miałem okazję przedstawić prelekcję na ten temat. W tym wpisie zamieściłem pełne podsumowanie prezentacji „Jak stworzyć dodatkowe bloki do Gutenberga z Advanced Custom Fields PRO?”.

Z wpisu dowiesz się między innymi o tym:

Czym jest Advanced Custom Fields?

Zacznijmy od podstaw! Advanced Custom Fields to wtyczka, która pozwala w prosty sposób dodać dodatkowe pola do ekranów edycji. Na przykład dla wpisów, podstron, kategorii czy widżetów. Dzięki specjalnym funkcjom wtyczki ACF w prosty sposób odczytamy wartości tych pól w motywie.

Możliwe lokacje pól

  • Wpis
    • Typ wpisu
    • Szablon wpisu
    • Status wpisu
    • Format wpisu
    • Kategoria wpisu
    • Taksonomia wpisu
    • Wpis
  • Strona
    • Szablon strony
    • Typ strony
    • Rodzic strony
    • Strona
  • Użytkownik
    • Bieżący użytkownik
    • Rola bieżącego użytkownika
    • Formularz użytkownika
    • Rola użytkownika
  • Formularze
    • Taksonomia
    • Załącznik
    • Komentarz
    • Widżet
    • Menu
    • Element menu

Możliwe typy pól

  • Podstawowe
    • Tekst
    • Obszar tekstowy
    • Liczba
    • Zakres
    • E-mail
    • Url
    • Hasło
  • Treść
    • Obraz
    • Plik
    • Edytor WISIWYG
    • oEmbed
    • Galeria
  • Wybór
    • Wybór
    • Wybór (checkbox)
    • Przycisk opcji (radio)
    • Grupa przycisków
    • Prawda/Fałsz
  • Relacyjne
    • Link
    • Obiekt wpisu
    • Link do strony
    • Relacja
    • Taksonomia
    • Użytkownik
  • jQuery
    • Mapa Google
    • Wybór daty
    • Wybieranie daty i godziny
    • Wybór koloru
  • Układ
    • Wiadomość
    • Zwijane panele
    • Grupa
    • Zakładka

Przykład użycia Advanced Custom Fields

Dobrym przykładem wykorzystania podstawowej wersji Advanced Custom Fields może być pole z informacją o tym, jak długo zajmie czytanie wpisu na blogu. Poniżej znajdziesz instrukcję, dzięki której w czterech krokach umieścisz informację na swoim blogu.

Krok 1

Zastanów się nad tym jakich pól potrzebujemy. W tym przypadku, jedyną zmienną jest czas czytania. Możemy do tego użyć pola liczba (np. „5”) lub pole tekstowe (np. „5 min”). W tym celu musimy dodać nową grupę pól w panelu Advanced Custom Fields, którą znajdziemy w menu pod etykietą „Własne Pola”.

Grupę pól nazwałem „Fields: Post”, tak by jasno wskazywała czego dana grupa pól dotyczy. Następnie, powinniśmy dodać pole o nazwie „reading_time”, z etykietą „Czas czytania”. Informacji dotyczącej czasu czytania nie potrzebujemy jednak na podstronach. Dlatego, po utworzeniu danych pól musimy przypisać jej do konkretnej lokacji, czyli do wpisów.

Krok 2

Przejdźmy do widoku edycji jednego z naszych wpisów. Pod każdym wpisem powinno pojawić się pole z etykietą „Czas czytania”.

Krok 3

To jednak jeszcze nie wszystko. Po dodaniu pól w panelu administracyjnym musimy odczytać wartości pól w motywie.

Jeżeli edytujesz istniejący już motyw – utwórz motyw potomny. Potem należy odnaleźć szablon wpisu. Powinieneś go znaleźć w motywie pod nazwą single.php.

Do wyświetlenia wartości pól w Advanced Custom Fields możemy skorzystać z dwóch funkcji:

  • get_field() – funkcja pozwalająca na odczytanie wartości danego pola,
  • the_field() – funkcja pozwalająca na wyświetlenie wartości danego pola.
<?php if( get_field('reading_time') != "" ):?>
        <div>
            <img data-src="<?php bloginfo('template_directory');?>/dist/svg/reading-time.svg" class="lazy" alt="Ikona czas" />
            <span><?php the_field('reading_time');?> czytania</span>
        </div>
<?php endif;?>

Co oferuje Advanced Custom Fields w wersji PRO?

Advanced Custom Fields PRO możemy zakupić na stronie wtyczki. Warto się śpieszyć, gdyż autorzy zapowiedzieli przejście na model subskrypcyjny od 2020 roku. W tej chwili (grudzień 2019) wtyczkę możemy zakupić za 200 dolarów australijskich (AUD).

Wersja PRO od wersji podstawowej różni się:

  • Dodatkowymi polami:
    • Pole powtarzalne,
    • Elastyczna treść,
    • Klon,
  • Dodatkowymi lokacjami
    • Strona opcji,
    • Blok edytora Gutenberg.

Jakie są zalety tworzenia niestandardowych bloków do Gutenberga z ACF PRO?

Pod hasłem „Gutenberg Block” w repozytorium odnajdziemy szereg wtyczek, które oferują nam dodanie dodatkowych bloków. Przykładem takiego bloku może być wtyczka wyświetlająca opinie na naszej stronie internetowej. Pokażę Ci, dlaczego ACF PRO ma przewagę nad wtyczkami podobnego typu.

  • Niezależność – W przypadku wielu wtyczek oferujących bloki jesteśmy uzależnieni od ich twórców. Nasze prośby dotyczące zmian nie zawsze mogą zostać spełnione.
  • Wydajność – Kod jest dostosowany do naszych potrzeb, a nie wszystkich użytkowników wtyczki. Nie zawiera on więc zbędnego kodu CSS, JS którego nie potrzebujemy. O tym, dlaczego warto dbać o prędkość strony internetowej możesz przeczytać we wpisie – „Dlaczego wersja mobilna strony internetowej jest ważna?”.
  • Prostota użycia – Jeżeli znasz podstawy HTML, CSS oraz nie boisz się plików PHP powinieneś dać sobie radę!
  • Ogranicza nas tylko wyobraźnia – Możemy stworzyć blok, którego na dobrą sprawę jeszcze nikt nie wymyślił!

Jak utworzyć dodatkowy blok do Gutenberga w siedmiu krokach

Przejdźmy do siedmiu kroków, dzięki którym utworzymy podobny blok do poniższego.

Wskazówka

Funkcja the_field() to tak naprawdę to samo co echo get_field()

To blok „wskazówki”, który wykorzystuję do moich wpisów na blogu. Od początku było istotne dla mnie to, by mieć dostęp do zmiany: ikony, tytułu oraz treści wskazówki. Ta informacja, przyda nam się w kolejnych krokach.

Krok 1

Na samym początku musimy zarejestrować blok za pomocą funkcji acf_register_block(). W tym przypadku, użyłem takie parametry jak: nazwa, tytuł, opis, nazwa funkcji renderującej, ikona oraz słowa kluczowe. Dodatkowo odwołałem się do nowej kategorii pól, którą nazwałem acf-custom-blocks.

function my_acf_init() {
        
        if( function_exists('acf_register_block') ) {

            acf_register_block(array(
                'name'				=> 'tip-block', // Nazwa bloku
                'title'				=> __('Tip block', 'text-domain'), // Wyświetlana nazwa bloku
                'description'		=> __('Custom tip block', 'text-domain'), // Opis bloku
                'render_callback'	=> 'acf_block_render_callback', // Nazwa funkcji renderującej
                'category'			=> 'acf-custom-blocks', // Kategoria bloku
                'icon'				=> '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M5 8.5c0-.828.672-1.5 1.5-1.5s1.5.672 1.5 1.5c0 .829-.672 1.5-1.5 1.5s-1.5-.671-1.5-1.5zm9 .5l-2.519 4-2.481-1.96-4 5.96h14l-5-8zm8-4v14h-20v-14h20zm2-2h-24v18h24v-18z"/></svg>', // Ikona
                'keywords'			=> array( 'tip' ), // Słowa kluczowe
            ));

        }

}
add_action('acf/init', 'my_acf_init');

Krok 2

Dodatkową grupę pól możemy dodać za pomocą funkcji acf_category(), którą znajdziecie poniżej.

function acf_category( $categories, $post ) {
        return array_merge(
            $categories,
            array(
                array(
                    'slug' => 'acf-custom-blocks',
                    'title' => __( 'ACF Custom Blocks', 'text-domain'),
                    'icon' => 'welcome-widgets-menus'
                ),
            )
        );
}
 add_filter( 'block_categories', 'acf_category', 10, 2 );

Dzięki temu, w edytorze Gutenberga zobaczymy wszystkie bloki z Advanced Custom Fields w jednej kategorii ACF Custom Blocks.

Krok 3

Zamiast odwoływania się do parametru render_template w funkcji acf_register_block() użyliśmy parametru render_callback. Dzięki niemu, możemy zdefiniować ogólną ścieżkę do pliku szablonu renderowanego bloku. W tym przypadku dla bloków utworzonych w Gutenbergu funkcja acf_block_render_callback() będzie odwoływać się do lokalizacji components/blocks/{nazwa_bloku}.php.

function acf_block_render_callback( $block ) {

        $slug = str_replace('acf/', '', $block['name']);
        
        if( file_exists( get_theme_file_path("/components/blocks/{$slug}.php") ) ) {
            include( get_theme_file_path("/components/blocks/{$slug}.php") );
        }

}

Krok 4

Przejdźmy do grupy pól w zakładce „Własne pola”. Utwórzmy nową o nazwie „Block: Tip”, która bezpośrednio będzie wskazywać, że mamy do czynienia z blokiem wskazówką. Następnie musimy dodać trzy pola o etykietach: treść (Edytor WYSIWYG), ikona (Obraz) oraz Tytuł (Tekst). Na sam koniec wystarczy, że ustawimy lokację tak aby pola pokazywane były tylko dla bloku „Wskazówka”.

Krok 5

Zajmiemy się teraz przygotowaniem szablonu naszego bloku. W funkcji renderującej acf_block_render_callback() zdefiniowaliśmy, że będzie się ona odwoływać do pliku components/blocks/{nazwa_bloku}.php. W tym przypadku będzie to components/blocks/tip-block.php. Zawartość tego pliku może wyglądać tak jak poniżej.

<?php
    $icon = get_field('icon');
?>

<div class="tip">

    <?php if( $icon ):?>
        <div class="tip-icon">
            <img src="<?php echo esc_url($icon['url']);?>" alt="<?php echo esc_attr($icon['alt']);?>">
        </div>
    <?php endif;?>

    <?php if( get_field('title') ):?>
        <span class="tip-title"><?php the_field('title');?></span>
    <?php else: ?>
        <span class="tip-title"><?php echo __('Tip', 'text-domain');?></span> 
    <?php endif;?>

    <?php if( get_field('content') ):?>
        <div class="tip-content">
            <?php the_field('content');?>
        </div>
    <?php endif;?>

</div>

Krok 6

Po utworzeniu szablonu, musimy jeszcze do naszego bloku dodać ostylowanie. W zależności od Twojego doświadczenia możesz skorzystać zarówno z CSS, jak i z dowolnego preprocesora (na przykład SCSS). Poniżej znajdziesz przykładowy plik SCSS. Nie zapomnij go załadować w motywie.

.tip {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;

    font-size: 20px;
    background: #f8f8f8;
    padding: 45px 60px;

    &-title {
        color: #b5b5b5;
        text-transform: uppercase;
    }

    &-icon {
        display: flex;
        align-items: center;
        justify-content: center;
        width: 100px;
        height: 100px;
        background-color: #fae92d;
        margin: 15px;
        padding: 15px;
        border-radius: 50%; 
    }

    &-content {
        padding: 15px 40px 40px;
    }

}

Krok 7

Gdy spróbujemy dodać nasz blok do wpisu pojawi się mały problem. Nasz blok, pomimo dodania do motywu wyświetla się bez stylów.

Możemy to naprawić poprzez dodanie do pliku functions.php prostej funkcji. Dzięki funkcji wp_enqueue_script() oraz wp_enqueue_style() załadujemy skrypty JS oraz style CSS do naszego edytora. Zalecam, by mieć osobne pliki JS oraz CSS do motywu, a inne do edytora. Załaduj fragmenty kodu, których potrzebujesz w motywie.

    function editor_assets() {
        
        wp_enqueue_script(
            'editor-scripts',
            get_template_directory_uri() . '/dist/scripts/editor-scripts.js'
        );

        wp_enqueue_style(
            'editor-styles',
            get_template_directory_uri() . '/dist/styles/editor-styles.css' 
        );

    }

    add_action( 'enqueue_block_editor_assets', 'editor_assets' );

Po dodaniu funkcji editor_assets() w edytorze powinieneś ujrzeć ostylowany blok.

Inne możliwe przykłady użycia dodatkowych bloków przy użyciu Advanced Custom Fields PRO

Przykładowym blokiem, który w prosty sposób możemy utworzyć przy pomocy ACF PRO może być na przykład:

Sekcja z przyciskiem „Call to action”:

Chciałbyś utworzyć niestandardowe bloki do Gutenberga,
ale nie wiesz jak?

Podsumowanie wpisu

To już koniec! Wspólnie przeszliśmy przez podstawy wtyczki Advanced Custom Fields, aż po funkcjonalność ACF Blocks w Advanced Custom Fields PRO. Mam nadzieję, że dzięki temu wpisowi poznałeś najważniejszą odpowiedź czyli „Jak utworzyć dodatkowy blok do Gutenberga”.

Masz jakieś sugestie, bądź chciałbyś się czymś ciekawym podzielić? Pod wpisem znajdziesz formularz, który umożliwi Ci pozostawienie komentarza.

Opublikowano

w

Komentarze

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *