Skapa en anpassad CMB2-länkväljarkontroll för WordPress

Senaste uppdateringen nov 9, 2022

Innehåll

Introduktion / Historia

Varför CMB2?

Handledning

Bygga formuläret

Stilar

Gör kontrollen repeterbar

Att välja en länk

Använda kontrollen

I den här handledningen kommer jag att titta på hur du kan skapa en anpassad kontroll för att utöka funktionaliteten för CMB2 (Custom Meta Boxes 2) av WebDevStudios.

Jag utvecklar webbplatser (och webbapplikationer) med WordPress CMS (Content Management System), och när ett nytt projekt landar kan du garantera att det kommer att finnas ett krav på mig att utveckla ‘Custom Meta Boxes’ för att låta användaren ha fin kontroll över webbplatsens innehåll och layout.

Jag kommer att beskriva hur jag byggde CMB2-kontrollen Link Picker för CMB2 (tillgänglig från alla bra WordPress-pluginförråd). En skärmdump som kan ses nedan.

"Link Picker" CMB2-kontrollen i aktion

Länkväljaren aktiverar den inbyggda WordPress-dialogrutan "Infoga/redigera länk" när du klickar på knappen "Välj". Detta kan ses på skärmdumpen nedan:

Genom att trycka på knappen kan du välja från en länk (eller lägga till din egen)

Jag är säker på att du håller med om att det är otroligt praktiskt att ha en kontroll som denna om du vill ge dina webbplatsredigerare möjligheten att lägga till en länk och även söka i WordPress efter dess interna länkar, istället för att de måste klippa och klistra in länkarna i en länk fält.

Introduktion / Historia

För de som inte känner till, finns en metabox på redigeringsskärmen för ett WordPress-inlägg och kommer sannolikt att innehålla olika formulärkontroller (textrutor, rullgardinslistor, kryssrutor etc…). Dessa kontroller låter dina webbplatsanvändare enkelt kunna ändra en anpassad text eller funktionalitet på webbplatsen.

Ett exempel på en metabox med olika formulärkontroller

WordPress låter dig skapa metaboxar med hjälp av funktioner (som t.ex. [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)), men att skapa metaboxar på detta sätt kan vara en lång process, med mycket kodupprepning (speciellt om du vill använda samma formulärkontroller i flera projekt).

Varför CMB2?

Några av er kanske har hört talas om Advanced Custom Fields (ACF) som tillhandahåller ett GUI (Graphical User Interface) som låter dig skapa metaboxar direkt med WordPress.

ACF enligt mig är inte ett bra verktyg för någon webblösning som skalas. Plugin-programmet är för mycket beroende av att data lagras i databasen. Detta orsakar smärta när du distribuerar ändringar på en webbplats, eftersom du inte bara kan trycka upp din kod och se ändringarna direkt. Istället måste du göra om arbetet på de olika distributionsmiljöerna (staging, live, et al). Så vi behövde en lösning som låter oss skapa metaboxar programmässigt. Ange CMB2.

Innan vi antog CMB2 använde vi tidigare HM Custom Meta Boxes från de där underbara människorna på Human Made (som började som en gaffel till WebDevStudios föregångare till CMB2,).

Vi älskade HM Custom Meta Boxes, och med de enklaste kodavsnitten kunde vi snabbt skapa anpassade Meta Boxes för att göra i stort sett vad som helst!

HM Custom Meta Boxes Markup Exempel (detta är markeringen för Instagram Meta Box i den första skärmdumpen)

Så varför flytta till CMB2? Tja, HM Custom Meta Boxes fick tyvärr inte så mycket kärlek (jag pratade med dess huvudutvecklare och han är en väldigt mycket upptagen man), medan CMB2 gick framåt med nya funktioner, nya kontroller, och det hade fått dragkraft i WordPress-communityt med många människor som adopterar det och släpper plugins för att utöka det (inklusive flera av våra partnerbyråer).

