Har du någonsin hamnat i situationen där du vill lägga till dina anpassade inställningar i WordPress Gutenberg-block? I det här inlägget kommer vi att gå in i detalj på hur man gör det. Du hittar två exempelkoder på verkliga användningsfall för att lägga till anpassade inställningar till WordPress-block.

Tänk på att eftersom Gutenberg-blocken är Javascript kräver ändring av dem att du skriver koden i Javascript. Precis som WordPress PHP-kod har krokar och filter som gör att tema- eller plugin-utvecklare kan modifiera sin kod, finns det även filter i WordPress Javascript-kod. På samma sätt som PHPs [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()funktion har vi Javascript-funktionen [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

Jag kommer att skriva koden i Javascript ES6-syntax, vilket kräver en kompilator för att transformera den. Du kan skriva i ES5-syntax men jag rekommenderar att du går för ES6/ESNext. Jag har ett inlägg som förklarar hur man ställer in en transformator för ES6/ESNext. Jag antar också att du har en viss förtrogenhet med React/JSX, möjligen viss erfarenhet av hur du skapar dina egna anpassade Gutenberg-block.

Vad du kan filtrera på Gutenberg-block

Det finns inte mycket dokumentation i tillgängliga Gutenberg-krokar och filter. Men i syfte att lägga till anpassade inställningar och på något sätt tillämpa dem på befintliga block; det här är vad jag har hittat hittills. Jag har fokuserat på att lägga till enkla inställningar – inte operationer som kräver drastiska komponentändringar eller komplext beteende.

Det finns tre steg för att lägga till anpassade inställningar till befintliga block:

Vi lägger till ett filter på befintliga blocks [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)inställningar. Detta tillåter oss att lägga till nya attribut till attributesarrayen, vilket gör att vi kan spara ytterligare information i blocket. Vi måste spara vår anpassade inställning någonstans.
Haka fast på blockets editkomponent (komponenten som ansvarar för att rendera blocket i editorn). I denna krok kan vi haka på Inspector (sidofältet) och lägga till våra egna komponenter. Vi kan antingen lägga till en ny sektion/panel, eller så kan vi haka på avsnittet "Avancerat" som alltid finns i alla block. Sedan är det upp till oss att rendera inställningsingångar, såsom textinmatningar, kryssrutor eller vad som helst.
Filtrera blockets saverekvisita. Vi kan justera rekvisitan för spara, som är ansvarig för att både spara blocket och rendera det i frontend (utanför editorn). I vårt fall vill vi lägga till en klass eller inline-stil.

Vi kan rikta in oss på specifika block eller rikta in oss på alla. Vi har alltid tillgång till vilken typ av block vi befinner oss på.

För att säga det med andra ord: Vi lägger till några anpassade inställningar i Inspector och sparar det i anpassade attribut som vi har lagt till i blocket. Vi kan sedan påverka blockets klassnamn eller inline-stil (i vissa fall), beroende på de sparade attributen. Med de anpassade klassnamnen kan vi enkelt lägga till anpassad CSS som visuellt ger våra inställningar en effekt.

Vad kan vi inte göra (för nu?)

Tyvärr finns det vissa saker vi inte kan komma åt med filter på befintliga block. När det gäller att lägga till enkla anpassade inställningar till block är dessa vanliga saker vi inte kan påverka.

Ingen åtkomst till blockets inline-stil i editorn

I kommande fall av inställningar som påverkar ett blocks design måste vi lägga till inline-stil på blockets omslutningsnod. Bara klassnamn duger inte. Om du till exempel lägger till en anpassad färginställning och användaren väljer en anpassad färg (från colorpicker), kan du inte lösa detta genom att lägga till en klass – du behöver inline stil.

Tyvärr verkar det som att WordPresss standardblock hanterar inline-stil i editor helt oberoende utan möjlighet att filtrera eller "haka in". Jag kommer att visa ett sätt att kringgå detta i det sista exemplet nedan, men det är inte idealiskt i alla fall.

Varför bry sig om att blocket ser annorlunda ut i editor kontra frontend, kanske du frågar? Hela poängen med Gutenberg är att implementera ett visuellt sätt att redigera innehåll där det vi ser faktiskt är vad vi får. Vi vill uppnå samma visuella utseende både i editor och frontend.

Vissa block inkluderar inte klassnamn i editorn

Som nämnts ovan kan vi filtrera blockets inpackningsklassnamn eftersom detta är en rekvisita som skickas till alla Gutenberg-block. Men tyvärr finns det några block som inte tillämpar blockets klass alls i edit. Ett exempel är täckblocket. Jag har lekt runt mycket med att använda omslagsblock som "sektioner" för förstasidor och stöter på problem eftersom omslagsblocket bygger sin egen klass inuti edit. Den hoppar helt över blockets "globala" klass (som är den vi har tillgång till via filter).

Men vi kan åtminstone vara säkra på att filtrerade klassnamn alltid tillämpas i save(frontend). Detta sker automatiskt utanför varje blocks specifika kod.

Om jag har fel om något av ovanstående, Vänligen meddela mig i kommentarerna nedan! Jag lär mig ständigt Gutenberg, och samtidigt utvecklas Gutenberg också. Jag hoppas någon gång ovanstående kommer att vara möjligt någon gång eller att det är möjligt men jag saknar bara lite viktig information!

Med det ur vägen, låt oss börja titta på lite kod.

Exempel 1: Lägg till ett växlingsfält för att dölja ett täckblock på mobilen

Låt oss anta att vi utvecklar ett tema där omslagsblock kommer att användas för "sektioner" på förstasidan. Och vi vill ge användaren en möjlighet att dölja en viss sektion från mobilen. För att lösa detta kan vi lägga till ett växlingsfält i avsnittet "Avancerat" i Cover blocks Inspector. Om fältet är aktiverat kommer Cover-blocket att få en extra anpassad klass som vi kan rikta in oss på med CSS och mediafrågor.

Förresten: Detta är ett fall där problemet med Cover block inte tillämpar våra anpassade klassnamn i editorn faktiskt är en fördel! Tänk om det gjorde det; då skulle det vara omöjligt för användaren att redigera blocket i editorn om han eller hon har en liten skärm!

Som nämnts tidigare finns det tre steg vi behöver koda för. Vi måste också lägga till lite PHP för att köa vår Javascript-fil till redigeraren. Låt oss göra det först.

Lägger till vårt manus i editorn

Vi kopplar en funktion till handlingen [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Inuti vår funktion köar vi ett script, precis som vi brukar göra i wp_enqueue_scriptshook.


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Kom ihåg att justera sökvägen till var ditt manus är! Obs: Om du skriver i ES6 med webbpaket som kompilerar ditt Javascript, kom ihåg att ställa in sökvägen till byggandet av ditt skript, inte källan.

Jag gillar att lägga till ‘ wp-edit-post‘ som ett beroende till skriptet för att säkerställa att det laddas tillräckligt sent.

Det är allt PHP vi behöver göra. Resten skrivs i vår Javascript-fil.

Lägg till ett anpassat attribut

Det första filtret vi kommer att använda är blocks.registerBlockTypevilka filters registerBlockTypeinställningsobjekt.

Men först lite om att lägga till filter i Javascript. Eftersom jag inte hittat någon bra dokumentation för detta så ska jag förklara det lite här. Funktionen addFilterfinns i wp.hooksnamnutrymmet och accepterar fyra argument.

addFilter('hookName', 'namespace', 'functionName', 'priority');

Den första parametern, ‘hookName’, är namnet på filtret vi vill haka på. Detta motsvarar den första parametern när du använder PHP:s add_filter(). Den andra parametern, ‘namespace’, är ett anpassat namnområde för din kod. Detta är bara för att undvika namnkollision. Du kan i stort sett ställa in vad du vill här, använd bara inte WordPress namnutrymme (‘wp’). Använd en kort form av ditt namn eller projektnamn. Den tredje parametern, ‘functionName’, är den kopplade funktionen – vilket är samma som PHP: add_filter()s andra argument. Och slutligen är den fjärde parametern, ‘prioritet’, valfri. Återigen, detta är detsamma som PHPs add_filter()tredje argument.

Processen för filter i Javascript är densamma som i PHP. Vi definierar en funktion som behöver returnera den filtrerade variabeln. Ibland är variabeln en sträng, ett objekt eller en komponent. Inuti funktionen modifierar vi variabeln som vi tycker passar.

I vårt fall vill vi lägga till ett nytt attribut till blockets attributeobjekt. Vi anropar det nya attributet hideOnMobileoch ställer in dess typ till boolean. Detta görs så här:


function addCoverAttribute(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/cover') {
            settings.attributes = Object.assign(settings.attributes, {
                hideOnMobile: {
                    type: 'boolean',
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/cover-custom-attribute',
    addCoverAttribute
);

På linjen #3ser vi till att endast rikta oss mot block av typen ‘ core/cover‘. Det andra argumentet att blocks.registerBlockTypefiltrera är lämpligt nog blockets namn. Vi lägger sedan till ett nytt objektobjekt till settings.attributesobjektet. Slutligen ser vi till att returnera den filtrerade variabeln, settings.

Vid denna tidpunkt har ingenting förändrats visuellt i Gutenberg. Men alla täckblock har nu ytterligare ett attribut som vi kan använda för att lagra vår inställning.

Lägg till inställning i Inspector (avancerad panel)

Det andra filtret anropas editor.BlockEditoch filtrerar blockets editkomponent. Detta filter tar emot det ursprungliga blockets BlockEditkomponent och returnerar en ny inpackad komponent. Vi måste använda wp.compose.createHigherOrderComponentför att returnera den inslagna komponenten.

Inuti vår komponent ser vi till att göra den inslagna komponenten BlockEdit, oavsett. Men om blocket är av typen Cover så hakar vi även fast på komponenten InspectorAdvancedControls(som är panelen "Advanced" i Inspector) och lägger till en ToggleControl. Vi skriver för ToggleControlatt visa värdet på och uppdatera det anpassade attributet som vi lade till tidigare, hideOnMobile.

Glöm inte att alltid lämna tillbaka originalet BlockEdit, vilket vi gör på linjen #9. På rad #10 kontrollerar vi om blockets typ är Cover, och renderar InspectorAdvancedControlskomponenten. Inuti här lägger vi till en ToggleControl, som är en ingångskontroll som visas som en växling mellan sant eller falskt. Vi sätter en etikett och kopplar dess värde till hideOnMobileattributet. Om du har lagt till inställningar i Inspector tidigare borde detta vara ganska enkelt för dig.

Med ovanstående kod bör vi nu få detta inuti panelen "Avancerat" i Inspector on Cover blocks:

Inmatningen kommer nu att uppdatera vårt anpassade attribut hideOnMobile. Det sista steget är att göra något beroende på värdet av detta attribut. Från och med nu är attributet sparat, men det påverkar faktiskt ingenting.

Lägg till en anpassad klass

Det sista steget är att lägga till en anpassad klass i blockets klass. Vi gör detta med filtret blocks.getSaveContent.extraProps. Detta filter påverkar rekvisitan till blockets savekomponent. En av dem är propen className, som alltid kommer att tillämpas på frontend. Vi lägger helt enkelt till vår anpassade klass efter den om attributet var true, och returnerar den sedan. Jag har bestämt mig för att lägga till en klass ‘ hide-on-mobile‘, men du kan kalla den vad du vill.

Den här koden är ganska självförklarande. På raden #4kontrollerar vi om attributet hideOnMobilefinns och är true. Om så är fallet lägger vi till en anpassad klass till classNamesträngen.

Med alla ovanstående tre filter bör vi nu få en anpassad klass "göm-på-mobil" applicerad på vårt Cover-block närhelst inställningen är aktiverad.

Allt som återstår är att lägga till lite CSS till ditt temas frontend-stilmall. Något som det här;


.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
    .wp-block-cover.hide-on-mobile { display: block; }
}

Exempel 2: Lägg till Inspector-panel med anpassad bakgrundsfärgsinställning för Spacer-block

För det andra användningsfallet vill vi lägga till anpassade färginställningar till Spacer-blocket. Som standard har Spacer-blocket inga andra inställningar än dess höjd. Låt oss anta att vi vill lägga till en bakgrundsfärg som färgar Spacer-blockets fulla höjd. Det gör att användaren kan lägga till tomma, färgade "ränder" i sitt innehåll. I det här fallet vill vi lägga till färginställningarna i sin egen separata panel i Inspector, enligt vanligt förväntat beteende för färginställningar.

Obs: Att hantera färger är lite mer komplicerat eftersom vi behöver använda en (annan) högre ordningskomponent withColors. Eftersom vi redan behöver implementera en högre ordningskomponent i editor.BlockEditvi behöver composeflera komponenter. Dessutom måste vi lägga till två attribut för varje färginställning. En kommer att innehålla färgpalettens slug, och den andra kommer att innehålla hex-färgkoden – endast om användaren har valt en anpassad färg (använt colorpicker). Allt detta är vanligt beteende när man arbetar med withColors. Jag har ett <a href="https://wordpress.mediadoma.com/sv/hur-man-laegger-till-faerginstaellningar-i-ditt-anpassade-gutenberg-block/" title="inlägg som förklarar att lägga till färginställningar och withColorsi detalj” >inlägg som förklarar att lägga till färginställningar och withColorsi detalj om du blir förvirrad.

För det andra kommer vi i detta fall att stöta på problemet som förklaras ovan; där vi inte kan lägga till lämplig inline-stil till redigeraren. Lösningen jag har valt i det här fallet är att linda Spacer-blocket inuti a divi editorn och tillämpa rätt klasser och inline-stil på omslaget div. Detta gör den valda färgen synlig i editorn när blocket är avmarkerat. När du väljer blocket lägger WordPress dock till sin egen anpassade ljusgrå bakgrund till blocket, som täcker vår anpassade bakgrundsfärg. En CSS till editorn kommer att fixa detta. Jag ska förklara mer i slutet.

Stegen är desamma som exemplet ovan. Vi köar vårt skript till editorn i PHP först. Sedan i Javascript filtrerar vi attributesobjektet, Spacers editkomponent och slutligen Spacers savekomponent.

Lägger till vårt manus i editorn


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Kom ihåg att justera sökvägen till ditt skript. Jag gillar att lägga till ‘ wp-edit-post‘ som ett beroende till skriptet för att säkerställa att det laddas tillräckligt sent.

Det är allt PHP vi behöver göra. Resten skrivs i vår Javascript-fil.

Lägg till anpassade attribut

Som i exemplet ovan lägger vi till ett filter blocks.registerBlockTypeför att lägga till ytterligare objektobjekt till blockets attributesobjekt.

När vi arbetar med withColorsmåste vi lägga till två attribut för varje färg. Namnet på vårt bakgrundsfärgattribut är backgroundColor, vilket betyder att det andra attributet måste namnges customBackgroundColor. Allt detta förklaras i mitt inlägg om hantering av färginställningar i Gutenberg. Båda bör vara av typen string och endast tillämpas på block av typen Spacer.


function addSpacerAttributes(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/spacer') {
            settings.attributes = Object.assign(settings.attributes, {
                backgroundColor: {
                    type: 'string',
                },
                customBackgroundColor: {
                    type: 'string'
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/spacer-background-attribute',
    addSpacerAttributes
);

Lägg till panelen ColorSettings i Inspector

Det andra steget är att lägga till en färginställningspanel i Inspector för Spacer-blocket genom att filtrera editor.BlockEdit.

Vi måste använda composeför att kombinera den högre ordningens komponent som returneras från detta filter och withColors. Med andra ord, vi lindar helt enkelt den returnerade komponenten i withColors. Som parameter withColorstillhandahåller vi vårt attribut backgroundColor.

Inuti den lindade komponenten ser vi till att alltid återvända BlockEdit(linje #9och #39för Spacer-block). För block av typen Spacer hakar vi även på InspectorControlsför att lägga till en PanelColorSettingsför vårt färgval. Detta är standardproceduren för att lägga till färginställningar.

På line #17 - 34genererar vi manuellt den nödvändiga klassen och/eller inline-stilen. Sedan #38lägger vi till en omslutande div BlockEditmed dessa klasser och inline-stilar.

Resultatet är en ny färginställningspanel i Inspector för Spacer-block, fullt fungerande.

Att välja en palettfärg eller en anpassad färg kommer verkligen att påverkas i omslutnings-div i editorn. Men du kan bara se det när du avmarkerar Spacer-blocket!

Detta beror på att WordPress använder sin egen styling när man väljer ett spacerblock. Vi kommer att fixa det i slutet, först behöver vi bara tillämpa samma klass och/eller inline-stil i frontend också.

Lägg till anpassad klass och inline-stil för att spara

Slutligen måste vi filtrera blocks.getSaveContent.extraPropsoch tillämpa nödvändig klass och/eller inline-styling för frontend. Återigen är detta väldigt likt det vi gjorde i exempel 1 ovan. Om en palettfärg har valts måste vi lägga till ett klassnamn som följer WordPresss standarder för färginställningar (" has-<PALETTESLUG>-background-color"). Om en anpassad färg valdes måste vi lägga till inline-stil med hex-färgen.

Obs: Om du behöver hantera klassnamn mycket rekommenderar jag att du importerar classnamesbiblioteket. Detta används flitigt i Gutenberg eftersom det förenklar inställningen av de korrekta klassnamnen med en hel del. Koden nedan antar att du inte har det och komponerar klassnamnet manuellt.


function applySpacerBackground(props, blockType, attributes) {
    if (blockType.name == 'core/spacer') {
        const { backgroundColor, customBackgroundColor } = attributes;
 
        // For improved class name handling, use classnames library. Or do it manually like..
        let className = (props.className != undefined)? props.className: '';
        if (backgroundColor != undefined) {
            className += ' has-' + backgroundColor + '-background-color';
        }
        props.className = className;
        if (customBackgroundColor != undefined) {
            Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
        }
    }
    return props;
}
 
wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'awp/spacer-apply-class',
    applySpacerBackground
);

Med ovanstående kod kommer frontend nu perfekt att återge Spacer-block med vårt anpassade färgval!

Den sista (valfria) fixen är att lägga till lite CSS till redigeraren. Du måste antingen lägga till inline CSS eller en redigeringsformatmall. Till exempel kan du ställa en stilmall i samma PHP-hook som vi använde för att köa vår Javascript-fil. Jag kommer inte att gå in på detaljer om hur man gör detta; men CSS du behöver är något i stil med nedan. Allt den gör är att ställa in Spacers background-colortill den ärvda färgen (den kommer att ärva från vår omslags-div) när blocket väljs:


.block-library-spacer__resize-container.is-selected { 
    background-color: inherit; 
}

PS: Tänk på att detta kan komma att ändras i framtiden. Gutenberg är fortfarande starkt under utveckling.

Slutsats

I det här inlägget har vi lärt oss två metoder för att implementera anpassade inställningar till befintliga WordPress Gutenberg-block. Det är fullt möjligt för enkla inställningar som kanske bara kräver en klass eller inline-styling. Vi har tittat på varningarna, som jag hoppas kommer att åtgärdas i senare Gutenberg-versioner!

Inspelningskälla: awhitepixel.com