Skapa anpassat Gutenberg-block – Del 4: Attribut

I den här delen ska vi titta på hur man definierar attribut, hämtar deras värden och uppdaterar dem. Med attribut kan vi acceptera input från editorn, spara den och mata ut den hur vi vill. I föregående steg tittade vi på WordPress-komponenter, var man hittar dem och hur man implementerar dem. I det här inlägget kommer vi att lägga till rekvisita för att göra kopplingen till attribut – den sparade informationen.

Definiera attribut

Attribut läggs till som objekt i en array till attributesegenskapen i registerBlockType(). Varje attributs nyckel är attributnamnet, och du måste ha egenskapen typesom ett minimum.

Fastigheten typekan vara något av följande; null, boolean, object, array, number, string, eller integer.

Du kan valfritt tillhandahålla egenskapen defaultför att definiera startvärdet för ditt attribut. Om du inte anger en standard kommer attributet att vara som standard null.

Ett annat attribut egenskap är sourcesom fungerar tillsammans med selectoregenskapen, men det här är knepiga saker som vi kommer att titta på i detalj längre ner nedan.

Till exempel att definiera två attribut; exampleTextsom sträng och postIdssom en array skulle se ut så här:

Allt du behöver sparat för ditt block (indata från användaren/redigeraren) kräver ett attribut. Det är upp till dig hur du strukturerar dina data, genom att definiera separata attribut för varje eller samla ihop dem i ett objekt. Det kommer bara att vara en skillnad i hur du hämtar deras data och hur du uppdaterar dem.

Hämta attributvärden

Attribut finns som rekvisita till dina block editoch savefunktioner. Om du har följt denna serie från föregående steg, kom ihåg att vi uppdaterade funktionerna för att skicka rekvisita som parameter.

Det är vanligt att destrukturera attribut från rekvisita eftersom du vanligtvis hänvisar till dem ofta. Att till exempel mata ut ett anropat attribut exampleTextskulle se ut så här:

Uppdaterar attributvärden

För att uppdatera attribut har vi en metod tillgänglig i rekvisita, kallad setAttributes(). Denna funktion accepterar ett objekt där du kan lägga till alla attribut du vill uppdatera. Du kan bara uppdatera ett attribut, flera eller alla samtidigt. Om du har flera attribut definierade och kräver setAttributes()att endast uppdatera ett av dem, berörs inte de andra.

Om du har erfarenhet av React kommer du förmodligen omedelbart att känna igen likheter mellan setAttributes()och setState(). De fungerar exakt likadant, men skillnaden är att tillståndet i React bara är något som lagras lokalt i den komponenten, och attribut sparas faktiskt som data utanför komponenten.

För att uppdatera ett attribut, skulle du vanligtvis förstöra funktionen från rekvisita, och kalla det så här: Nedan uppdaterar vi exampleTextattributet till "Hej".

const { setAttributes } = props;
setAttributes({ exampleText: 'Hi' });

Naturligtvis skulle du köra setAttributes()inifrån någon handling. Ett vanligt exempel är inuti onChangerekvisiten på något slags inmatningsfält som används för att lagra värdet på exampleTextattributet.

Se till att spara attribut i den typ du har definierat på attributet. Du kommer inte ha någon tur när du försöker spara objekt i ett strängattribut till exempel.

Låt oss prova det i praktiken! Initiera npm run startom du inte redan har gjort det.

Visa ett attribut i en anpassad textinmatning och uppdatering av attributets värde

I föregående steg lade vi till några komponenter i editt.ex. en textinmatning, men ingenting lagrades. Låt oss lägga till ett attribut och en textinmatning för det i vårt block. Vi kommer både att se till att textinmatningen visar det aktuella värdet, och närhelst inmatningen ändras uppdaterar vi attributet.

Lägga till textinmatningen och dess onChangerekvisita

Vi destrukturerar attributesoch setAttributeskommer propsatt använda båda. Sedan använder vi en TextControlkomponent från WordPress wp.componentspaket. Vi skickar två rekvisita till den; valuekommer att ställa in ingångens värde (både initialt och medan vi skriver) och en åtgärd på ingångens händelse onChange.

I valueställer vi in ​​det till värdet av vårt attribut; attributes.exampleText. I onChangehändelse av att vi kör en funktion som skickar det inskrivna värdet på vår indata som parameter, newtext(ingångsvärdet är en prop som returneras från komponenten). I den funktionen anropar setAttributes()och uppdaterar vi attributet exampleTexttill det som skrevs in i inmatningen.

Detta är grundläggande React – förutom att vi arbetar med attribut och inte stat. Om ovanstående förvirrade dig rekommenderar jag att du tittar på en snabb handledning i React, eftersom dessa förmodligen kommer att förklara detta bättre än mig!

Uppdatera din editor och se hur blocket fungerar! Du bör få en vanlig textinmatning för att skriva saker i, och den kommer att sparas när du trycker på Spara/Uppdatera i postredigering.

Resultatet i frontend och i databasen

Om du tittar på ditt inlägg i frontend bör det fortfarande eka en div med ":)" eftersom det är vad vi fortfarande har i vår savefunktion. Men något har hänt bakom kulisserna! Vårt blocks kommentarblock innehåller nu värdet av vårt attribut i JSON.

Du kan inte se kommentarsblocken i en mall som gör ett normalt the_content()anrop. För att se kommentarsblocken har du två alternativ. Titta antingen på post_contenttabellen i postdatabasen. Eller lägg echo get_the_content()till mallen och titta på den i Inspect/debugging tool.

