Ga naar de inhoud

useBlockProps

Standaard moet Gutenberg een wrapper rond blokken maken om ze interactief te maken in de editor. Dit kan problematisch zijn voor sommige bloktypen, zoals containers of kolommen, omdat de markup in de editor en aan de frontend dan verschilt. Met de hook useBlockProps kun je een element in de bloktemplate markeren als het hoofdelement, zodat de markup in de editor en aan de frontend gelijk is.

Gebruik

Voeg eenvoudig het attribuut useBlockProps toe aan het hoofdelement van je blok.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio combineert automatisch klassen en attributen uit de editor (zoals uitlijningsklassen) met alles wat in de bloktemplates is gedefinieerd. Daarvoor wordt onder water get_block_wrapper_attributes gebruikt.

Het filter blockstudio/blocks/components/use_block_props/render wordt toegepast op de wrapper in zowel de frontend- als de editorweergave. Klassen die door een thema of een integratie per instantie worden toegevoegd, zijn daarom zichtbaar op het editorcanvas en in de opgeslagen front-endmarkup.

Uitvoer:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

Aandachtspunten

Blockstudio voorkomt linknavigatie in de blokeditor, waaronder target="_blank", klikken met een modificatietoets, klikken met de middelste muisknop en activeren via het toetsenbord. Klikgebeurtenissen bereiken Gutenberg nog steeds, zodat gewone klikken het blok selecteren. RichText blijft bewerkbaar. Dit geldt met of zonder useBlockProps, ook wanneer een anker als hoofdelement van het blok wordt gebruikt.

Links op de frontend en de opdrachten in het contextmenu van de browser blijven ongewijzigd. U hoeft geen links uit templates te verwijderen of te vertakken op basis van $isEditor.

Hoofdelement

Omdat er in een bloktemplate maar één hoofdelement kan zijn, moet de bloktemplate bij gebruik van useBlockProps één hoofdelement hebben. Het volgende werkt bijvoorbeeld niet; Gutenberg maakt dan een wrapper rond de template.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

Op dezelfde manier kun je useBlockProps maar één keer per bloktemplate gebruiken.

Apestaartje

Blockstudio zet de bloktemplate om in geldige React-code in Gutenberg met behulp van html-react-parser. Hierdoor kan het teken @ niet worden gebruikt in een attribuutnaam HTML.

Bibliotheken zoals Alpine.js gebruiken de tekens @ om directives te definiëren op elementen HTML.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Binnen Gutenberg wordt dit attribuut @click uit het element verwijderd. (Natuurlijk werkt het nog wel aan de frontend.)

Om dit probleem te omzeilen, kun je de alternatieve syntaxis van Alpine.js gebruiken.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

Het bovenstaande werkt binnen Gutenberg en aan de frontend.

Klassen van de canvasbody

Wanneer assets.reset.enabled actief is, kopieert Blockstudio ook de opgeschoonde klassen die door het filter body_class van WordPress worden geretourneerd naar het canvas van de blokeditor. Zo blijven themaselectors zoals .brand-a .site-card op beide plekken werken.

Filter de uiteindelijke lijst met klassen wanneer de editor een beperktere set nodig heeft:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

Dit filter bepaalt alleen welke klassen naar het canvas van de editor worden gekopieerd. Het wijzigt de bodyklassen aan de frontend niet.