Insticksprogrammet Advanced Custom Fields (ACF) stöder fullständig inställning av fält och grupper efter PHP-kod i ditt tema eller plugin. Fördelarna med att göra detta är att alla dina fält kommer att vara tillgängliga oavsett vilken WordPress-instans du arbetar med (till exempel om du behöver växla mellan lokal, testserver och liveserver). Du kan ställa in alla fält i ACF:s admin och använda exportverktyget för att exportera det till PHP.

Men om du gör detta ofta kanske du märker att ACF:s PHP-export innehåller mycket kod som gör dina PHP-filer onödigt långa. I vissa fall är det bättre att skriva koden själv, med det absoluta minimum som behövs, för renare kod i ditt tema eller plugin. Den här guiden syftar till att ge dig en fullständig referens för hur du manuellt skriver ut lägga till ACF-fält och grupper i PHP. Observera att det inte kommer att gå in i detalj om varje fälttyp eftersom det förutsätter att du redan är bekant med de olika fälten som är möjliga i ACF.

Men först; vissa försiktighetsåtgärder

För att upprätthålla bra kodstandarder och säkerställa att din WordPress-webbplats inte kraschar bör du alltid kontrollera om funktionerna eller klasserna som din kod använder faktiskt existerar. Speciellt när det kommer till plugins som enkelt kan avaktiveras eller inte ens installeras på en sida bör du alltid slå in din plugin-specifika kod i ett if-test som kontrollerar om funktionerna du använder finns, innan du använder dem.

När det gäller ACF kan du göra det genom att kontrollera om klassen 'acf'finns eller om funktionen för att lägga till fält och grupper, 'acf_add_local_field_group', finns. Linda någon av dem runt koden nedan.


if (function_exists('acf_add_local_field_group')) {
    // Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
    // Your ACF specific code here
}

Skelettkod

För att lägga till metaboxar (grupper) och fält använder vi kroken som heter acf/init. Inuti funktionen anropar vi funktionen acf_add_local_field_group()med en array som parameter. Inuti den arrayen finns den fullständiga inställningen för gruppen och alla dess fält. De viktigaste är array-nycklarna 'fields'och 'location'. För arraynyckel 'fields'anger du arrayen för alla fält, och för nyckeln 'location'anger du inställningarna för var metaboxen ska visas. Det här inlägget kommer att gå in i detalj om vilka möjliga alternativ du har för var och en av dessa nedan.

Detta är det absoluta minimum för att lägga till en grupp, förutom fälten och platsen:

Varje grupp behöver en unik nyckel, men själva namnet spelar inte så stor roll (för oss). Om du lägger till fler grupper, glöm inte att ändra 'key'fältet. Metabox-titeln kan ställas in i array-nyckelelementet, du gissade rätt, 'title'. Om du lägger till flera metaboxar på samma plats (t.ex. i postredigering), kan du styra vilken som kommer först genom att ange olika nummer i 'menu_order'.

Du kan styra metabox-designen genom att tillhandahålla antingen defaulteller seamlessi 'style'. Men med den nya Gutenberg-redaktören har detta en mycket mindre betydelse. Detsamma gäller nyckeln 'position'där man förr i tiden kunde placera metaboxen under inläggets innehåll ('normal'), på sidan ('side') eller direkt efter inläggets titel ('acf_after_title').

OK! Låt oss dyka in i de två mer intressanta delarna av arrayen; börjar med platsen – som definierar var metaboxen visas.

Plats

Det här handlar om vad du lägger i nyckeln 'location'. Men innan vi undersöker de möjliga alternativen måste vi förstå dess arraystruktur.

'location'accepterar en array med en array av element i en array! Vänta. Ja, eftersom det är möjligt att tillhandahålla och kombinera OCH- och ELLER-logik på plats (t.ex. "visa i postredigering men inte om inläggstypen är ‘bok’", eller "visa i användarredigeringsskärm och även skapa ny användarskärm men för båda fallen inte om den nuvarande rollen är författare"). Sättet du betecknar om det är ett OCH eller ett ELLER är genom att strukturera arrayerna. Det är mycket lättare att visa än att förklara med ord:

Så här kombinerar du två platselement med OCH-logik (båda dessa måste vara sanna):

