Share
De nieuwe WordPress-editor (met codenaam Gutenberg) moet in versie 5.0 verschijnen. Dit is de perfecte tijd om het te begrijpen voordat het in WordPress-kern terechtkomt. In deze serie laat ik u zien hoe u met de Block API kunt werken en uw eigen inhoudsblokken kunt maken die u kunt gebruiken om uw berichten en pagina's uit te breiden..
In de vorige post zagen we hoe het te gebruiken create-Guten-block toolkit om een plug-in te maken die een voorbeeldblok bevat dat voor ons klaar staat om mee te werken. We kunnen dit indien nodig eenvoudig uitbreiden, maar het is een goed idee om te weten hoe je een nieuw blok kunt creëren om alle aspecten van de ontwikkeling van Gutenberg-blokken volledig te begrijpen..
In dit bericht maken we een tweede blok in onze my-maat-block plugin om een willekeurige afbeelding weer te geven van de PlaceIMG-webservice. U kunt het blok ook aanpassen door de afbeeldingscategorie te selecteren in een selectieknop voor vervolgkeuzelijsten.
Maar eerst zullen we leren hoe blokscripts en -stijlen in de wachtrij worden gezet voordat we verder gaan met het allerbelangrijkste registerBlockType () functie, die fundamenteel is voor het maken van blokken in Gutenberg.
Om JavaScript en CSS toe te voegen die onze blokken nodig hebben, kunnen we twee nieuwe WordPress-hooks van Gutenberg gebruiken:
Accentsconagua
enqueue_block_editor_assetsenqueue_block_assetsDeze zijn alleen beschikbaar als de Gutenberg-plug-in actief is en ze werken op een vergelijkbare manier als standaard WordPress-hooks voor het bijhouden van scripts. Ze zijn echter specifiek bedoeld om met Gutenberg-blokken te werken.
De enqueue_block_editor_assets hook voegt alleen scripts en stijlen toe aan de admin-editor. Dit maakt het ideaal voor het in de wacht slepen van JavaScript om blokken en CSS te registreren om gebruikersinterface-elementen voor blokinstellingen te stylen.
Voor blokuitvoer wilt u echter dat uw blokken hetzelfde weergeven in de editor als aan het begin van het programma. Gebruik makend van enqueue_block_assets maakt dit gemakkelijk omdat stijlen automatisch aan zowel de editor als de frontend worden toegevoegd. U kunt deze haak ook gebruiken om JavaScript te laden indien nodig.
Maar u vraagt zich misschien af hoe u scripts en stijlen kunt inlijsten enkel en alleen aan de voorkant. Er is geen WordPress-haakje waarmee u dit rechtstreeks kunt doen, maar u kunt dit omzeilen door een voorwaardelijke verklaring toe te voegen in de enqueue_block_assets haak callback-functie.
add_action ('enqueue_block_assets', 'load_front_end scripts'); functie load_front_end scripts () if (! is_admin () // wacht front-end alleen scripts en stijlen hierOm scripts en stijlen daadwerkelijk in te huren met behulp van deze twee nieuwe hooks, kunt u de standaard gebruiken wp_enqueue_style () en wp_enqueue_scripts () werkt zoals u normaal zou doen.
U moet er echter voor zorgen dat u de juiste scriptafhankelijkheden gebruikt. Voor het inladen van scripts in de editor, kunt u de volgende afhankelijkheden gebruiken:
array ('wp-blocks', 'wp-i18n', 'wp-element', 'wp-components') array ('wp-edit-blocks') En als u stijlen ophaalt voor zowel de editor als de frontend, kunt u deze afhankelijkheid gebruiken:
array ('wp-blocks')Een ding dat het vermelden waard is, is dat de feitelijke bestanden in de wacht zijn gesleept door onze my-maat-block plugin zijn de gecompileerd versies van JavaScript en CSS en niet de bestanden die de JSX- en Sass-broncode bevatten.
Dit is alleen iets om in gedachten te houden bij het handmatig in wacht zetten van bestanden. Als u probeert raw-code in te roosteren die React, ES6 + of Sass bevat, zult u verschillende fouten tegenkomen.
Dit is waarom het handig is om een toolkit te gebruiken zoals create-Guten-block omdat het automatisch scripts voor u verwerkt en in de wachtrij plaatst!
Om een nieuw blok te creëren, moeten we het bij Gutenberg registreren door te bellen registerBlockType () en het doorgeven van de bloknaam plus een configuratieobject. Dit object heeft nogal wat eigenschappen die een goede uitleg vereisen.
Laten we echter eerst de bloknaam bekijken. Dit is de eerste parameter en is een string die uit twee delen bestaat, een naamruimte en de bloknaam zelf, gescheiden door een schuine streep naar voren.
Bijvoorbeeld:
registerBlockType ('block-namespace / block-name', // configuratie-object);Als u meerdere blokken in een plug-in registreert, kunt u dezelfde naamruimte gebruiken om al uw blokken te ordenen. De naamruimte moet echter uniek zijn voor uw plug-in, wat naamconflicten helpt voorkomen. Dit kan gebeuren als een blok met dezelfde naam al is geregistreerd via een andere plug-in.
De seconde registerBlockType () parameter is een instellingenobject en vereist een aantal eigenschappen dat moet worden gespecificeerd:
titel (string): wordt in de editor weergegeven als het doorzoekbare bloklabelOmschrijving (optionele reeks): beschrijft het doel van een blokicoon (optioneel Dashicon- of JSX-element): pictogram dat bij een blok hoortcategorie (string): waar het blok wordt weergegeven in de Blokken toevoegen dialoogtrefwoorden (optionele array): maximaal drie sleutelwoorden die worden gebruikt bij blokzoekopdrachtenattributen (optioneel object): behandelt de dynamische blokgegevensBewerk (functie): een functie die de opmaak retourneert die in de editor moet worden weergegevenopslaan (functie): een functie die de opmaak retourneert die aan de voorkant moet worden gerenderduseOnce (optionele boolean): beperk het blok om meerdere keren te worden toegevoegdondersteuningen (optioneel object): definieert door blokken ondersteunde functiesErvan uitgaande dat we JSX gebruiken voor blokontwikkeling, hier is wat een voorbeeld registerBlockType () oproep kan eruitzien als een heel eenvoudig blok:
registerBlockType ('my-unique-namespace / ultimate-block', title: __ ('The Best Block Ever', 'domain'), icon: 'wordpress', categorie: 'common', keywords: [__ ('sample ',' domein '), __ (' Gutenberg ',' domein '), __ (' blok ',' domein ')], bewerken: () => Welkom bij de Gutenberg-editor!
, opslaan: () => Hoe kijk ik aan de voorkant?
);Merk op hoe we geen invoer voor de Omschrijving, attributen, useOnce, en ondersteuningen eigenschappen? Alle velden die optioneel zijn (en niet relevant zijn voor uw blok) kunnen veilig worden weggelaten. Omdat dit blok bijvoorbeeld geen dynamische gegevens bevatte, hoeven we ons geen zorgen te maken over het opgeven van eventuele kenmerken.
Laten we nu de registerBlockType () configuratie-objecteigenschappen meer in detail een voor een.
Bij het invoegen of zoeken naar een blok in de editor, wordt de titel weergegeven in de lijst met beschikbare blokken.
Het wordt ook weergegeven in het venster Blokkeercontrole, samen met de blokbeschrijving indien gedefinieerd. Als de blokinspectie momenteel niet zichtbaar is, kunt u het tandwielpictogram in de rechterbovenhoek van de Gutenberg-editor gebruiken om zichtbaarheid in te schakelen.
Zowel de titel- als de beschrijvingsvelden moeten idealiter worden ingepakt in i18n-functies om vertaling naar andere talen mogelijk te maken.
Er zijn momenteel vijf blokcategorieën beschikbaar:
gemeenschappelijkopmaaklay-outwidgetsembedDeze bepalen het categoriegedeelte waarin uw blok wordt vermeld binnen de Voeg blok toe venster.
De Blocks tabblad bevat Gemeenschappelijke blokken, opmaak, Lay-outelementen, en widgets categorieën, terwijl de instortvoorzieningen categorie heeft een eigen tabblad.
Categorieën zijn momenteel vastgelegd in Gutenberg, maar dit kan in de toekomst worden gewijzigd. Dit zou bijvoorbeeld handig zijn als u meerdere blokken in een enkele plug-in zou ontwikkelen en u ze allemaal onder een gemeenschappelijke categorie zou willen plaatsen, zodat gebruikers ze gemakkelijker konden vinden.
Standaard krijgt uw blok het schild Dashicon toegewezen, maar u kunt dit overschrijven door een aangepast Dashicon op te geven in de icoon veld-.
Elke Dashicon wordt voorafgegaan door dashicons- gevolgd door een unieke reeks. Het tandwielpictogram heeft bijvoorbeeld de naam dashicons-admin-generic. Om dit als blokpictogram te gebruiken, verwijdert u gewoon de dashicons- voorvoegsel om te worden herkend, b.v.. pictogram: 'admin-generiek'.
U bent echter niet alleen beperkt tot het gebruik van Dashicons als pictogrameigenschap. De functie accepteert ook een JSX-element, wat betekent dat u elk beeld- of SVG-element kunt gebruiken als uw blokpictogram.
Zorg er wel voor dat de grootte van het pictogram overeenkomt met andere blokpictogrammen, standaard 20 x 20 pixels.
Kies maximaal drie vertaalbare zoekwoorden om uw blok te laten opvallen wanneer gebruikers naar een blok zoeken. Het is het beste om zoekwoorden te kiezen die nauw aansluiten bij de functionaliteit van uw blok voor de beste resultaten.
trefwoorden: [__ ('zoeken', 'domein'), __ ('voor', 'domein'), __ ('ik', 'domein'),]U kunt zelfs uw bedrijfsnaam en / of plugin-naam als zoekwoorden opgeven, zodat als u meerdere blokken heeft, gebruikers uw bedrijfsnaam kunnen typen en al uw blokken in de zoekresultaten worden weergegeven.
Hoewel het toevoegen van zoekwoorden volledig optioneel is, is dit een uitstekende manier om het voor gebruikers gemakkelijker te maken om uw blokken te vinden.
Attributen helpen bij het beheren van dynamische gegevens in een blok. Deze eigenschap is optioneel omdat u deze niet nodig hebt voor zeer eenvoudige blokken die statische inhoud uitvoeren.
Als uw blok echter te maken heeft met gegevens die kunnen veranderen (zoals de inhoud van een bewerkbaar tekstgebied) of als u blokinstellingen moet opslaan, is het gebruik van kenmerken de juiste keuze.
Attributen werken door dynamische blokgegevens op te slaan in de berichtinhoud die is opgeslagen in de database of in post-meta. In deze zelfstudie gebruiken we alleen kenmerken waarmee gegevens worden opgeslagen, samen met de inhoud van het bericht.
Als u attribuutgegevens wilt ophalen die zijn opgeslagen in post-inhoud, moeten we opgeven waar deze zich in de markup bevindt. We kunnen dit doen door een CSS-selector op te geven die verwijst naar de attribuutgegevens.
Als ons blok bijvoorbeeld een ankertag bevat, kunnen we het gebruiken titel veld als ons attribuut als volgt:
attributen: koppelingitle: source: 'attribute', selector: 'a', attribute: 'title'
Hier is de attribuutnaam linktitle, wat een willekeurige string is en kan alles zijn wat je maar wilt.
We kunnen dit kenmerk bijvoorbeeld gebruiken om de koppelingstitel op te slaan dat is ingevoerd via een tekstvak in blokinstellingen. Als u dit doet, wordt het titelveld ineens dynamisch en kunt u de waarde ervan in de editor wijzigen.
Wanneer het bericht is opgeslagen, wordt de kenmerkwaarde in de koppelingen ingevoegd titel veld. Evenzo, wanneer de editor is geladen, de waarde van de titel tag wordt opgehaald uit de inhoud en ingevoegd in de linktitle attribuut.
Er zijn meer manieren om te gebruiken bron om te bepalen hoe blokinhoud wordt opgeslagen of opgehaald via attributen. U kunt bijvoorbeeld de 'tekst' bron om de innerlijke tekst uit een alinea-element te extraheren.
attributen: paragraph: source: 'text', selector: 'p'
U kunt ook de kinderen bron om alle onderliggende knooppunten van een element in een array te extraheren en op te slaan in een attribuut.
attributen: editablecontent: source: 'children', selector: '.parent'
Hiermee selecteert u het element met klasse .ouder en slaat alle onderliggende knooppunten op in de editablecontent attribuut.
Als u geen bron opgeeft, wordt de kenmerkwaarde in HTML-opmerkingen opgeslagen als onderdeel van de berichtmarkering wanneer deze in de database wordt opgeslagen. Deze opmerkingen zijn verwijderd voordat het bericht aan de voorkant wordt weergegeven.
We zullen een specifiek voorbeeld van dit type attribuut zien wanneer we ons later in deze tutorial beginnen met het implementeren van ons willekeurige afbeeldingsblok.
Attributen kunnen even wennen zijn, dus maak je geen zorgen als je ze de eerste keer niet helemaal begrijpt. Ik raad aan om de attributensectie van het Gutenberg-handboek te bekijken voor meer details en voorbeelden.
De Bewerk functie bepaalt hoe uw blok in de editor-interface verschijnt. Dynamische gegevens worden doorgegeven aan elk blok rekwisieten, inclusief alle aangepaste kenmerken die zijn gedefinieerd.
Het is gebruikelijk om toe te voegen className = props.className naar het hoofdblokelement om een CSS-klasse uit te voeren die specifiek is voor uw blok. WordPress voegt dit niet voor u toe in de editor, dus moet het voor elk blok handmatig worden toegevoegd als u het wilt opnemen.
Gebruik makend van props.className is de standaardpraktijk en wordt aanbevolen omdat het een manier biedt om CSS-stijlen aan te passen voor elk afzonderlijk blok. Het formaat van de gegenereerde CSS-klasse is .wp-blok- namespace - naam. Zoals u kunt zien, is dit gebaseerd op de bloknaamruimte / naam en is het ideaal om als unieke blokidentificatie te worden gebruikt.
Voor de bewerkingsfunctie moet u geldige markeringen retourneren via de render () methode, die vervolgens wordt gebruikt om uw blok in de editor weer te geven.
Vergelijkbaar met de Bewerk functie, opslaan geeft een visuele weergave van uw blok maar aan de voorkant. Het ontvangt ook dynamische blokgegevens (indien gedefinieerd) via rekwisieten.
Een belangrijk verschil is dat props.className is niet beschikbaar binnen opslaan, maar dit is geen probleem omdat het automatisch wordt ingevoegd door Gutenberg.
De ondersteuningen eigenschap accepteert een object met Booleaanse waarden om te bepalen of uw blok bepaalde kernfuncties ondersteunt.
De beschikbare objecteigenschappen die u kunt instellen, zijn als volgt.
anker (standaard false): hiermee kunt u rechtstreeks naar een specifiek blok linkencustomClassName (waar): voegt een veld in het blokinspector toe om een aangepast te definiëren naam van de klasse voor het blok naam van de klasse (waar): voegt een toe naam van de klasse naar het blok-rootelement op basis van de bloknaamhtml (waar): hiermee kunt u de blokmarkering rechtstreeks bewerkenuseOnce EigendomDit is een nuttige eigenschap waarmee u kunt instellen dat een blok meer dan eens aan een pagina wordt toegevoegd. Een voorbeeld hiervan is de kern Meer blok, dat niet aan een pagina kan worden toegevoegd als het al aanwezig was.
Zoals je kunt zien, eenmaal de Meer blok is toegevoegd, het blokpictogram is grijs en kan niet worden geselecteerd. De useOnce eigenschap is ingesteld op vals standaard.
Het is nu tijd om de kennis die we tot nu toe hebben opgedaan, te gebruiken om een degelijk werkend voorbeeld van een blok te implementeren dat iets interessanters doet dan alleen statische inhoud uitvoeren.
We bouwen een blok om een willekeurig beeld dat is verkregen via een extern verzoek uit te voeren naar de PlaceIMG-website, die een willekeurige afbeelding retourneert. Bovendien kunt u de categorie afbeeldingen selecteren die wordt geretourneerd via een selectieknop voor vervolgkeuzelijsten.
Voor het gemak zullen we ons nieuwe blok hieraan toevoegen my-maat-block plugin, in plaats van een geheel nieuwe plug-in te maken. De code voor het standaardblok bevindt zich in de / Src / block map, dus voeg binnen een andere map toe / src riep random-image en voeg drie nieuwe bestanden toe:
Als alternatief zou je de kunnen kopiëren / Src / block map en hernoem het als u niet alles handmatig wilt typen. Zorg echter wel voor hernoemen block.js naar index.js in de nieuwe block-map.
We gebruiken index.js voor de bestandsnaam van het hoofdblok, zodat we de importverklaring binnenin kunnen vereenvoudigen blocks.js. In plaats van het pad en de volledige bestandsnaam van het blok op te nemen, kunnen we alleen het pad naar de blokmap opgeven, en importeren zal automatisch zoeken naar een index.js het dossier.
Doe open /src/blocks.js en voeg een verwijzing toe naar ons nieuwe blok bovenaan het bestand, direct onder de bestaande importinstructie.
import './random- image';
Binnen /src/random-image/index.js, voeg de volgende code toe om ons nieuwe blok te starten.
// CSS importeren. import './style.scss'; import './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; registerBlockType ('cgb / block-random-image', title: __ ('Random Image'), icon: 'format-image', categorie: 'common', keywords: [__ ('random'), __ (' afbeelding ')], bewerken: functie (rekwisieten) ga terug ( Willekeurig beeldblok (editor)
); , opslaan: functie (rekwisieten) terug ( Willekeurig beeldblok (voorkant)
); );Dit stelt het raamwerk van ons blok in en is redelijk vergelijkbaar met de boilerplate-blokcode gegenereerd door de create-Guten-block toolkit.
We beginnen met het importeren van de editor- en front-end stylesheets en daarna extraheren we een aantal veelgebruikte functies wp.i18n en wp.blocks in lokale variabelen.
Binnen registerBlockType (), waarden zijn ingevoerd voor de titel, icoon, categorie, en trefwoorden eigenschappen, terwijl de Bewerk en opslaan functies sturen momenteel alleen statische inhoud uit.
Voeg het willekeurige afbeeldingsblok toe aan een nieuwe pagina om de uitvoer te zien die tot nu toe is gegenereerd.
Zorg ervoor dat u nog steeds bestanden bekijkt voor wijzigingen zodat elke blokbroncode (JSX, ES6 +, Sass, etc.) wordt omgezet in geldige JavaScript en CSS. Als u momenteel geen bestanden bekijkt voor wijzigingen, opent u een opdrachtregelvenster binnen de my-maat-block plug-in root-map en voer in npm start.
Je vraagt je misschien af waarom we geen PHP-code hoefden toevoegen om extra blokscripts in te huren. De blokscripts voor de my-maat-block blok wordt in de wacht gezet via init.php, maar we hoeven geen scripts speciaal in te huren voor ons nieuwe blok, aangezien dit voor ons wordt verzorgd door create-Guten-block.
Zolang we ons hoofdblokbestand importeren in src / blocks.js (zoals we hierboven deden) dan hoeven we geen extra werk te doen. Alle JSX, ES6 + en Sass-code worden automatisch in de volgende bestanden gecompileerd:
Deze bestanden bevatten JavaScript en CSS voor alle blokken, dus er hoeft slechts één set bestanden in de wachtrij te worden geplaatst, ongeacht het aantal gemaakte blokken!
We zijn nu klaar om een beetje interactiviteit toe te voegen aan ons blok, en we kunnen dit doen door eerst een kenmerk toe te voegen om de afbeeldingscategorie op te slaan.
attributen: category: type: 'string', standaard: 'nature'
Hiermee wordt een kenmerk gemaakt met de naam categorie, die een string opslaat met een standaardwaarde van 'natuur'. We hebben geen locatie in de opmaak opgegeven om de kenmerkwaarde op te slaan en op te halen, dus speciale HTML-opmerkingen worden in plaats daarvan gebruikt. Dit is het standaardgedrag als u een attribuutbron weglaat.
We hebben een manier nodig om de beeldcategorie te wijzigen, wat we kunnen doen via een select uitrolbesturingselement. Werk het Bewerk functioneren als volgt:
edit: function (props) const attributes: category, setAttributes = rekwisieten; function setCategory (event) const selected = event.target.querySelector ('option: checked'); setAttributes (category: selected.value); event.preventDefault (); terug ( De huidige categorie is: category ); Hier is hoe het eruit zal zien:
Dit is heel anders dan de vorige static Bewerk functie, dus laten we de wijzigingen doornemen.
Eerst hebben we een select-uitklapbesturingselement toegevoegd met verschillende keuzes die overeenkomen met de afbeeldingscategorieën die beschikbaar zijn op de PlaceIMG-site.
Wanneer de drop-downwaarde verandert, de setCategory functie wordt aangeroepen, die de momenteel geselecteerde categorie vindt en vervolgens op zijn beurt de setAttributes functie. Dit is een kernfunctie van Gutenberg en werkt een attribuutwaarde correct bij. Het wordt aanbevolen dat u alleen een kenmerk bijwerkt met deze functie.
Wanneer een nieuwe categorie wordt geselecteerd, wordt de attribuutwaarde bijgewerkt en wordt deze terug in de Bewerk functie, die het uitvoerbericht bijwerkt.
We moeten nog een laatste stap voltooien om de willekeurige afbeelding weer te geven. We moeten een eenvoudig onderdeel maken dat de huidige categorie bevat en een resultaat oplevert
Het verzoek dat we moeten doen aan PlaceIMG heeft de vorm: https://placeimg.com/[width]/[height]/[category]
We houden de breedte en hoogte voor nu op een vaste plek, dus we hoeven alleen de huidige categorie aan het einde van de aanvraag-URL toe te voegen. Bijvoorbeeld als de categorie was 'natuur' dan zou de volledige aanvraag-URL zijn: https://placeimg.com/320/220/nature.
Voeg een ... toe RandomImage component hierboven registerBlockType ():
functie RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; terugkeer;
Om het te gebruiken, voegt u het toe aan de bewerkingsfunctie en verwijdert u het statische uitvoerbericht. Terwijl we bezig zijn, doe hetzelfde voor de opslagfunctie.
De volledige index.js bestand zou er nu als volgt uit moeten zien:
// CSS importeren. import './style.scss'; import './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; functie RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; terugkeer); , opslaan: function (props) const attributes: category = rekwisieten; terugkeer (
Voeg ten slotte (voorlopig) de volgende stijlen toe aan editor.scss om een gekleurde rand rond de afbeelding toe te voegen.
.wp-block-cgb-block-random-image selecteer opvulling: 2px; marge: 7px 0 5px 2px; grensradius: 3px;
Je hebt ook een aantal stijlen nodig style.css.
.wp-block-cgb-block-random-image background: # f3e88e; kleur: #fff; rand: 2px vast # ead9a6; grensradius: 10px; opvulling: 5px; breedte: -webkit-fit-inhoud; breedte: -moz-fit-inhoud; breedte: fit-inhoud; img border-radius: erven; rand: 1px gestippeld # caac69; weergave: raster;
Wanneer de pagina wordt vernieuwd in de editor of op de voorkant, wordt een nieuwe willekeurige afbeelding weergegeven.
Als dezelfde afbeelding steeds opnieuw wordt weergegeven, kunt u een harde verversing uitvoeren om te voorkomen dat de afbeelding wordt weergegeven in de cache van uw browser.
In deze tutorial hebben we heel wat terreinen behandeld. Als je helemaal klaar bent, geef jezelf dan een welverdiende schouderklopje! Gutenberg-blokontwikkeling kan heel leuk zijn, maar het is zeker een uitdaging om elk concept bij de eerste blootstelling te begrijpen.
Onderweg hebben we geleerd om blokscripts en -stijlen in te huren en de registerBlockType () functie in de diepte.
We hebben dit opgevolgd door theorie in de praktijk te brengen en een aangepast blok vanuit het niets te maken om een willekeurige afbeelding van een specifieke categorie weer te geven met behulp van de PlaceIMG-webservice.
In het volgende en laatste deel van deze zelfstudiereeks voegen we meer functies toe aan ons willekeurige afbeeldingsblok via het instellingenpaneel in de blokinspecteur..
Als je deze zelfstudie hebt gevolgd en gewoon wilt experimenteren met de code zonder alles in te voeren, kun je de laatste versie downloaden my-maat-block plugin in de volgende tutorial.
