🛠 Kuidas lisada oma lühikood WordPressis: add_shortcode() jaotus [+2 näidet]

Lõin lõigu, lisasin selle faili functions.php ja WordPress ütleb „cheatin' uh?". Tuttav olukord? Lühikoodid, WordPressi tuumaks olev laiendusmehhanism, ja add_shortcode() avab selle 15 koodireaga. Kuid „Tere, maailm" ja reaalse stsenaariumi vahel on mõned lõksud: return vs echo, tagasikutse parameetrite järjekord ja siltide konfliktid.

Lühikoodid ilmusid WordPress 2.5-s ja on sellest ajast saanud ökosüsteemi alustalaks: kontaktvormid, galeriid, slaidiesitlused, kohandatud väljade väljund, kõik see elab nurksulgudes. add_shortcode() pole aastaid muutunud ja saate selle selgeks poole tunniga.

Allpool on funktsiooni täielik lahtiseletus koos kahe kasutusvalmis näitega: alates jalusest automaatselt uuenevast aastaarvust kuni saidi kasutajate nimekirjani.

💡 Kiirülevaade:

• add_shortcode() süntaks ja parameetrid, silt ja tagasikutse
• Reegel: alati return, mitte kunagi echo
• init konks, miks teie lühikood ei pruugi ilma selleta töötada
• Kaks võimalust andmete edastamiseks: siltide vaheline sisu ja atribuudid
• Kasutusvalmis kood: lühikood auto-aasta ja kasutajate nimekirja jaoks

Kuidas add_shortcode() WordPressis töötab

Funktsioon add_shortcode() on sisenemispunkt mis tahes kohandatud lühikoodi registreerimiseks. See võtab kaks kohustuslikku parameetrit: unikaalse sildi ja tagasikutsefunktsiooni nime, mis sisu tagastab.

WordPressi dokumentatsiooni kohaselt saab tagasikutse kolm argumenti kindlas järjekorras:

• $attributes, lühikoodis edastatud atribuutide massiiv
• $content, avava ja sulgeva sildi vaheline tekst
• $tag, sildi nimi, millega lühikood on registreeritud

Lihtne näide, lühikood, mis väljastab „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' );

Kood läheb teie alamteema faili functions.php või Code Snippets pluginaga. Pärast seda väljastab [hello-world] postituse redaktoris „Hello World!".

Miks return, mitte echo

Pange tähele return-i tagasikutsefunktsiooni sees. Kui kasutate echo-t, toimub väljund enne, kui WordPress ülejäänud lehe üles ehitab, „Hello World!" satub päris ülaossa ja ümbritsev sisu nihkub paigast.

Reegel on lihtne: *lühikoodi tagasikutse tagastab alati väärtuse return-iga*. Ei mingit echo-t, print-i ega otsest HTML väljundit väljaspool puhvrit.

Init konks on nõutav

WordPress.org arendajad soovitavad lühikoodi registreerimise haakida init-i, mitte kutsuda add_shortcode() otse functions.php faili kehas. Ilma init-ita ei pruugi WordPress olla oma sisemiste mehhanismide lähtestamist lõpetanud ja lühikood lihtsalt ei käivitu.

Süntaks ja parameetrid

Funktsiooni signatuur:

1
add_shortcode( string $tag, callable $callback )

$tag, lühikoodi nimi (ilma sulgudeta). Kui kaks pluginat registreerivad sama sildiga lühikoodi, kirjutab viimane eelmise üle. Konfliktide vältimiseks lisage unikaalne eesliide: mitte [gallery], vaid [myplugin_gallery].

$callback, selle funktsiooni nimi, mis sisu tagastab. Võite edastada stringi funktsiooni nimega, anonüümse funktsiooni või klassi meetodi (edastades massiivi [ $object, 'method_name' ]).

Kuidas kasutada lühikoode redaktoris

WordPressi redaktoris, nii Gutenbergis kui ka klassikalises, sisestatakse lühikood nurksulgudes. Meie näite puhul:

[hello-world]

Täisvorm sulgeva sildiga töötab samuti:

[hello-world][/hello-world]

Teine variant on vajalik, kui siltide vahel edastatakse sisu (sellest lähemalt allpool).

Kuidas kutsuda lühikoodi PHP-s

Teema mallides või pluginates käivitatakse lühikoode do_shortcode() abil:

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

Funktsioon võtab lühikoodi sisaldava stringi ja tagastab selle käivitamise tulemuse. See on kasulik, kui peate lühikoodi väljundi manustama PHP loogikasse, näiteks failis header.php või tsükli sees.

Andmete edastamine lühikoodile: kaks võimalust

Meetod 1: siltide vaheline sisu

Ümbritsege andmed avava ja sulgeva sildi vahele:

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

Tagasikutse saab stringi from John to Mary teise parameetri $content kaudu:

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

Tulemus: „Hello from John to Mary World!".

Meetod 2: atribuudid

