Mamy tylko 10 minut więc bez zbędnego wstępu przejdźmy do konkretów!

W tym wpisie zakładam że masz już dostępną działającą instalację WordPress, na przykład lokalnie na swoim komputerze. Sposób w jaki uruchamiasz WordPressa nie ma znaczenia.

Do dzieła, zaraz stworzymy własną wtyczkę do Gutenberga!

Ręczne tworzenie wtyczki

Mimo że mamy niewiele czasu to jesteśmy w stanie utworzyć wszystkie niezbędne pliki ręcznie bez większego wysiłku.

Na początek załóżmy że nasz plugin dodaje tylko jeden blok Gutenberga. Nazwijmy go roboczo Hello Blocks!.

Będziemy potrzebować:

• katalog w plikami wtyczki (ląduje w /wp-content/plugins)
• główny plik .php wtyczki
• plik JS z kodem bloku

I to tyle!

Główny plik PHP

Tutaj nic nie zmienia się względem regularnego tworzenia wtyczek do WordPressa. Utwórzmy więc folder /wp-content/plugins/hello-blocks a w nim jeden plik hello-blocks.php. Jego zawartość to na razie sam komentarz z nagłówkiem wtyczki:

<?php
/**
 * Plugin Name:       Hello Blocks!
 * Version:           1.0.0
 */

Wtyczka powinna być już dostępna do uruchomienia:

Aktywujmy ją:

Plik JavaScript z kodem bloku

Jako przykład bloku użyjemy prosty, edytowalny blok stworzony przez Adama we wpisie Jak stworzyć swój pierwszy blok Gutenberga w 15 minut jako developer PHP bez środowiska lokalnego.

Utwórzmy plik block.js w głównym katalogu wtyczki:

hello-blocks
-- hello-blocks.php
-- block.js

Plik block.js zawiera:

wp.blocks.registerBlockType( 'tutorial/moj-pierwszy-blok', {
    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 })
            }
        );
    }
} );

Rejestrowanie bloku

Mamy już działający plugin oraz przygotowany kompletny kod bloku Gutenberga. Teraz czas na połączenie tych dwóch rzeczy i rejestrację nowego bloku.

Wszystko co musimy zrobić to załadować w Gutenbergu nasz skrypt.

Jedyne na co musimy zwrócić szczególną uwagę to zależności tego skryptu. W kodzie bloku możemy znaleźć wystąpienia wp.blockEditor, wp.blocks oraz wp.element. To oznacza że aby ten skrypt został wykonany poprawnie musi zostać załadowany po skryptach wp-block-editor, wp-blocks oraz wp-element.

Użyjemy do tego klasycznego wp_enqueue_script na hooku enqueue_block_editor_assets.

<?php
/**
 * Plugin Name:       Hello Blocks!
 * Version:           1.0.0
 */

function add_block_scripts() {
  wp_enqueue_script(
    'hello-blocks-js',
    plugins_url( 'block.js', __FILE__ ),
    array( 'wp-block-editor', 'wp-blocks', 'wp-element' )
  );
}

add_action( 'enqueue_block_editor_assets', 'add_block_scripts' );

Testowanie nowewgo bloku

Czas na sprawdzenie czy to działa. Idź do tworzenia nowego wpisu i spróbuj wpisać /moj w Gutenbergu.

Enter

Działa! Gratuluję, właśnie stworzyłeś wtyczkę dodającą blok do Gutenberga w mniej niż 10 minut.

Ale to nie wszystko!

Rejestrowanie bloku przy użyciu block.json i register_block_type

Jest kilka sposobów na rejestrowanie bloku przy pomocy register_block_type.

W czasie gdy Gutenberg był rozwijany pojawiały się coraz to nowe sposoby rejestracji własnych bloków. Z tego powodu w sieci znajduje się sporo nieaktualnych artykułów i tutoriali.

Tutaj skupimy się tylko na jednym, zalecanym sposobie. Jest to najnowsze API register_block_type i powinno się rejestrować bloki w ten właśnie sposób.

Nowy plik: block.json

W głównym katalogu wtyczki utwórzmy nowy plik block.json:

hello-blocks
-- hello-blocks.php
-- block.js
-- block.json

Zaczniemy od podstawowej zawartości block.json. Nie będziemy omawiać wszystkich elementów tego pliku. To temat na osobny artykuł o anatomii pliku block.json. Nie przejmuj się jednak, na tą chwilę nie musisz wiedzieć do czego służy $schema czy apiVersion.

Minimalna zawartość pliku

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3
}

Dodajemy nazwę bloku

Pole name jest wymagane i musi być w formacie tekst/tekst.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "tutorial/moj-pierwszy-blok"
}

Przenosimy część kodu z block.js do block.json

