WordPress mini-projekt – pierwszy dynamiczny blok

Piszemy pierwszy dynamiczny blok dla WordPressa. Blok będzie zawierał informację Copyright z nazwą witryny i aktualnym rokiem. Nauczymy się tworzyć dynamiczne bloki WordPressa, których możemy używać w szablonach blokowych albo wewnątrz wpisów, także w szablonach klasycznych. Użyjemy mieszanki Reacta z pakietem wp-scripts oraz klasycznego, WordPressowego PHP.

Tworzymy blok dynamiczny z linii komend – pierwsze kroki

Musimy wejść do naszej instalacji WordPressa i odnaleźć folder plugins wewnątrz folderu wp-content. Następnie wykorzystamy poniższą komendę, aby wygenerować plik pluginu

npx @wordpress/create-block@latest date-copy-try  --variant dynamic

Jeżeli nie mamy node.js albo npx – musimy to zainstalować, internet jest pełen tutoriali na ten temat. Powyższa komenda powinna nam utworzyć folder o nazwie date-copy-try, zawierający blok i plugin o takiej nazwie. Tworzenie plików może potrwać nawet do kilku minut.

Po otrzymaniu informacji o tym, że wszystko poprawnie się zainstalowało powinniśmy przejść do tego folderu z poziomu terminala, korzystając z komendy

cd date-copy-try

Teraz przechodzimy do folderu o nazwie src, do pliku o nazwie edit.js. Ten plik zawiera nasz blok widoczny w edytorze bloków, czyli jak będzie widziany podczas dodawania. Rzućmy okiem na fragment:

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Date Copy Try – hello from the editor!', 'date-copy-try' ) }
		</p>
	);
}

Zamieńmy to na:

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			Hello from editor!
		</p>
	);
}

Teraz przejdźmy do pliku render.php – on steruje tym, jak nasz blok będzie wyświetlany na stronie. Powinniśmy mieć tam coś takiego:

<?php
/**
 * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
 */
?>
<p <?php echo get_block_wrapper_attributes(); ?>>
	<?php esc_html_e( 'Date Copy Try – hello from a dynamic block!', 'date-copy-try' ); ?>
</p>

Zamieńmy to na:

<?php
/**
 * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
 */
?>
<p <?php echo get_block_wrapper_attributes(); ?>>
	Hello from render.php
</p>

Mamy też do dyspozycji pliki editor.scss oraz style.scss. Jak nietrudno się domyślić, jeden obsługuje style edytora, drugi style wyświetlanego bloku w ogóle. Możemy się tam pobawić, popodmieniać kolory. Teraz pora na komendę:

npm run build

To jeszcze nie wszystko. Nasz plugin o nazwie date-copy-try musimy odnaleźć w panelu admina i aktywować. Następnie wejść na jakikolwiek wpis i dodać blok date-copy-try do posta. W edytorze zobaczmy napis „hello from editor” zaś po zapisaniu „hello from render.php” przy wyświetlaniu wpisu. Oba będą miały domyślne, dość dziwne formatowanie – kolor tła niebieski. Pochodzi on z pliku style.scss:

.wp-block-create-block-date-copy-try {
	background-color: #21759b;
	color: #fff;
	padding: 2px;
}

To jest klasa, którą cały nasz blok posiada. W edytorze posiada ją ze względu na funkcję useBlockProps:

<p { ...useBlockProps() }>
			Hello from editor!
</p>

Ta funkcja nadaję m.in tę klasę (w React i wp-scripts to className, nie class – ale o tym później) do edytowanego bloku. Blok renderowany zaś ma tę klasę ze względu na funkcję get_block_wrapper_attributes().

<p <?php echo get_block_wrapper_attributes(); ?>>
	Hello from render.php
</p>

Te funkcje generalnie są dobre, nie chcemy ich usuwać – chcemy tylko wyłączyć te kolory. Możemy to zrobić w pliku style.scss:

.wp-block-create-block-date-copy-try {
	// background-color: #21759b;
	color: black;
	padding: 2px;
}

Po wszystkim musimy użyć jeszcze komendy

npm run build

Wyłączać i włączać pluginu nie musimy, jeżeli już go raz poprawnie podpięliśmy, ale tę komendę wykonujemy po każdej zmianie. Teraz kolor tekstu będzie czarny, zaś kolor tła – żaden. W edytorze możemy mieć co najwyżej pewne czerwone, kropkowe obramowanie pochodzące z pliku editor.scss:

.wp-block-create-block-date-copy-try {
	border: 1px dotted #f00;
}

Nie jest – moim zdaniem – dobrą praktyką tego obramowania się pozbawiać, ale kolor możemy, dla zobrazowania jak to wszystko działa, zmienić.

.wp-block-create-block-date-copy-try {
	border: 1px dotted gold;
}

