Scurtături de includere și auto-închidere în WordPress

Exemplele anterioare arată macro-uri pentru scurtături de auto-închidere, cum ar fi [myshortcode]. API suportă și scurtături de includere precum [myshortcode]conținut[/myshortcode].

În cazul în care un macro pentru scurtătură este folosit pentru a include conținut, funcția sa de manipulare va primi un al doilea parametru care conține conținutul. Utilizatorii ar putea scrie scurtăturile în ambele forme, astfel încât este necesar să se permită oricare dintre aceste cazuri, oferind o valoare implicită pentru al doilea parametru pentru funcția de manipulare:

function my_shortcode_handler( $atts, $content = null )

empty( $content ) poate fi folosit pentru a distinge între auto-închidere și cazurile de includere.

Când este inclus conținut, macro-ul complet dse scurtătură care include conținutul va fi înlocuit cu ieșirea funcției. Este responsabilitatea funcției de manipulare să furnizeze orice este necesar pentru evadarea sau codificarea șirului conținutului brut, și a-l include la ieșire.

Iată un exemplu banal de scurtăturp de includere:

function caption_shortcode( $atts, $content = null ) {
return ‘’ . $content . ‘’;
}
add_shortcode( ‘caption’, ‘caption_shortcode’ );

Atunci când este utilizată astfel:

[

Captarea mea

]

ieșirea ar fi:

Captarea mea

Deoarece $content este inclus în valoarea de returnare, fără nicio evadare sau codificare, utilizatorul poate include HTML brut:

[

<a href=”http://exemplu.ro/”>Captarea mea</a>

]

Care ar produce:

<a href=”http://exemplu.ro/”>Captarea mea</a>

Acest lucru poate sau nu să fie comportament intenționat – în cazul în care scurtătura nu ar trebui să permită HTML brut la ieșirea sa, ar trebui să folosească o funcție de evadare sau de filtrare care să acționeze înainte de a returna rezultatul.

Analizorul de scurtătură folosește o singură peste conținutul postării. Acest lucru înseamnă că, în cazul în care parametrul $content al unui manipulator de scurtătură conține o altă scurtătură, nu va fi analizată:

[caption]Captare: [myshortcode][/caption]

Acest lucru ar produce:

Captare: [myshortcode]

În cazul în care scurtătura de includere este destinată să permită alte scurtături la ieșirea sa, funcția de manipulare poate apela do_shortcode() recursiv:

function caption_shortcode( $atts, $content = null ) {
return ‘’ . do_shortcode($content) . ‘’;
}

În exemplul anterior, acest lucru ar asigura că macro-ul „[myshortcode]” din conținutul închis este analizat, iar ieșirea sa inclusă de span de captare:

Capare: Rezultatul funcției de manipulare myshortcode

Analizorul nu se ocupă de amestecarea formelor de includere și non-includere ale aceleiași scurtături așa cum ai vrea tu. De exemplu, dacă ai:

[[myshortcode example=’non-enclosing’ /] conținut non-inclus [myshortcode] conținut inclus [/myshortcode]]

În loc să fie tratate ca două scurtături separate de textul ”conținut non-inclus”, analizorul tratează aceasta ca o singură scurtătură care include „conținut non-inclus [myshortcode] conținut inclus„.

Scurtăturile de includere suportă atribute în același mod ca și scurtăturile de auto-închidere. Iată un exemplu al caption_shortcode() îmbunătățit pentru a suporta un atribut „class„:

function caption_shortcode( $atts, $content = null ) {
$a = shortcode_atts( array(
‘class’ => ‘caption’,
), $atts );

return ‘’ . $content . ‘’;
}
[Captarea mea]

Captarea mea

Alte caracteristici pe scurt

Analizorul suportă stilul XHTML care închide scurtături ca „[myshortcode /]„, dar acest lucru este opțional.
Macro-urile scurtăturilor pot folosi ghilimele simple sau duble pentru valorile atributelor, sau să le omită în întregime dacă valoarea atributului nu conține spații. [myshortcode foo = bar ‘123’ = 456] este echivalent cu [myshortcode foo = „123” bar = „456”]. De notat că valoarea atributului pe ultima poziție nu se poate termina cu un slash înainte, deoarece caracteristica în paragraful de mai sus va consuma ca slash.
Pentru compatibilitate inversă cu scurtăturile ad-hoc mai vechi, numele de atribute pot fi omise. În cazul în care un atribut nu are nume va fi dată o cheie numerică pozițională în matrice $atts. De exemplu, [myshortcode 123] va produce $atts = array( 0 => 123 ). Atributele de poziție pot fi amestecat cu cele cu nume, și ghilimelele pot fi utilizate în cazul în care valorile conțin spații sau alte caractere importante.
API pentru scurtături are situații de testare. Testele – care conțin o serie de exemple de cazuri de eroare de sintaxă și neobișnuite – pot fi găsite la http://svn.automattic.com/wordpress-tests/trunk/tests/shortcode.php

Referința funcției

Următoarele funcții API pentru scurtături sunt disponibile:

function add_shortcode( $tag, $func )

Înregistrează o nouă funcție de manipulare a scurtăturii. $tag este șirul de scurtătură așa cum este scris de către utilizator (fără acolade), cum ar fi „myshortcode„. $func este numele funcției de manipulare.

Doar o funcție de manipulare poate exista pentru o anumită scurtătură. Apelarea add_shortcode() din nou cu același nume $tag va suprascrie manipulatorul anterior.

function remove_shortcode( $tag )

Anulează înregistrarea unei scurtături existente. $tag este numele scurtăturii, așa cum este utilizat în add_shortcode().

function remove_all_shortcodes()

Anulează înregistrarea tuturor scurtăturilor.

function shortcode_atts( $pairs, $atts )

Procesează o matrice brută de atribute $atts în contrast cu setul de valori implicite specificate în $pairs. Returnează o matrice. Rezultatul va conține fiecare cheie de la $pairs, fuzionate cu valorile de la $atts. Orice cheie în $atts care nu există în $pairs este ignorată.

function do_shortcode( $content )

Analiza oricăror macro-uri de scurtătură cunoscute din șirul $content. Returnează un șir care conține conținutul original cu macro-urile de scurtătură înlocuite cu ieșirea funcțiilor lor de manipulare.

do_shortcode() este înregistrat ca un filtru implicit pe „the_content” cu o prioritate de 11.