Dodajemy tytuł bloku oraz jego atrybuty (obie te rzeczy zostaną usunięte z pliku block.js).

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "tutorial/moj-pierwszy-blok",
  "title": "Mój pierwszy blok!",
  "attributes": {
    "content": {
      "type": "string",
      "default": "Cześć"
    }
  }
}

Wskazywanie lokalizacji pliku JavaScript bloku

Używamy do tego pola editorScript.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "tutorial/moj-pierwszy-blok",
  "title": "Mój pierwszy blok!",
  "attributes": {
    "content": {
      "type": "string",
      "default": "Cześć"
    }
  },
  "editorScript": "file:./block.js"
}

Zaktualizowany plik block.js

Zauważ że nie ma już tutaj ani tytułu bloku ani jego atrybutów. Według dokumentacji WordPressa ustawianie atrybutów i innych elementów bloku powinno odbywać się poprzez plik block.json.

W pierwszej linii musieliśmy powielić nazwę bloku podaną w block.json. W środowisku obsługującym importowanie z innych plików moglibyśmy uniknąć tej duplikacji poprzez import z pliku block.json.

wp.blocks.registerBlockType("tutorial/moj-pierwszy-blok", {
  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 }),
    });
  },
}); 

Zależności pliku block.js

W kolejnej sekcji zobaczysz że do rejestracji bloku nie będziemy już ręcznie zaciągać skryptów do edytora. Wszystko będzie działo się automatycznie.

W jaki sposób w takiej sytuacji kontrolować zależności które są wymagane do działania pliku?

Musimy utworzyć plik o nazwie block.asset.php (lub xxx.asset.php jeśli nasz plik JavaScript nazywa się xxx.js).

Struktura:

hello-blocks
-- hello-blocks.php
-- block.asset.php
-- block.js
-- block.json

W naszym przypadku zawartość pliku block.asset.php to:

<?php return array(
  'dependencies' => array(
    'wp-block-editor',
    'wp-blocks',
    'wp-element'
  )
);

Zaktualizowany plik hello-blocks.php

Największe zmiany i uproszczenia możemy zobaczyć w głównym pliku PHP wtyczki.

Jeśli używamy pliku block.json, nie musimy już w ogóle rejestrować skryptów. Wszystko dzieje się automatycznie.

Jedyne co musimy zrobić to wykonać funkcję register_block_type przypiętą na hooku init.

<?php
/**
 * Plugin Name:       Hello Blocks!
 * Version:           1.0.0
 */

function my_add_block() {
  register_block_type( __DIR__ . '/block.json' );
}

add_action( 'init', 'my_add_block' );

I to wszystko. Nasz blok został zarejestrowany.

Wsparcie dla wielu bloków w jeden wtyczce

Możemy łatwo w jednej wtyczce zarejestrować kilka bloków korzystając ze wspomnianej możliwości użycia folderów zamiast wskazywania na konkretny plik block.json. Na przykład:

hello-blocks
-- hello-blocks.php
-- block-1
-- -- block.asset.php
-- -- block.js
-- -- block.json
-- block-2
-- -- block.asset.php
-- -- block.js
-- -- block.json

Przy powyższej strukturze możemy w naszym pliku hello-blocks.php dodać oba bloki z folderów block-1 i block-2:

<?php
/**
 * Plugin Name:       Hello Blocks!
 * Version:           1.0.0
 */

function my_add_blocks() {
  register_block_type( __DIR__ . '/block-1/' );
  register_block_type( __DIR__ . '/block-2/' );
}

add_action( 'init', 'my_add_blocks' );

Gotowe biblioteki i narzędzia automatyzujące pracę z blokami

Tak jak wspomniałem wcześniej, tworzenie ręcznie plików xxx.asset.php, lub pisanie nowoczesnego JavaScriptu w plikach JS bloków jest uciążliwe gdybyśmy mieli to obsługiwać ręcznie.

Z pomocą przychodzi do tego oficjalna paczka @wordpress/create-block. Służy ona do tworzenia całej wtyczki jedną komendą:

npx @wordpress/create-block@latest hello-block

Paczka obsługuje wiele opcji. Więcej znajdziesz w dokumentacji.

Pod maską, paczka używa innej, również oficjalnej paczki @wordpress/scripts, która odpowiada za obsługę kompilowania plików JS (ES6+) czy SCSS/SASS do plików rozumianych przez przeglądarkę (takich jak w naszym prostym przykładzie).

Inne przydatne narzędzia to np. @wordpress/env: oparte na dokerze kompletne środowisko WordPressa, lub WordPress Playground czyli magicznie działający WordPress w przeglądarce.

Podsumowanie i kod źródłowy

Jak widzisz, tworzenie wtyczki która dodaje blok do Gutenberga nie jest wcale takie skomplikowane.

Mam nadzieję że wpis okazał się pomocny.

Owocnego tworzenia wtyczek do Gutenberga!

Podobało się? Podziel się z innymi