Hoe maak ik zelf een shortcode?

Bij het live gaan van de snippet base vroeg ik in mijn nieuwsbrief aan mijn lezers, of ze suggesties hadden, welke snippets ik met prioriteit zou moeten posten. Ik kreeg in totaal 12 identieke antwoorden. ‘Hoe maak ik zelf shortcodes’.

Hoewel dit strict genomen natuurlijk geen ‘code snippet’ is, denk ik dat het wel goed is, hier eens bij stil te staan. Maar laten we eerst eens kijken, hoe een shortcode eruit ziet :

[mijn_shortcode id="12" url="https://test.com/"]Dit is een test[/mijn_shortcode]

Dit is dus een shortcode met alle denkbare mogelijkheden. Ik geef aan een shortcode een tweetal parameters mee, en plaats de shortcode om een stuk content heen. Wat er hiermee gedaan wordt is natuurlijk afhankelijk van de inhoud van de shortcode zelf.

Hello World!

Laten we nu eens kijken hoe zo’n shortcode eigenlijk gedefinieerd is in WordPress. En om gelijk maar met een klassieker te beginnen, Laten we een shortcode maken die ‘Hello World!’ op de pagina zet.

<?php
add_shortcode('hello','wxp_say_hello_world'); 

function wxp_say_hello_world() {
   return 'Hello World!';
}

Iedere keer dat ik in mijn WordPress content [hello] tik, zal dit dus vervangen worden door ‘Hello World!’. Leuk, maar niet erg flexibel. Laten we eens wat anders proberen.

Wat nu, wanneer ik een shortcode zou hebben, die een parameter ‘planet’ accepteert. Dus wanneer ik intik

[hello]

Geeft hij ‘Hello World!’, maar tik ik

[hello planet="Mars"]

geeft hij ‘Hello Mars!’ terug.

<?php 
add_shortcode('hello','wxp_say_hello_world'); 

