WordPress mini-projekt – statyczny blok z tekstem

Piszemy plugin z blokiem statycznym, czyli takim, w którym zarówno za wyświetlanie edytora jak i renderowanie bloku odpowiada JavaScript (React) – pliki edit.js i save.js. Użyjemy też atrybutu, który przechowuje treść (w tym wypadku – tekst) oraz komponentu RichText, który pozwala nam wpisywanie tekstu w edytorze.

Tworzymy statyczny blok i ustawiamy atrybuty

Aby stworzyć blok statyczny tradycyjnie przejdziemy do folderu plugins w folderze wp-content naszej instalacji Wodpressa i użyjemy poniższej komendy:

npx @wordpress/create-block@latest rich-text-try

Komenda ta stworzy nam blok statyczny, a zatem taki, w którym za renderowanie bloku odpowiada nie plik render.php lecz plik save.js kontrolowany przez WordPressowego Reacta. Może to zająć nawet kilka minut. Gdy już wszystko będzie gotowe, przechodzimy do folderu komendą:

cd rich-text-try

Teraz wypada wejść do panelu admina w WordPressie, znaleźć naszą wtyczkę i włączyć ją. Gdy już to mamy, w folderze naszego pluginu przechodzimy do folderu src, tam odnajdujemy plik block.json i dopisujemy do niego poniższą treść:

"attributes": {
		"content": {
			"type": "string",
			"source": "html",
			"selector" : "h2"
			}
		}
}

Są to atrybuty, z jakich mamy zamiar korzystać. Mamy tylko jeden atrybut o nazwie „content”, typu napisowego, źródła htmlowego (do tego dojdziemy) oraz z selektorem h2 (czyli do elementu h2 będziemy ten atrybut przypisywać). Trochę to skomplikowane, ponieważ korzystamy ze statycznych bloków i komponentu RichText, zazwyczaj w atrybutach mamy tylko nazwę i typ, ale nie zrażajmy się.

Teraz przejdźmy do pliku edit.js:

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Rich Text Try – hello from the editor!', 'rich-text-try' ) }
		</p>
	);
}

Przygotujmy go do pracy z naszym atrybutem content. Robimy to dopisując poniższą treść:

export default function Edit({ attributes, setAttributes }) {
	const { content } = attributes;
	return (
		<p { ...useBlockProps() }>
			{ __( 'Rich Text Try – hello from the editor!', 'rich-text-try' ) }
		</p>
	);
}

W uproszczeniu – wyciągamy obiekt attributes oraz funkcję setAttributes, służącą do zapisywania atrybutów. Wyciągamy też „content” z naszych atrybutów. Teraz plik save.js:

export default function save() {
	return (
		<p { ...useBlockProps.save() }>
			{ 'Rich Text Try – hello from the saved content!' }
		</p>
	);
}

Tutaj musimy też dokonać pewnych zmian:

export default function save({ attributes }) {
	const { content } = attributes
	return (
		<p { ...useBlockProps.save() }>
			{ 'Rich Text Try – hello from the saved content!' }
		</p>
	);
}

W save – swoją drogą nietrafiona nazwa, lepsze byłoby saved – niczego nie będziemy już zapisywać, będziemy tylko odczytywać i wyświetlać zapisany atrybut content, toteż tylko attributes wyciągamy przy pomocy dekompozycji argumentów.

Aby nasz projekt był w pełni gotowy potrzebujemy jeszcze ustawić sobie importy, w obu plikach. Zaimportujemy komponent RichText z modułu block-editor:

import { useBlockProps, RichText } from '@wordpress/block-editor';

Teraz jesteśmy – mniej więcej – gotowi do poskładania tego wszystkiego do kupy.

Edycja i zapisywanie tekstu komponentem RichText

Teraz użyjemy naszego komponentu RichText w pliku edit.js. Zamieniamy naszą funkcję edit na poniższy kod:

export default function Edit({ attributes, setAttributes }) {
	const { content } = attributes;
	return (
		<RichText { ...useBlockProps() }
			tagName="h2"
			placeholder="heading"
			value={ content }
			onChange={ newVal => setAttributes({ content: newVal }) }
			/>
	);
}

tagName oznacza, jakim tagiem ma być nasz komponent – tutaj <h2>. Placeholder – co ma być wpisane, gdy tekst jest pusty. Do value przypisujemy atrybut content zaś onChange przyjmuje funkcję, która ma zapisywać nowy atrybut za każdym razem, gdy coś tam dopiszemy.

Teraz pora na save.js:

export default function save({ attributes }) {
	const { content } = attributes
	return (
		<RichText.Content { ...useBlockProps.save() }
			tagName="h2"
			value={ content }
			/>
	);
}

Tutaj jest dużo prościej i myślę, że i to jest zrozumiałe. Musimy tylko upewnić się, że zarówno edit.js jak i save.js importują komponent RichText (z tego samego miejsca co useBlockProps czyli modułu block-editor).

Teraz pozostaje nam tylko użyć naszej ulubionej komendy:

npm run build

Już możemy wypróbować, jak nasz blok działa. Możemy teraz zmienić CSS, jeżeli denerwuje nas to, co mamy, generalnie jednak blok jest ukończony. Zrobiliśmy rzecz wydawałoby się bardzo prostą, ale zrozumienie i przećwiczenie tego przyda nam się w następnych wpisach, które będziemy kontynuować.

Dynamiczny blok a RichText – jak to osiągnąć

Umiejętność pracy ze statycznymi blokami zawierającymi komponent RichText przyda się nam, ale to samo możemy osiągnąć dynamicznym blokiem, co też postaramy się tutaj uczynić. Zacznijmy od komendy (w folderze plugins):

npx @wordpress/create-block@latest rich-text-dyn  --variant dynamic

Teraz komenda:

cd rich-text-dyn

W block.json (w folderze src) podajemy atrybut bez źródła:

"attributes": {
		"content": {
		"type": "string",
        "selector" : "h2"
		}
		}

W edit.js importujemy komponent RichText:

import { useBlockProps, RichText } from '@wordpress/block-editor';

Tworzymy taką samą funkcję edit jak w bloku statycznym:

export default function Edit({ attributes, setAttributes }) {
	const { content } = attributes;
	return (
		
			<RichText { ...useBlockProps() }
			tagName="h2"
			placeholder="heading"
			value={ content }
			onChange={ newVal => setAttributes({ content: newVal }) }
			/>

	);
}

W render.php jest zaś inaczej. Atrybuty są przechowywane w tablicy asocjacyjnej $attributes. Nasz render będzie wyglądał tak:

<?php
/**
 * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
 */
?>
<h2 <?php echo get_block_wrapper_attributes(); ?>>
	<?php esc_html_e( $attributes["content"], 'rich-text-dyn' ); ?>
</h2>

Sami sobie musieliśmy stworzyć tag <h2> i wrzucić w niego atrybut content. I już – blok dynamiczny korzystający z atrybutów i komponentu RichText po stronie edytora. Teraz wystarczy tylko nasza ulubiona komenda (npm run build) i już możemy to wypróbować.

Które bloki są lepsze? Statyczne czy dynamiczne? To zależy. Od bardzo wielu merytorycznych i pozamerytorycznych czynników (jak nasze upodobania i preferencje). Koniec końców potrafimy jednak obsługiwać i jeden i drugi korzystając z atrybutów zapisywanych w edytorze i odczytywanych przez odwiedzającego witrynę.

To już konkretny wstęp do następnych projektów, które będziemy tworzyć z blokami WordPressa.