Pracujesz przy klasycznych motywach WordPressa? Chciałbyś w końcu zacząć tworzyć bloki? Każdy tutorial zniechęca Cię żmudnym procesem konfigurowania lokalnego środowiska? Dobrze trafiłeś!

W tym wpisie stworzymy prosty blok WordPressa szybko, łatwo, i bez instalowania czegokolwiek. Bez zbędnych wstępów, wskoczmy od razu do kodu.

Prosty blok Guteneberga w minutę

Oto najprostszy możliwy blok Gutenberga:

wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-block', {
    title: "Mój pierwszy blok!",
    edit: function () {
        return wp.element.createElement( "p", {}, "Cześć!" );
    }
} );

Możesz go wypróbować! Otwórz śmiało edytor postów w dowolnym WordPressie i wklej ten kod powyżej w narzędziach deweloperskich. Już? Gratuluję! Właśnie stworzyłeś swój pierwszy blok Gutenberga. Tak po prostu, bez wymyślnych narzędzi:

Najważniejszą częścią naszego bloku jest funkcja edit(). Omówimy krótko jak ona właściwie działa, a następnie rozbudujemy nasz blok o możliwość edycji tekstu.

Funkcja edit() wyświetla blok w edytorze

Funkcja edit() jest tak naprawdę komponentem Reacta który jest wyświetlany w edytorze w miejscu naszego bloku.

Weźmy na przykład blok „obrazek”. To właśnie funkcja edit() odpowiada za wyświetlenie obrazka bądź zaślepki umożliwiającej jego wybór:

Nasz blok jest dużo prostszy, ale działa na tej samej zasadzie. Kiedy dodasz w poście „Mój pierwszy blok” to edytor uruchomi funkcję edit() i wyświetli na ekranie to co ona zwróci: paragraf tekstu(<p>) z tekstem Cześć!

Możesz teraz zapytać czemu funkcja edit() nie przypomina komponentów Reacta które widziałeś w innych artykułach? Przecież zwykle wyglądają one raczej tak:

function Edit() {
    return <p>Cześć!</p>;
}

Taka notacja nazywa się JSX i, choć bardziej przejrzysta, to nie jest prawidłowym JavaScriptem. Takiego kodu nie uruchomimy w przeglądarce.

Gdyby ten wpis miał tytuł „Twój pierwszy blok w 3 godziny” to moglibyśmy zainstalować narzędzia przekształcające JSX na następujący kod JavaScript:

function Edit() {
    return wp.element.createElement( "p", {}, "Cześć!" );
}

Ale dziś mamy tylko 15 minut więc oszczędzimy sobie zamieszania z narzędziami i będziemy od razu pisać prawidłowy JavaScript. Nasz kod będzie przez to nieco dłuższy, ale będziemy mogli z niego od razu skorzystać.

No dobrze, ale mieliśmy rozbudować blok o możliwość edycji. Do dzieła!

Dodajemy możliwość edycji Bloku

Aby móc w edytorze edytować napis „Cześć!” wyświetlany w naszym bloku, zamienimy tag <p> na edytowalny komponent RichText. To ten sam komponent którego używasz przy edycji paragrafów, guzików, i innych znajomych bloków – umożliwia on edycję treści oraz jej formatowanie poprzez pogrubienie, kursywę itp.

Zanim jednak zgłębimy szczegółowo mechanikę RichText, warto zrozumieć ogólne zasady działania formularzy w ekosystemie Reacta.

Jak działają formularze w komponentach Reacta?

Stworzenie w React-cie edytowalnego pola tekstowego wymaga:

1. Stworzenia pola tekstowego
2. Ustawienia jego wartości
3. Aktualizowania tej wartości przy każdej edycji

W praktyce wygląda to tak:

function Form() {
    // Deklarujemy stan:
    const [content, setContent] = useState('Cześć!');
    return React.createElement(
        "input",
        {
            type: "text",

            // Ustawiamy wartość pola tekstowego na aktualną treść:
            value: content,

            // Aktualizujemy treść przy każdej edycji:
            onChange: (e) => setContent(e.target.value) 
        }
    );
}

Teraz jesteśmy gotowi na stworzenie edytowalnego bloku Gutenberga.

Zamieńmy tag <p> na komponent RichText

Komponentu RichText używamy bardzo podobnie do zwykłego inputa:

// Najpierw odrejestrujmy blok z poprzedniego przykładu:
wp.blocks.unregisterBlockType( 'tutorial/moj-pierwszy-block');
wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-block', {
    title: "Mój pierwszy blok!",
    edit: function () {
        // Deklarujemy stan:
        const [content, setContent] = wp.element.useState('Cześć!');
        return wp.element.createElement(
            wp.blockEditor.RichText,
            {
                tagName: "div",

                // Ustawiamy wartość RichText na aktualną treść bloku:
                value: content,

                // Aktualizujemy treść przy każdej edycji:
                onChange: newContent => setContent( newContent )
            }
        );
    }
} );