Po wszystkim, rzecz jasna, używamy komendy:

npm run build

Brzydko to wygląda, ale obrazuje, jak działa. Możemy wrócić do poprzedniego koloru. Teraz otworzymy sobie plik block.json w tym samym folderze src i dodamy do niego w supports następującą treść:

"supports": {
		"html": false,
		"color": {
			"background": true,
			"text": true
		}
	},

To powinno sprawić, że nasz blok będzie miał ustawienie, pozwalające na wybieranie nam koloru tekstu i tła samemu, w zakładce blok po prawej stronie, klikając na „kolor” następnie „tekst” albo „tło” i wybierając kolor. Dostępne kolory pochodzą z pliku theme.json naszego szablonu i też warto będzie się w ten temat zagłębić. Teraz jednak pamiętajmy, że dokonaliśmy zmiany, a zatem pora na komendę:

npm run build

Możemy teraz wypróbować sobie zmienianie koloru tekstu i tła. W naszych plikach scss nie mamy nic, co by nam przeszkadzało, zaś w block.json nadaliśmy taką możliwość użytkownikowi.

Block copyright na stronie – render.php

Zabierzemy się za to, jak nasz blok będzie wyświetlany na stronie zapisanego wpisu. Chcemy mieć informację copyright, zawierającą aktualny rok oraz nazwę witryny. W pliku render.php mamy na razie taki kod kod:

<p <?php echo get_block_wrapper_attributes(); ?>>
	Hello from render.php
</p>

Zamieniamy to na:

<p <?php echo get_block_wrapper_attributes(); ?>>
	©Copyright <?php echo date("Y");?> <?php bloginfo('name'); ?>
</p>

Mamy tutaj znak Copyright, funkcję PHP date zwracającą rok (wrzuconą w echo) oraz funkcję WordPressa bloginfo wyświetlającą za pomocą argumentu 'name’ nazwę naszej witryny. Te funkcje WordPressa nie potrzebują echo, bo same je wykonują.

Teraz po zapisaniu pliku render.php używamy naszej ulubionej komendy:

npm run build

Wystarczy wejść na stronę z wpisem zawierającym nasz blok, możliwe, że odświeżyć, i już mamy naszą informację – copyright, rok, nazwa witryny.

Blok copyright w edytorze – edit.js

W edytorze, czyli tam, gdzie dodajemy bloki, nic się jeszcze nie zmieniło. Nasz plik edit.js cały czas wygląda tak:

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			Hello from editor!
		</p>
	);
}

Dodanie daty nie będzie takie trudne:

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			©Copyright {new Date().getFullYear()} SITE_NAME
		</p>
	);
}

Po wszystkim oczywiście nasza ulubiona komenda, czyli:

npm run build

Problem stanowi to „SITE NAME”. Możemy tam wpisać nazwę naszej witryny, ale jeżeli chcemy stworzyć blok i plugin uniwersalny, który działa dla każdej strony, to musi być zaciągane dynamicznie. Tak samo jak w render.php, gdzie odpowiada za to funkcja bloginfo(’name’) a nie jakaś „na sztywno” zapisana nazwa strony.

Nie zagłębiając się w szczegóły, które z czasem poznamy, musimy w importach pliku edit.js dodać następującą linijkę:

import { useEntityProp } from '@wordpress/core-data';

Zaimportowaliśmy właśnie narzędzie pozwalające nam na wyciąganie z naszego bloga różnych treści w dynamiczny sposób. Teraz pora go użyć. Kod jest następujący:

export default function Edit() {
	const [ title ] = useEntityProp( 'root', 'site', 'title' );
	return (
		<p { ...useBlockProps() }>
			©Copyright {new Date().getFullYear()} {title}
		</p>
	);
}

To po prostu trzeba znać mniej więcej na takiej samej zasadzie jak znamy – albo nie znamy i wyszukujemy w google – funkcję bloginfo. Teraz tylko pozostaje nam użyć naszej ulubionej komendy:

npm run build

I już – w edytorze mamy teraz mniej więcej to samo, co w renderze – edytor ma tylko specjalne obramowanie wokół naszego bloku. Nazwa witryny jest dynamicznie zaciągana, jak w render.php za pomocą bloginfo(’name’).

Stworzyliśmy nasz pierwszy, w dodatku dynamiczny blok (czyli używający Reacta tylko do edytora, zaś wyświetlany przy pomocy PHP). Nauczyliśmy się podstaw stylowania go oraz umożliwiania użytkownikowi samemu dobrać odpowiedni styl. Napisaliśmy nasz blok za pomocą Reacta dla edytora oraz za pomocą PHP + WordPressa dla wyświetlania. Jest to dobry początek w kierunku poznania bloków WordPressa, kierunek, który będziemy kontynuować.