Och det här är för att kombinera platser med ELLER-logik (bara en behöver vara sann):

Se skillnaden?

Okej, låt oss gå vidare. Varje platsalternativ består av en uppsättning av tre element; 'param'det är där vi lägger till alla olika platser, 'operator', och 'value'. Operatör är hur man jämför värdet, och det kan vara '=='för lika med eller '!='för inte lika med.

Låt oss gå igenom de möjliga alternativen en efter en.

Plats efter posttyp

Ställ in önskad inläggstyp i 'value'. Tänk på att du inte kan tillhandahålla en array med flera inläggstyper, du måste kombinera flera av dessa arrayer i en AND-konfiguration.

Plats efter poststatus

Ställ in önskad poststatus som 'value'. Återigen, kom ihåg att du inte kan tillhandahålla en uppsättning av flera inläggsstatusar, du måste ange varje önskat värde i en OCH- eller ELLER-konfiguration.

Plats efter sidmall

Detta visas endast om den valda sidan (eller anpassad inläggstyp med stöd för sidmall) har valt det angivna sidmallsnamnet.

Plats efter tilldelad taxonomiterm

Den här platsen är till för när ett inlägg har en specifik term tilldelad. Du måste ange taxonominamnet, ett kolon och termens snigel som värde.

Plats efter sidtyp

ACF grupperar speciella egenskaper för sidor som "sidtyp". Det handlar mest om huruvida den aktuella sidan är en förälder- eller barnsida eller inte, men också för inriktning på sidor som är inställda som WordPress-startsida eller bloggsida.

Plats: taxonomi

En plats för när man redigerar eller lägger till en term i en taxonomi.

Ange taxonominamnet som 'value'. Tänk på att du inte kan tillhandahålla en uppsättning av flera taxonomier, men du kan tillhandahålla 'all'för att rikta in dig på alla taxonomier.

Plats: användare

Denna plats är till för att lägga till eller redigera en användarprofil.

Ange 'edit‘ för att endast rikta in sig på skärmen för redigering av befintliga användare, 'register'för att endast rikta in formuläret när du registrerar en ny användare, eller ‘ all'för båda ovanstående.

Plats: menyalternativ

Sedan ACF 5.6 kan du också lägga till fältgrupper till menyalternativ.

Du kan ställa valuein för allatt tillämpa gruppen på alla menyalternativ, eller så kan du ange menyer antingen efter plats (registrerade platser i ditt tema) eller efter meny-ID. För platsanvändning 'location/<name>'– så för en plats som heter ‘ primary‘ kan du ställa in värdet till 'location/primary'för att tillämpa din grupp på en meny som endast är tilldelad denna plats. Om du vill rikta in dig på ett specifikt meny-ID, ställ in värdet på en sträng av det ID:t.

Plats: widget

ACF ger dig till och med en plats i widgetinställningarna utan att ändra widgetens kärnkod.

Du kan rikta in dig på alla widgetar med 'all'som 'value'eller rikta in dig på en specifik widget. Du måste känna till det "interna ID" för widgeten som de är registrerade med.

Plats: ACF-alternativsida (endast Pro)

Med ACF Pro kan du använda ACF för att skapa anpassade adminsidor.

Ange namnet du ställt acf_add_options_pagein menu_slugsom 'value'.

Plats: block (endast Pro 5.8+)

ACF Pro (5.8+) har en funktion för att lägga till Gutenberg-block med fält från ACF och styra dess utdata med PHP. Ganska snyggt för dem som inte har dykt in i att lägga till anpassade Gutenberg-block och det nödvändiga Javascriptet ännu.

Fält

Nu kommer vi in på den mer intressanta delen; själva fälten. ACF erbjuder ett (riktigt) brett utbud av fälttyper, och jag upprepar; den här guiden visar dig inte vad varje fält är och hur de fungerar eller ser ut.

I kärnmatrisen du tillhandahåller tillhandahåller 'fields'du acf_add_local_field_group()en matris där varje fält är sin egen matris.

Det absoluta minimum som krävs för varje fält är följande: ett unikt 'key'som kan vara vad du vill och du kommer förmodligen aldrig behöva hänvisa till det. Du behöver också 'name'vilken som är meta-nyckeln (inlägg, användare, term) där värdet på fältet sparas som – och det är den du kommer att referera till när du får värdet på fälten. Du bör ge ett 'label'och slutligen det avgörande 'type'som definierar vilken fälttyp vi hanterar. Resten av fälten beror på 'type'som vi kommer att se när vi går igenom varje fälttyp nedan.

