🛠 Slik legger du til din egen shortcode i WordPress: add_shortcode() forklart [+2 eksempler]

Opprettet en snippet, la den til i functions.php, og WordPress sier «cheatin' uh?» Høres det kjent ut? Shortcodes, WordPress sin kjernemekanisme for utvidelser, og add_shortcode() låser det opp på 15 linjer med kode. Men mellom «Hello World» og et reelt scenario ligger noen fallgruver: return vs echo, parameterrekkefølge i callback og tag-konflikter.

Shortcodes dukket opp i WordPress 2.5 og har siden blitt grunnmuren i økosystemet: kontaktskjemaer, gallerier, sliderer, utdata fra egendefinerte felt, alt lever inni hakeparenteser. add_shortcode() har ikke endret seg på årevis, og du kan mestre den på en halvtime.

Nedenfor finner du en komplett gjennomgang av funksjonen med to klare til bruk-eksempler: fra et automatisk oppdaterende årstall i bunnteksten til en liste over nettstedets brukere.

💡 Rask oversikt:

• add_shortcode() syntaks og parametere, tag og callback
• Regelen: alltid return, aldri echo
• init-hooken, hvorfor shortcoden din kanskje ikke virker uten den
• To måter å sende data på: innhold mellom tagger og attributter
• Klar til bruk-kode: en shortcode for automatisk årstall og en brukerliste

Slik fungerer add_shortcode() i WordPress

Funksjonen add_shortcode() er inngangsporten for å registrere enhver egendefinert shortcode. Den tar to obligatoriske parametere: en unik tag og navnet på callback-funksjonen som skal returnere innholdet.

Ifølge WordPress-dokumentasjonen mottar callbacken tre argumenter i en fast rekkefølge:

• $attributes, en matrise med attributter sendt inn i shortcoden
• $content, teksten mellom åpnings- og lukketaggen
• $tag, tag-navnet shortcoden er registrert med

Et grunnleggende eksempel, en shortcode som skriver ut «Hello World!»:

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Koden legges i barnetemaets functions.php eller via en Code Snippets-utvidelse. Etter det vil [hello-world] i innleggseditoren skrive ut «Hello World!».

Hvorfor return, ikke echo

Legg merke til return inni callback-funksjonen. Hvis du bruker echo, skjer utskriften før WordPress bygger resten av siden, «Hello World!» havner helt øverst, og det omkringliggende innholdet forskyves.

Regelen er enkel: **en shortcode-callback returnerer alltid en verdi via ****return**. Ingen echo, print eller direkte HTML-utskrift utenfor en buffer.

Init-hooken er påkrevd

Utviklerne hos WordPress.org anbefaler å koble shortcode-registrering til init, ikke å kalle add_shortcode() direkte i hoveddelen av functions.php. Uten init kan det hende WordPress ikke er ferdig med å initialisere sine interne mekanismer, og shortcoden vil rett og slett ikke utløses.

Syntaks og parametere

Funksjonssignatur:

1
add_shortcode( string $tag, callable $callback )

$tag, shortcode-navnet (uten parenteser). Hvis to utvidelser registrerer en shortcode med samme tag, overstyrer den siste den forrige. For å unngå konflikter, legg til et unikt prefiks: ikke [gallery], men [myplugin_gallery].

$callback, navnet på funksjonen som returnerer innholdet. Du kan sende en streng med funksjonsnavnet, en anonym funksjon eller en klassemetode (ved å sende en matrise [ $object, 'method_name' ]).

Slik bruker du shortcodes i editoren

I WordPress-editoren, Gutenberg eller Classic, settes en shortcode inn i hakeparenteser. For vårt eksempel:

[hello-world]

Fullformen med en lukketagg fungerer også:

[hello-world][/hello-world]

Det andre alternativet er nødvendig når innhold sendes mellom taggene (mer om det nedenfor).

Slik kaller du en shortcode i PHP

I temamaler eller utvidelser kjøres shortcodes via do_shortcode():

1
echo do_shortcode( '[hello-world]' );

Funksjonen tar en streng som inneholder en shortcode og returnerer resultatet av kjøringen. Den er nyttig når du trenger å bygge inn shortcode-utdata i PHP-logikk, for eksempel i header.php eller inni en løkke.

Sende data til en shortcode: to måter

Metode 1: innhold mellom tagger

Omslutt dataene mellom åpnings- og lukketaggene:

[hello-world]from John to Mary[/hello-world]

Callbacken mottar strengen from John to Mary via den andre parameteren $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Resultat: «Hello from John to Mary World!».

Metode 2: attributter

