🛠 Hur du lägger till din egen shortcode i WordPress: add_shortcode() förklarat [+2 exempel]

Skapade ett snippet, lade till det i functions.php, och WordPress säger "cheatin' uh?" Låter det bekant? Shortcodes, WordPress kärnmekanism för utbyggnad, och add_shortcode() låser upp den på 15 rader kod. Men mellan "Hello World" och ett verkligt scenario finns några fallgropar: return vs echo, callback-parametrarnas ordning och taggkonflikter.

Shortcodes dök upp i WordPress 2.5 och har sedan dess blivit grunden i ekosystemet: kontaktformulär, gallerier, sliders, utmatning av anpassade fält, allt lever inuti hakparenteser. add_shortcode() har inte ändrats på flera år, och du kan bemästra den på en halvtimme.

Nedan följer en komplett genomgång av funktionen med två färdiga exempel: från ett automatiskt uppdaterande årtal i sidfoten till en lista över webbplatsens användare.

💡 Snabb översikt:

• add_shortcode() syntax och parametrar, tagg och callback
• Regeln: alltid return, aldrig echo
• init-hooken, varför din shortcode kanske inte fungerar utan den
• Två sätt att skicka data: innehåll mellan taggar och attribut
• Färdig kod: en shortcode för auto-år och en användarlista

Hur add_shortcode() fungerar i WordPress

Funktionen add_shortcode() är ingången för att registrera en anpassad shortcode. Den tar två obligatoriska parametrar: en unik tagg och namnet på den callback-funktion som ska returnera innehållet.

Enligt WordPress dokumentation tar callback-funktionen emot tre argument i en fast ordning:

• $attributes, en array med attribut som skickas i shortcoden
• $content, texten mellan öppnings- och stängningstaggen
• $tag, taggnamnet som shortcoden är registrerad med

Ett grundläggande exempel, en shortcode som matar 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 placeras i ditt barntemas functions.php eller via ett Code Snippets-tillägg. Därefter kommer [hello-world] i inläggsredigeraren att mata ut "Hello World!".

Varför return, inte echo

Notera return inuti callback-funktionen. Om du använder echo sker utmatningen innan WordPress bygger resten av sidan, "Hello World!" hamnar högst upp, och det omgivande innehållet förskjuts.

Regeln är enkel: **en shortcode-callback returnerar alltid ett värde via ****return**. Ingen echo, print eller direkt HTML-utmatning utanför en buffert.

Init-hooken krävs

WordPress.orgs utvecklare rekommenderar att man krokar shortcode-registrering till init, inte anropar add_shortcode() direkt i brödtexten i functions.php. Utan init kanske WordPress inte har slutfört initieringen av sina interna mekanismer, och shortcoden kommer helt enkelt inte att köras.

Syntax och parametrar

Funktionssignatur:

1
add_shortcode( string $tag, callable $callback )

$tag, shortcode-namnet (utan hakparenteser). Om två tillägg registrerar en shortcode med samma tagg, åsidosätter den sista den föregående. För att undvika konflikter, lägg till ett unikt prefix: inte [gallery], utan [myplugin_gallery].

$callback, namnet på funktionen som returnerar innehållet. Du kan skicka en sträng med funktionsnamnet, en anonym funktion eller en klassmetod (genom att skicka en array [ $object, 'method_name' ]).

Hur man använder shortcodes i redigeraren

I WordPress-redigeraren, Gutenberg eller Classic, infogas en shortcode inom hakparenteser. För vårt exempel:

[hello-world]

Den fullständiga formen med en stängningstagg fungerar också:

[hello-world][/hello-world]

Det andra alternativet behövs när innehåll skickas mellan taggarna (mer om det nedan).

Hur man anropar en shortcode i PHP

I temamallar eller tillägg körs shortcodes via do_shortcode():

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

Funktionen tar en sträng som innehåller en shortcode och returnerar resultatet av dess körning. Det är användbart när du behöver bädda in shortcode-utdata i PHP-logik, till exempel i header.php eller inuti en loop.

Skicka data till en shortcode: två sätt

Metod 1: innehåll mellan taggar

Omslut data mellan öppnings- och stängningstaggen:

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

Callback-funktionen tar emot strängen from John to Mary via den andra parametern $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!".

Metod 2: attribut