Detta är skelettkoden för att lägga till ett fält.

Tänk på att du behöver ovanstående för varje fält, men för att inte upprepa samma kod kommer varje fälttyp nedan endast att inkludera 'type'och alla andra element som behövs för den fälttypen.

Fält: Textinmatning

Det enklaste fältet av alla. Allt vi egentligen behöver är:

Men för att ytterligare anpassa din textinmatning kan du också tillhandahålla något av följande:

Fält: Nummerinmatning

Fält: Textarea

Fält: Räckviddsreglage

Fält: Lösenord

Samma som textinmatning, förutom att allt du skriver i den kommer att täckas med * som du kan förvänta dig i ett lösenordsfält.

Fält: Bild

Välj en bild.

Fält: Fil

Liknar bilden ovan, förutom att den inte förhandsgranskar filen.

Du kan också tillhandahålla 'mime_types' => '',och ställa in den till att t.ex. 'pdf,docx'endast tillåta PDF- och DOCX-filer.

Fält: WYSIWYG Editor

WYSIWYG är en "What You See Is What You Get"-redaktör – den vi var bekanta med innan Gutenberg kom (TinyMCE).

Parametern 'media_upload'och 'delay'kan vara 1 (sant) eller 0 (falskt).

Fält: Välj

Fält: Kryssruta

Observera att det 'default_value'kan vara en rad med flera val.

Fält: Radioknapp

Inställningen 'other_choice'till true lägger till en extra alternativknapp märkt "Övrigt" med en textinmatning där användaren kan skriva något.

Fält: Sant/falskt (växla)

'ui_on_text'och 'ui_off_text'är bara giltig om är 1, eftersom de 'ui'definierar vad som ska visas på den speciella UI-växeln.

Fält: Länk

Ger dig en knapp för att ange en länk, antingen genom att skriva eller välja från innehåll på din WordPress-webbplats (bör vara bekant från att lägga till en länk i den vanliga WordPress-redigeraren).

Fält: Post Object

Ger en valruta där du kan välja bland WordPress-innehåll. Select låter dig söka genom att skriva in och allt innehåll är uppdelat efter inläggstyp. Du kan tillåta att flera inlägg väljs eller bara ett.

Fält: Relation

Fält: Välj termer i en taxonomi

Taxonomy term selector har fyra olika "lägen" eller typer där två av dem tillåter flera val.

Fält: Välj användare

Fält: Google Maps

Tänk på att du måste tillhandahålla en giltig GoogleMaps API-nyckel till ACF för att det här fältet ska fungera, så här:


add_filter('acf/fields/google_map/api', function($api) {
    $api['key'] = 'YOURAPIKEY';
    return $api;
});

Fält: Datumväljare

Fält: Väljare för datum och tid

Fält: Tidsväljare

Fält: Colorpicker

Fält: Galleri (endast ACF Pro)

Specialtyper av fält

ACF erbjuder också vissa fälttyper som inte sparar ett värde i sig, men de är mer för organisatoriska ändamål. För alla dessa ställs 'name'in på en tom sträng.

HTML-meddelande

Om du bara behöver skriva ut lite HTML utan att det faktiskt sparar ett värde kan du använda typ 'message'.

Repeater (endast ACF Pro)

En repeater innehåller en rad fält som kan upprepas.

Elementet sub_fieldsförväntar sig en array av fält, precis som du har ställt in fält ovan.

Slutsats

Detta är inte på något sätt en uttömmande guide eftersom ACF erbjuder ett så brett utbud av alternativ och anpassningar. Men det bör täcka de mest använda alternativen och anpassade användningsfall. Personligen kommer jag på mig själv att hänvisa till detta ganska ofta när jag lägger till ACF-fält för klienter. Och även för de mest konstiga alternativen är den här guiden tillräcklig nog så att jag inte behöver blåsa upp mina PHP-filer med ACF:s exportkod. Jag hoppas att detta har varit användbart för dig också!

Inspelningskälla: awhitepixel.com