Slutligen, som du kanske har förstått, är arbetet med CMB2 lika otroligt enkelt som vi hade vant oss vid, eftersom båda plattformarna har en gemensam förfader.

Handledning

Innan vi börjar har alla sina egna ideal om hur man skapar ett WordPress-plugin, och jag har provat en hel del, men handledningen om ‘ Root Composition in WordPress ‘ av Tom J Nowell förändrade helt hur jag arbetar. Jag tycker att dess tillvägagångssätt är rent, enkelt, och det gör framtida underhåll av alla plugin till en enkel sak. Om du tar tag i källan till Link Picker for CMB2- plugin, kan du se metoderna han lär ut i praktiken.

Bygga formuläret

För att bygga formen som återger Länkväljaren är det första vi behöver göra att koppla in i cmb2_render_[control_name]handlingen. Som jag har kallat den här kontrollen ‘link_picker’ kan vi slutföra kroken så här:

För er som inte riktigt förstår add_actionkroken fungerar det som följer:

Det första argumentet cmb2_render_link_pickerär namnet på kroken vi vill haka på.
Det andra argumentet array( $this, 'cmb2_render_link_picker' )är funktionen vi vill anropa när denna hook körs. Observera att jag lindar in detta i en array, med $thissom den första parametern, eftersom jag anropar funktionen i en klass. Om du inte arbetar med klasser kan du bara använda funktionsnamnet cmb2_render_link_picker.
3., är den 10ordning som vi vill att funktionen ska aktiveras (ju lägre nummer, desto snabbare aktiveras den när åtgärden anropas).
Det 5är mängden parametrar som kommer att skickas till funktionen som jag anropar (detta kommer att bli klart inom kort).

Därefter skapar vi funktionen som renderar formuläret:

Jag har lämnat "DocBlock" i koden ovan som beskriver vad var och en av parametrarna som skickas in i cmb2_render_link_picker()funktionen gör.

Observera att min funktion börjar med publicdeklarationen. Detta beror återigen på att jag arbetar inom en klass. Om du inte arbetar med klasser kan du utelämna detta.

Värdet för detta fält skickas till funktionen via $valueparametern. När det gäller detta fält kommer vi att passera genom en array, eftersom vår kontroll har tre separata element:

Texten
URL:en
Om länken öppnas i ett nytt fönster (eller inte)

Eftersom den $valueinte alltid är inställd (till exempel första gången kontrollen renderas) måste vi initiera den med några standardvärden. Vi gör detta med följande kodbit:

Vi kan sedan börja arbeta med att rendera formuläret. Här är ett exempel på den första textinmatningskontrollen:

Puh! Det ser lite rörigt ut, eller hur? Låt oss dela upp det rad för rad:

Den inledande stycketaggen.
Inledande etiketttagg för kontrollen, men med forattributet automatiskt inställt av $field_type_object _idparametern. Detta genererar automatiskt ett ID för kontrollen när den renderas.
Texten på vår etikett, byggd med text från kontrollalternativen (eller faller tillbaka till ordet "Text").
Den avslutande etiketten
Den avslutande stycketaggen.
Starta PHP-deklarationen
Använd en inmatningskontroll (en del av för $field_type_objectatt skapa en formulärinmatning (standardtyp kommer att vara text).
Starta uppsättningen av parametrar
Ställ in klassen för ingången.
Ställ in namnet på ingången, återigen med hjälp av $field_type_objecthjälparen.
Ställ in ID för ingången till samma ID som sattes på etiketttaggen.
Få värdet från $value, eftersom detta är en array, vi vill ha "text"-nyckeln för denna kontroll.
Stäng arrayen.
Stäng inmatningsfunktionen.
Stäng PHP-deklarationen.

Webbadressens formulärfältsmarkering är ungefär densamma, bara för att använda HTML5-inmatningstyper kan vi ställa in en extra parameter ‘typ’ till ‘url’:

Slutligen vill vi implementera en dropdown. Markeringen är mycket bekant:

Observera att $field_type_objectfunktionen vi använder är selectatt generera en rullgardinsmeny. Observera också att på rad 6 har vi ett nytt attribut för options. In i detta skickar vi en rad "alternativ". Detta genereras före denna kontroll så här:

Sedan behöver vi bara linda in det i några <div>och vi har vår fulla kontroll:

Och det är allt! Vi har gjort vår kontroll! CMB2 hanterar automatiskt all data vi vill spara, så inget att göra där.

Stilar

Skärmdumpen av kontrollen vi skapar (nära toppen av det här inlägget) har några anpassade stilar applicerade på den så att den renderas inline. Jag går inte in på hur man stylar formuläret idag, men om du är nyfiken kan du ladda ner plugin och se källan.

Gör kontrollen repeterbar

För dig som vill bli lite mer avancerad kan du få kontrollen att fungera med CMB2:s repeterbara regioner. För att göra det måste du göra lite arraymapping. Använd koden nedan för att göra det:

Att välja en länk

Naturligtvis är hela poängen med länkväljaren att integrera i WordPresss egen länkvalsfunktionalitet, vilket gör att dialogrutan ‘Infoga/redigera länk’ visas när du klickar på knappen ‘Välj’.

För att få detta att hända förlitar vi oss starkt på JavaScript. Jag använder i synnerhet jQuery för att få saker att hända.

Innan jag visar dig JavaScriptet som startar dialogrutan måste vi först ställa WordPresss egna interna JavaScript i kö, som kommer att förinläsa modalerna och biblioteken som vår kod beror på. Det ser ut ungefär så här:

Som du kan se är många av de interna WordPress-biblioteken beroende av jQuery för att ladda popupen, så det är vettigt att vår popup-utlösare gör detsamma. Detta görs via den /js/plugin.jssom laddas på rad 10 i exemplet ovan.


jQuery(document).ready(function($) {

    var url   = $('body');
    var text = $('body');
    var blank = $('body');

    $('body').on('click', '.js-insert-link', function(event) {

        event.preventDefault? event.preventDefault(): event.returnValue = false;
        event.stopPropagation();

        url            = $(this).closest('.link-picker').find('input.cmb_text_url ');
        text           = $(this).closest('.link-picker').find('input.cmb_text ');
        blank          = $(this).closest('.link-picker').find('input.cmb_checkbox ');

        wpActiveEditor = true;
        wpLink.open();
        wpLink.textarea = url;

        return false;
    });

    $('body').on('click', '#wp-link-cancel, #wp-link-backdrop, #wp-link-close', function(event) {

        wpLink.textarea = url;
        wpLink.close();
        event.preventDefault? event.preventDefault(): event.returnValue = false;
        event.stopPropagation();
        return false;
    });

    $('body').on('click', '#wp-link-submit', function(event) {
        console.log(text)
        var linkAtts = wpLink.getAttrs();

        linkAtts.text = $('#wp-link-text').val();

        url.val(linkAtts.href);

        if( linkAtts.text != '') {
            text.val(linkAtts.text);
        }

        if (linkAtts.target == '_blank') {
            blank.prop('checked', true);
        } else {
            blank.prop('checked', false);
        }

        wpLink.textarea = url;
        wpLink.close();
        event.preventDefault? event.preventDefault(): event.returnValue = false;
        event.stopPropagation();
        return false;
    });
});

Genom att använda klasserna som vi lindade runt våra formulärkontroller, riktar JavaScript sig mot kontrollerna och skickar det valda resultatet från länkväljarens popup-fönster till de relevanta kontrollfälten.

Använda kontrollen

Så efter att ha tittat igenom handledningen ovan, och möjligen efter att ha granskat källkoden för Link Picker for CMB2- plugin, eller bara laddat ner min version, kanske du nu undrar hur du använder saken med CMB2. Tja, det kan inte vara enklare:

Inspelningskälla: wholesomecode.ltd