Edastage parameetrid otse avavas sildis:

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

Tagasikutsefunktsioonis on atribuudid saadaval esimese parameetri $attributes kaudu, assotsiatiivse massiivina, kus võtmed vastavad atribuutide nimedele:

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

Väljund: „Hello from John to Mary!". Atribuudid on paremad struktureeritud andmete jaoks (hind, URL, ID), samas kui siltide vaheline sisu on parem suvalise teksti jaoks.

Praktikas peaksite atribuutidele kohe lisama shortcode_atts(), WordPressi sisseehitatud funktsiooni, mis ühendab edastatud atribuudid vaikeväärtuste massiiviga. Ilma selleta põhjustab $attributes['from'] poole pöördumine PHP teate, kui kasutaja atribuuti ei määranud. shortcode_atts()-iga saate alati täidetud massiivi: määratud võtmed varuväärtustega ja tundmatud atribuudid filtreeritakse automaatselt välja.

Kaks kasutusvalmis lühikoodi WordPressile

1. Automaatne jooksev aasta

Lühikood [current-year] sisestab jooksva aasta iseseisvalt, pole vaja igal jaanuaril jaluses kuupäeva uuendada:

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

Paigutage [current-year] jalusesse või postituse teksti ja aasta uueneb automaatselt.

2. Registreeritud kasutajate nimekiri

Lühikood [users-list] väljastab kõigi saidi kasutajate nimed täpploendina. Kasulik lehel „Meeskond" või administraatori aruannetes:

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() ilma argumentideta tagastab kõik kasutajad. Päringu piiramiseks rolli järgi edastage massiiv: get_users( [ 'role' => 'editor' ] ). Kood läheb aktiivse teema faili functions.php või kohandatud pluginasse.

Video: lühikoodide loomine WordPressis

Lühike video teemal, lühikoodi registreerimine nullist, alates funktsiooni kirjutamisest kuni redaktoris testimiseni:

⁉️🤔 Korduma kippuvad küsimused

Mis juhtub, kui kaks pluginat registreerivad sama sildiga lühikoodi?

WordPress käivitab selle, mis laaditi viimasena. Esimene lühikood kirjutatakse vaikimisi üle, ilma vigadeta. Seetõttu peaksite oma lühikoodides alati kasutama eesliidet: [acme_gallery] [gallery] asemel. See välistab konfliktid mis tahes teise plugina või teemaga.

Kas lühikoode saab kutsuda teiste lühikoodide sees?

Jah. Kui esimese lühikoodi tagasikutse tagastab stringi, mis sisaldab teise lühikoodi silti, töötleb WordPress pesastatud lühikoodi automaatselt. Kuid ärge unustage do_shortcode(): kui koostate sisu käsitsi ja see sisaldab lühikoode, käivitage string läbi do_shortcode() selgesõnaliselt. Tavaline the_content käitumine teeb seda ise, kuid otsene tagasikutse kutse mitte.

Kus peaks lühikoodi kood asuma, teemas või pluginas?

Kohandatud lühikoodid kannavad funktsionaalsust, mitte välimust, seega on parem need eraldada eraldi pluginasse. Teemade vahetamine ei lõhu saiti: lühikoodid jätkavad töötamist. Kasutage vähemalt alamteemat, kui olete kindel, et te ei vaheta vanemteemat.

Kas sildi nimele on piiranguid?

Nimi peab koosnema ladina tähtedest, numbritest ja sidekriipsudest. Tühikud, alakriipsud ja erimärgid ei ole lubatud. Soovitatav pikkus on kuni 20 tähemärki, väiketähed. Näide: [my-plugin-shortcode].

Kuidas siluda lühikoodi, kui see ei väljasta midagi?

Esimene samm, lubage WP_DEBUG failis wp-config.php. Teiseks, kontrollige, et tagasikutse tagastab väärtuse return-iga, mitte echo-ga. Kolmandaks, veenduge, et init konks on olemas. Kui vigu pole, kuid väljund on tühi, lisage tagasikutse sisse error_log() ja kontrollige serveri logisid.

Mida meeles pidada WordPressi lühikoodide kohta

Lühikoodid on küps ja stabiilne mehhanism. add_shortcode() pole aastaid muutunud: silt, tagasikutse, init konks, return echo asemel. Pidage meeles neid nelja asja ja iga kohandatud lühikood töötab esimesel katsel.

• Kui väljastate jalusesse aastaarvu, haarake valmis [current-year].
• Kui vajate kasutajate nimekirja, [users-list] koos rollifiltriga.
• Kui kirjutate oma lühikoodi nullist, kasutage alati eesliidet ja alati init-i.

Järgmise sammuna uurige lühikoodi pakendamist eraldiseisvaks pluginaks ja selle WordPress.org kataloogi esitamist, see on parim viis funktsionaalsuse eraldamiseks teemast ja oma arendajaprofiili taseme tõstmiseks.