Matricea brută $atts poate include toate atributele arbitrare care sunt specificate de utilizator. (În plus, intrarea zero a matricei poate conține șirul care a fost recunoscut de către regex.)
Pentru a ajuta setarea valorilor implicite pentru atribute lipsă, și pentru a elimina toate atributele care nu sunt recunoscute de scurtătură, API-ul oferă o funcție shortcode_atts().
shortcode_atts() seamănă cu funcția wp_parse_args, dar are câteva diferențe importante. Parametrii săi sunt:
shortcode_atts( $defaults_array, $atts );
Sunt necesari ambii parametri. $defaults_array este un tablou asociativ care specifică numele de atribute recunoscute si valorile lor implicite. $atts este matricea atributelor prime trecute în manipulatorul de scurtătură. shortcode_atts() va returna o matrice normalizată conținând toate cheile de la $defaults_array, completat cu valori de la matricea $atts dacă este prezentă. De exemplu:
$a = shortcode_atts( array(
‘title’ => ‘Titlul meu’,
‘foo’ => 123,
), $atts );
Dacă $atts ar conține array( ‘foo’ => 456, ‘bar’ => ‘something’ ), rezultat $a ar fi array( ‘title’ => ‘My Title’, ‘foo’ => 456 ). Valoarea $atts[‘foo’] suprascrie valoarea implicită 123. $atts[‘title’] nu este setat, astfel că este folosită valoarea implicită ‘Titlul meu‘. Nu există nici un element „bar” în matricea implicită, deci nu este inclus în rezultat.
Numele de atribute sunt întotdeauna convertite în litere mici înainte de a fi trecute în funcția de manipulare. Valorile sunt neatinse. [myshortcode FOO=”BAR”] produce $atts = array( ‘foo’ => ‘BAR’ ).
Un cod idiom sugerat pentru declararea atributelor implicite și de analiză într-un manipulator de scurtătură este după cum urmează:
function my_shortcode_handler( $atts, $content = null ) {
$a = shortcode_atts( array(
‘attr_1’ => ‘attribute 1 default’,
‘attr_2’ => ‘attribute 2 default’,
// …etc
), $atts );
}
Acest lucru va analiza atributele, va seta valorile implicite, va elimina orice atribute nesuportate, și va stoca rezultatele într-o variabilă de matrice locală numită $a cu atributele ca chei – $a[‘attr_1’], $a[‘attr_2’], și așa mai departe. Cu alte cuvinte, gama de valori implicite aproximează o listă de declarații de variabile locale.
IMPORTANT – Nu utilizați cuvinte care încep cu majuscule sau tot cuvântul cu majuscule pentru numele de atribute $atts
Valorile $atts sunt scrise cu litere mici în timpul procesării shortcode_atts( array( ‘attr_1’ => ‘attr_1 default’, // …etc ), $atts ), astfel încât poate doriți să utilizați doar litere mici.
NOTĂ privind confuzia între refereințele de nume regex/apel invers
Intrarea zero a matricei de atribute ($atts[0]) va conține șirul care corespunde scurtăturii regex, dar NUMAI în cazul în care diferă de denumirea de apel invers, care apare altfel ca al treilea argument pentru funcția de apel invers.
add_shortcode(‘foo’,’foo’); // două scurtături de referință pentru același apel invers
add_shortcode(‘bar’,’foo’);
produce acest comportament:
[foo a=’b’] ==> callback to: foo(array(‘a’=>’b’),NULL,”foo”);
[bar a=’c’] ==> callback to: foo(array(0 => ‘bar’, ‘a’=>’c’),NULL,””);
Acest lucru este confuz și poate reflecta un bug de bază, dar o rutină callback supraîncărcată poate determina în mod corect ce acurtătură a fost folosită pentru apelare, prin verificarea AMBELOR al treilea argument pentru apel invers și atributul zero. (NU este o eroare să avem două scurtături de referință pentru aceeași rutină de apel invers, care permite cod comun.)
Ieșire
Valoarea returnată a unei funcții de manipulare a scurtăturii este introdusă în ieșirea conținutului postării în locul macro-ului scurtăturii. Amintiți-vă să utilizați funcția de returnare și nu ecoul – to ce rezultă din ecou va fi trimis la browser, dar nu va apărea în locul corect în pagină.
Scurtăturile sunt analizate după ce formatările de postare wpautop și wptexturize au fost aplicate. Acest lucru înseamnă că ieșirea HTML a scurtăturii nu va avea în mod automat ghilimele aplicate, etichete p și br adăugate, și așa mai departe. Dacă doriți ieșirea scurtăturii să fie formatată, trebuie să apelați wpautop() sau wptexturize() în mod direct, atunci când returnați ieșirea de la manipulatorul de scurtătură.
wpautop recunoaște sintaxa scurtăturii și va încerca să nu elimine etichetele p sau br care includ scurtăturile care se găsesc singure pe propria linie. Scurtăturile destinate utilizării în această manieră ar trebui să asigure că ieșirea este inclusă într-o eticheta de bloc corespunzătoare, cum ar fi <p> sau <div>.
Notă: În WordPress 2.5.0, scurtăturile erau procesate înainte de aplicarea formatării postării, astfel încât ieșirea HTML a scurtăturii era uneori inclusă în etichetele p sau br. Acest lucru a fost un comportament incorect, care a fost rezolvat în 2.5.1.
În cazul în care scurtătura produce o mulțime de HTML, atunci ob_start poate fi folosit pentru a capta ieșirea și a o transforma într-un șir de după cum urmează:
function my_shortcode() {
ob_start();
?> <HTML> <here> … <?php
return ob_get_clean();
}
Lasă un răspuns