Skicka parametrar direkt i öppningstaggen:

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

I callback-funktionen är attribut tillgängliga via den första parametern $attributes, en associativ array där nycklarna matchar attributnamnen:

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!". Attribut är bättre för strukturerad data (pris, URL, ID), medan innehåll mellan taggar är bättre för godtycklig text.

I praktiken bör du omedelbart lägga till shortcode_atts() för attribut, en inbyggd WordPress-funktion som slår samman skickade attribut med en array med standardvärden. Utan den kommer åtkomst till $attributes['from'] att kasta ett PHP-meddelande om användaren inte angav attributet. Med shortcode_atts() får du alltid en ifylld array: definierade nycklar med fallback-värden, och okända attribut filtreras bort automatiskt.

Två färdiga shortcodes för WordPress

1. Automatiskt aktuellt år

Shortcoden [current-year] infogar det aktuella året på egen hand, inget behov av att uppdatera datumet i sidfoten varje januari:

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' );

Placera [current-year] i sidfoten eller inläggstexten, så uppdateras året automatiskt.

2. Lista över registrerade användare

Shortcoden [users-list] matar ut namnen på alla webbplatsens användare som en punktlista. Användbart på en "Team"-sida eller i adminrapporter:

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() utan argument returnerar alla användare. För att begränsa frågan efter roll, skicka en array: get_users( [ 'role' => 'editor' ] ). Koden placeras i det aktiva temats functions.php eller ett anpassat tillägg.

Video: skapa shortcodes i WordPress

En kort video om ämnet, att registrera en shortcode från grunden, från att skriva funktionen till att testa i redigeraren:

⁉️🤔 Vanliga frågor

Vad händer om två tillägg registrerar en shortcode med samma tagg?

WordPress kör den som laddades sist. Den första shortcoden åsidosätts tyst, utan felmeddelanden. Därför bör du alltid använda ett prefix i dina shortcodes: [acme_gallery] istället för [gallery]. Detta eliminerar konflikter med andra tillägg eller teman.

Kan shortcodes anropas inuti andra shortcodes?

Ja. Om den första shortcodens callback returnerar en sträng som innehåller den andra shortcodens tagg, bearbetar WordPress den nästlade shortcoden automatiskt. Men glöm inte do_shortcode(): om du bygger innehåll manuellt och det innehåller shortcodes, kör strängen genom do_shortcode() explicit. Standardbeteendet för the_content gör detta på egen hand, men ett direkt callback-anrop gör det inte.

Var ska shortcode-kod finnas, i temat eller ett tillägg?

Anpassade shortcodes bär funktionalitet, inte utseende, så det är bättre att extrahera dem till ett separat tillägg. Att byta tema kommer inte att förstöra webbplatsen: shortcodes fortsätter att fungera. Använd åtminstone ett barntema om du är säker på att du inte kommer att byta föräldratema.

Finns det begränsningar för taggnamnet?

Namnet måste bestå av latinska bokstäver, siffror och bindestreck. Mellanslag, understreck och specialtecken är inte tillåtna. Rekommenderad längd är upp till 20 tecken, gemener. Exempel: [my-plugin-shortcode].

Hur felsöker man en shortcode om den inte matar ut något?

Första steget, aktivera WP_DEBUG i wp-config.php. Andra, kontrollera att callback-funktionen returnerar ett värde via return, inte echo. Tredje, se till att init-hooken finns. Om det inte finns några fel men utmatningen är tom, lägg till error_log() inuti callback-funktionen och kontrollera serverloggarna.

Vad du ska komma ihåg om WordPress shortcodes

Shortcodes är en mogen och stabil mekanism. add_shortcode() har inte ändrats på flera år: tagg, callback, init-hook, return istället för echo. Kom ihåg dessa fyra saker, så fungerar varje anpassad shortcode på första försöket.

• Om du matar ut året i sidfoten, använd den färdiga [current-year].
• Om du behöver en användarlista, [users-list] med ett rollfilter.
• Om du skriver din egen shortcode från grunden, använd alltid ett prefix och använd alltid init.

Som nästa steg, titta på att paketera en shortcode som ett fristående tillägg och skicka in det till WordPress.org-katalogen, det är det bästa sättet att separera funktionalitet från temat och höja din utvecklarprofil.