Send parametere direkte i åpningstaggen:

[hello-world from="John" to="Mary"][/hello-world]

I callback-funksjonen er attributter tilgjengelige via den første parameteren $attributes, en assosiativ matrise der nøklene samsvarer med attributtnavnene:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Utdata: «Hello from John to Mary!». Attributter er bedre for strukturerte data (pris, URL, ID), mens innhold mellom tagger er bedre for vilkårlig tekst.

I praksis bør du umiddelbart legge til shortcode_atts() på attributter, en innebygd WordPress-funksjon som fletter beståtte attributter med en matrise med standardverdier. Uten den vil tilgang til $attributes['from'] kaste en PHP Notice hvis brukeren ikke spesifiserte attributtet. Med shortcode_atts() får du alltid en utfylt matrise: definerte nøkler med fallback-verdier, og ukjente attributter filtreres automatisk ut.

To klare til bruk-shortcodes for WordPress

1. Automatisk inneværende år

Shortcoden [current-year] setter inn inneværende år av seg selv, ingen grunn til å oppdatere datoen i bunnteksten hver januar:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Plasser [current-year] i bunnteksten eller innleggsteksten, så oppdateres året automatisk.

2. Liste over registrerte brukere

Shortcoden [users-list] skriver ut navnene på alle nettstedets brukere som en punktliste. Nyttig på en «Team»-side eller i admin-rapporter:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() uten argumenter returnerer alle brukere. For å begrense spørringen etter rolle, send en matrise: get_users( [ 'role' => 'editor' ] ). Koden legges i det aktive temaets functions.php eller en egendefinert utvidelse.

Video: opprette shortcodes i WordPress

En kort video om emnet, registrering av en shortcode fra bunnen av, fra å skrive funksjonen til testing i editoren:

⁉️🤔 Vanlige spørsmål

Hva skjer hvis to utvidelser registrerer en shortcode med samme tag?

WordPress kjører den som ble lastet sist. Den første shortcoden overstyres uten lyd, uten feilmeldinger. Derfor bør du alltid bruke et prefiks i shortcodene dine: [acme_gallery] i stedet for [gallery]. Dette eliminerer konflikter med enhver annen utvidelse eller tema.

Kan shortcodes kalles inni andre shortcodes?

Ja. Hvis den første shortcodens callback returnerer en streng som inneholder den andre shortcodens tag, behandler WordPress den nestede shortcoden automatisk. Men ikke glem do_shortcode(): hvis du bygger innhold manuelt og det inneholder shortcodes, kjør strengen gjennom do_shortcode() eksplisitt. Standardoppførselen til the_content gjør dette av seg selv, men et direkte callback-kall gjør det ikke.

Hvor bør shortcode-kode ligge, i temaet eller en utvidelse?

Egendefinerte shortcodes bærer funksjonalitet, ikke utseende, så det er bedre å trekke dem ut i en separat utvidelse. Bytte av tema vil ikke ødelegge nettstedet: shortcodes vil fortsette å virke. Som et minimum, bruk et barnetema hvis du er sikker på at du ikke vil bytte hovedtema.

Er det begrensninger på tag-navnet?

Navnet må bestå av latinske bokstaver, sifre og bindestreker. Mellomrom, understreker og spesialtegn er ikke tillatt. Anbefalt lengde er opptil 20 tegn, små bokstaver. Eksempel: [my-plugin-shortcode].

Hvordan feilsøker du en shortcode hvis den ikke gir noen utdata?

Første steg, aktiver WP_DEBUG i wp-config.php. Andre steg, sjekk at callbacken returnerer en verdi via return, ikke echo. Tredje steg, forsikre deg om at init-hooken er til stede. Hvis det ikke er noen feil, men utdataene er tomme, legg til error_log() inni callbacken og sjekk serverloggene.

Hva du bør huske om WordPress-shortcodes

Shortcodes er en moden og stabil mekanisme. add_shortcode() har ikke endret seg på årevis: tag, callback, init-hook, return i stedet for echo. Husk disse fire tingene, så vil enhver egendefinert shortcode fungere på første forsøk.

• Hvis du skriver ut årstallet i bunnteksten, bruk den ferdige [current-year].
• Hvis du trenger en brukerliste, [users-list] med et rollefilter.
• Hvis du skriver din egen shortcode fra bunnen av, bruk alltid et prefiks og bruk alltid init.

Som neste steg, se på å pakke en shortcode som en frittstående utvidelse og sende den inn til WordPress.org-katalogen, det er den beste måten å skille funksjonalitet fra temaet på og heve utviklerprofilen din.