Uppenbarligen har vi tillgång till attributen i saveockså, från rekvisita.

Visar ingångens värde isave

Låt oss visa värdet på attributet inuti en div i vår savefunktion:

Obs: När du har gjort denna ändring kommer du att få ett brutet block i inlägget du redan har lagt till detta block till. Detta händer eftersom redaktören möter en annan utdata saveän vad vi har definierat nu. Ta bort blocket och lägg till det igen. Ange något i din textinmatning, uppdatera inlägget och visa det i frontend.

Och detta är faktiskt kärnan i det. Du bestämmer vilka attribut du behöver för att spara det du vill ha i ditt block. I editkommer du att återge sätt för användaren att mata in, se till att de aktuella värdena visas och uppdatera dem när de ändras. Och i saveextraherar du de sparade attributen och återger utdata som du vill.

Vi kommer att beröra många fler olika komponenter och attribut när vi går i denna handledningsserie. Men låt oss titta på en annan komponent i det här inlägget för att se vad attributet egenskap sourcehandlar om.

RichText och attributegenskapensource

WordPress- RichTextkomponenten ger dig ett "kantfritt" textområde med stöd för textformatering. Du kanske föredrar att använda detta istället för en (ful?) standardtextinmatning eller textområde. Men tänk på att det RichTextmåste hanteras lite annorlunda eftersom det finns flera rekvisita du måste vara medveten om, och det är skillnad på hur vi får tag i värdet i vår savefunktion.

Lägga till en RichTextkomponent

Den enklaste formen av RichTextär att implementera det som du skulle göra med en textinmatning:

Vi destrukturerar RichTextkomponenten från wp.blockEditorpaketet, men i övrigt är ovanstående identisk med vad vi gjorde med standardtextinmatningen.

Hantering savemedRichText

Men i savefunktionen måste du använda RichTextkomponenten igen för att få värdet på attributet. Vi anropar RichText.Contentoch ställer in rekvisitan valuetill vårt attribut:

Detta kommer att mata ut vad som än skrevs i RichTextin-redigeraren direkt utan någon HTML-kod.

När du arbetar med RichTextvill du troligen styra HTML-omslaget runt texten, till exempel a <p>eller a <h2>, både i frontend och i editor. För det kan vi använda en rekvisita som heter tagName.

Komponenten RichTexttillåter flera andra rekvisita också. Du kan definiera en platshållartext som visas (blekas) när den är tom med placeholderrekvisitan. Komponenten låter dig också styra vilka formateringsalternativ fältet tillåter (vilka knappar det visar i verktygsfältet).

RichTextmedtagName

Med propen tagNamekan du fördefiniera vilken HTML-tagg dess utdata ska lindas in i. När du använder tagNamebör du använda samma tagNameprop och värde i både editoch save.

Säg att du vill sätta ditt attributvärde i en <h2>, som i editorn tvingar all indata att vara en h2. I editkan du göra:

Och i save:

Ovanstående kommer nu att mata ut vad som än skrevs i RichTextområdet inuti en <h2>tagg.

Använder sig avsource

Självklart kan du kombinera flera richtext för ett block, till exempel en för rubrik och en för ett stycke. Kom bara ihåg att var och en kommer att behöva sin egen egenskap. Till exempel:

Men du kommer nu att börja stöta på några problem. Även om du kan göra textformatering i editorn, kommer ingenting (eller en del) av din formatering att sparas. När du tittar på inlägget i frontend kommer det helt enkelt ut som h2och en p, utan någon formatering du har gjort (kursiv, fetstil, länk). Inte ens kommentarblocket för ditt block innehåller formateringen. Det här är det knepiga med RichText. För att lösa detta måste vi arbeta med attributet egenskap source.

Egenskapen sourcesom tillåter WordPress att extrahera och tolka innehållet direkt från inläggets innehåll. Om ett attribut inte har någon sourceinställning, kommer det att sparas i och extraheras från HTML-kommentarblocket.

När vi arbetar med RichTextställer vi vanligtvis in sourcepå html, som använder WordPress bibliotek för att analysera HTML-uppmärkning. Egenskapen sourcefungerar tillsammans med ett annat attribut egenskap; selectorsom definierar vilken HTML-tagg den ska extraheras från.

Som ett exempel ställer vi in source​​som htmli vårt stycke RichText, och ställer in selectorsom p(annars är det förinställt att roten av blocket blockeras).

attributes: {
    ...
    myRichText: {
        type: 'string',
        source: 'html',
        selector: 'p'
    }
},

Nu bör vår andra RichTextframgångsrikt spara all textformatering. Du kommer också att märka att kommentarsblocket nu bara visar myRichHeadingattributet i JSON. Attributet myRichTexthar helt försvunnit från kommentarsblocket. Detta beror på att med sourceWordPress nu analyserar inläggets innehåll istället för kommentarsblocket för attributvärdet.

För att vara helt ärlig har jag inte jobbat så mycket med sourceattributet alls och skulle rekommendera att undvika det om du kan. WordPress dokumentation förklarar lite mer om källa och attribut för att du vill kolla upp det själv.

I det här inlägget har vi lärt oss grunderna om attribut; hur man definierar dem, uppdaterar dem och matar ut deras värden. I nästa steg kommer vi att titta på fler olika komponenter och hur man lägger till inställningar utanför själva blockinnehållet; i verktygsfältet och editorns sidofält (kallas Inspektör).