Uruchom powyższy kod tak jak poprzednio, a następnie dodaj „Mój pierwszy blok” w edytorze. Tym razem blok nie tylko wyświetla „Cześć!”, ale też pozwala na edycję i formatowanie swojej treści!

Mamy jeszcze ostatni problem. Nasze zmiany w treści nie zostaną zapisane razem ze stroną – stracimy je w momencie zamknięcia karty przeglądarki.

Dodajemy możliwość zapisu Bloku

W WordPressie, treść bloków zapisujemy w postaci atrybutów bloków które są zapisywane w treści posta lub strony. Ale nasz blok nie używa jeszcze atrybutów. Zmiany treści są przechowywane jedynie przez chwilę w tymczasowym stanie Reacta. Zmieńmy to!

Dodajemy atrybutu Bloku

Żeby dodać atrybut, musimy go zadeklarować przy rejestracji bloku:

wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-block', {
    title: "Mój pierwszy blok!",
    // Dodajemy atrybut o nazwie "content":
    attributes: {
        content: {
            type: "string",
            default: "Cześć"
        }
    },
    // ... funkcja edit() póki co pozostaje bez zmian...
} );

Powyższa konfiguracja mówi Gutenbergowi, że nasz blok może zawierać dane tekstowe które powinny zostać zapisane w bazie.

Zapisujemy treść w atrybucie Bloku

Wykonamy teraz w naszym komponencie jedną jedyną zmianę: Podmienimy Reactowy stan komponentu na atrybut bloku który przed chwilą dodaliśmy:

// Najpierw odrejestrujmy blok z poprzedniego przykładu:
wp.blocks.unregisterBlockType( 'tutorial/moj-pierwszy-block');
wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-block', {
    title: "Mój pierwszy blok!",
    attributes: {
        content: {
            type: "string",
            default: "Cześć"
        }
    },
    // Atrybuty są dostępne przez pierwszy argument funkcji edit():
    edit: function ({ attributes, setAttributes }) {
        return wp.element.createElement(
            wp.blockEditor.RichText,
            {
                tagName: "div",

                // Ustawiamy wartość RichText na aktualną treść bloku:
                value: attributes.content,

                // Aktualizujemy treść przy każdej edycji:
                onChange: newContent => setAttributes({ content: newContent })
            }
        );
    }
} );

I voilà! Zmiany w treści bloku zostaną teraz zapisane w bazie danych! Przed nami ostatni już krok.

Zapisujemy treść do wyświetlenia na naszej stronie

WordPress umie już zapisać nasz blok ale nie wie jeszcze jak go wyświetlić. Jeśli stworzymy nową stronę i umieścimy na niej nasz blok, to na stronie zobaczymy w jego miejscu jedynie białą plamę.

Zdefiniujmy funkcję save która powie WordPressowi jakiego kodu HTML użyć do wyrenderowania naszego bloku na stronie:

function save( { attributes } ) {
    const blockProps = wp.blockEditor.useBlockProps.save();
    return wp.element.createElement(
        "div",
        blockProps,
        attributes.content
    );
}

I to już! Stworzyliśmy blok który można edytować, zapisywać, i oglądać na stronie internetowej.

A tutaj cały kod który stworzyliśmy zebrany w jednym miejscu:

// Najpierw odrejestrujmy blok z poprzedniego przykładu:
wp.blocks.unregisterBlockType( 'tutorial/moj-pierwszy-block');
wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-block', {
    title: "Mój pierwszy blok!",
    attributes: {
        content: {
            type: "string",
            default: "Cześć"
        }
    },
    save: function( { attributes } ) {
        const blockProps = wp.blockEditor.useBlockProps.save();
        return wp.element.createElement(
            "div",
            blockProps,
            attributes.content
        );
    },
    edit: function ({ attributes, setAttributes }) {
        return wp.element.createElement(
            wp.blockEditor.RichText,
            {
                tagName: "div",
                value: attributes.content,
                onChange: newContent => setAttributes({ content: newContent })
            }
        );
    }
} );

Rozbudowane możliwości bloków Gutenberga

Bloki Gutenberg oferują szeroki zakres funkcjonalności, które przekraczają ramy tego wpisu. Oto niektóre z nich:

• Dodawanie przycisków do paska bloku
• Integracja z inspektorem bloku
• Dostęp do REST API WordPressa
• Wsparcie dla różnorodności kolorów, stylów typograficznych oraz układów
• Wykorzystanie dynamicznych treści za pomocą kodu PHP

Tworzenie bloków może na początku wydawać się skomplikowane, szczególnie jeśli do tej pory pracowałeś głównie z PHP, ale opanowanie tej umiejętności otworzy nowe horyzonty dla Twoich stron WordPressa.

I to już! Masz pytania? Tematy o których chcesz przeczytać w kolejnym poście? A może coś było nie jasne? Zostaw komentarz i daj mi znać!

Wesołego kodowania!

Podobało się? Podziel się z innymi