function wxp_say_hello_world($args) {
   if (!isset($args['planet')) {
        $planet = 'World' 
      } else {
        $planet = $args['planet'];
   }
   return "Hello {$planet}!";
}

Wow. Dat ziet er gelijk een stuk complexer uit, nietwaar? Ik heb nu een parameter meegegeven aan de functie die ik $args genoemd heb. Het naampje mag je helemaal zelf bedenken, maar gangbaar zijn $args (van arguments), $atts or $attr (van attributes) of $params (van parameters).

Vervolgens ga ik controleren of alle parameters die ik verwacht zijn ingesteld of niet. Is er geen parameter ‘planet’ ingesteld, dan geef ik de variabele $planet de naam ‘World’, en anders de naam die in de parameter ‘planet’ staat.

En dan heb ik stiekem iets nieuws geïntroduceerd. Ik had de ‘return value’ in regel 10 ook kunnen schrijven

return 'Hello ' . $planet . '!';

maar dat is zoveel getik. Wanneer ik een tekenreeks (een ‘string’) niet tussen enkele quotes plaats (wat het best is om te doen), maar tussen dubbele quotes, dan vraag ik aan PHP om in die string ook intelligent te kijken naar de inhoud daarvan. En wanneer er bijvoorbeeld iets tussen accolades staat in die string, dit als PHP variabelen te interpreteren.

Wanneer ik dus een variabele ‘$planet’ heb met een waarde ‘Mars’, krijg ik de volgende resultaten :

<?php
$planet = 'Mars'; 
echo 'Hello {$planet}!';  //Resultaat: Hello {$planet}!
echo "Hello {$planet}";  //Resultaat: Hello Mars!

En zo lukt het me toch om jou stiekem achter jouw rug om een PHP programmeur te maken, nietwaar?

Maar wanneer ik meerdere variabelen heb dan is het hele stuk code

   if (!isset($args['planet')) {
        $planet = 'World' 
      } else {
        $planet = $args['planet'];
   }

wel behoorlijk omslachtig, wanneer je dit voor bijvoorbeeld 10 variabelen uit zou moeten schrijven. Daarom heeft WordPress ook een slimmere manier bedacht. De ‘shortcode_atts’ functie. In het kort: Je geeft een lijst (array) van default waarden mee in een array, en als de parameter niet voorkomt, of een lege waarde heeft, krijgt deze parameter de default waarde.

Stel je voor, dat ik niet altijd ‘Hello’ wil zeggen, maar ook wel eens wat anders. En misschien wil ik zelfs wel drie woorden gebruiken : ‘Hello beautiful world!’.

Dus laten we de nogal gelimiteerde shortcode [‘hello’] eens omdopen naar ‘greet’.

<?php
add_shortcode('greet', 'wxp_greetings');

function wxp_greetings($args) {
   $atts = shortcode_atts(
              array(
                 'greeting' => 'Hello',
                 'feeling'  => 'Beautiful',
                 'planet'   => 'World'
              ), $args);
   return "{$atts['greeting']} {$atts['feeling']} {$atts['planet']}!";  
}

Enkele voorbeelden van shortcodes en het resultaat hier :

[greet planet='Mercury'] Hello Beautiful Mercury!
[greet greeting='Goodbye' feeling='Cruel'] Goodbye Cruel World!
[greet] Hello Beautiful World!
[greet planet='Mercury' greeting='Welcome' feeling='Distant'] Welcome Distant Mercury!

En nu met content!

Tot nu toe hebben we alleen nog maar gekeken naar shortcodes die nergens omheen stonden, maar zoals we aan het begin ook hebben mogen lezen, er zijn shortcodes die een bepaalde content omsluiten. Zoals als [shortcode]Dit is de content van de shortcode[/shortcode].

Laten we eens een compleet nieuwe shortcode introduceren. We noemen de shortcode ‘boxit’, en de content in de shortcode komt in een box te staan. De box shortcode accepteert twee parameters, ‘class’ en ‘style’. De ‘class’ parameter geeft een css class aan de box, de style parameter accepteert directe styling.

<?php 
add_shortcode('boxit', 'wxp_boxit');

function wxp_boxit($args, $content) {
    $atts = shortcode_atts(
               array(
                  'style' => false,
                  'class' => false
               ),args);
    if ($atts['style']) {
         $style = "style='{$atts['style']}'";
    } else {
         $style='';
    }
    if ($atts['class']) {
         $class = "class='{$atts['class']}'";
    } else {
         $class = '';
    } 
    return "<div $class $style>$content</div>"; 
}

Geef ik nu het volgende in

[boxit style='border-color:black;border-width:1px;border-style:dotted']
Dit is een tekst
[/boxit]

dan krijg ik een tekst ‘Dit is een tekst’ met een stippellijn erom heen.

En geef ik vervolgens in

[boxit style='border-color:black;border-width:1px;border-style:dotted']
En dit gebeurt er met shortcodes... [greet] 
[/boxit]

dan krijg ik…

…wacht eens even, dit had ik niet verwacht. Want ik had verwacht de tekst ‘En dit gebeurt er met shortcodes… Hello Beautiful World!’ te zien. Maar ik krijg letterlijk de tekst te zien, die er tussen de shortcodes staat: En dit gebeurt er met shortcodes… [greet]

Wat heb ik hier fout gedaan?

Omdat er shortcodes binnen shortcodes voor kunnen komen, moeten we de parameter ‘content’ die we meegeven altijd evalueren met de functie ‘do_shortcode’.

We moeten de code dus een klein beetje uitbreiden :

<?php 
add_shortcode('boxit', 'wxp_boxit');

function wxp_boxit($args, $content) {
    $atts = shortcode_atts(
               array(
                  'style' => false,
                  'class' => false
               ),args);
    if ($atts['style']) {
         $style = "style='{$atts['style']}'";
    } else {
         $style='';
    }
    if ($atts['class']) {
         $class = "class='{$atts['class']}'";
    } else {
         $class = '';
    } 
    $content = do_shortcode($content); //deze regel is toegevoegd
    return "<div $class $style>$content</div>"; 
}

en zo gaat het wel goed.

En nu weet je eigenlijk alles, wat er over shortcodes te weten valt.

Succes met het maken van je eigen shortcodes!