🛠 Kuinka lisätä oma shortcode WordPressissä: add_shortcode()-erittely [+2 esimerkkiä]

Loin snippetin, lisäsin sen functions.php-tiedostoon, ja WordPress sanoo "cheatin' uh?" Kuulostaako tutulta? Shortcodet, WordPressin keskeinen laajennusmekanismi, ja add_shortcode() avaa sen 15 koodirivillä. Mutta "Hello Worldin" ja todellisen käyttötapauksen välillä on muutama sudenkuoppa: return vs echo, callback-parametrien järjestys ja tagien ristiriidat.

Shortcodet ilmestyivät WordPress 2.5:ssä ja ovat siitä lähtien olleet ekosysteemin perusta: yhteydenottolomakkeet, galleriat, sliderit, mukautettujen kenttien tulosteet, kaikki elävät hakasulkeissa. add_shortcode() ei ole muuttunut vuosiin, ja voit hallita sen puolessa tunnissa.

Alla täydellinen erittely funktiosta kahden käyttövalmiin esimerkin kera: automaattisesti päivittyvästä vuodesta alatunnisteessa sivuston käyttäjälistaan.

💡 Pikaopas:

• add_shortcode()-syntaksi ja parametrit, tag ja callback
• Sääntö: aina return, ei koskaan echo
• init-koukku, miksi shortcodesi ei ehkä toimi ilman sitä
• Kaksi tapaa välittää dataa: tagien välinen sisältö ja attribuutit
• Käyttövalmis koodi: shortcode automaattiselle vuodelle ja käyttäjälistalle

Miten add_shortcode() toimii WordPressissä

add_shortcode()-funktio on lähtökohta minkä tahansa mukautetun shortcoden rekisteröinnille. Se ottaa kaksi pakollista parametria: yksilöllisen tagin ja callback-funktion nimen, joka palauttaa sisällön.

WordPress-dokumentaation mukaan callback saa kolme argumenttia kiinteässä järjestyksessä:

• $attributes, taulukko shortcodessa annetuista attribuuteista
• $content, teksti avaavan ja sulkevan tagin välissä
• $tag, tagin nimi, jolla shortcode on rekisteröity

Perusesimerkki, shortcode, joka tulostaa "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' );

Koodi sijoitetaan lapsiteeman functions.php-tiedostoon tai Code Snippets -lisäosan kautta. Tämän jälkeen [hello-world] julkaisueditorissa tulostaa "Hello World!".

Miksi return, ei echo

Huomaa return callback-funktion sisällä. Jos käytät echo-komentoa, tulostus tapahtuu ennen kuin WordPress rakentaa loput sivusta, "Hello World!" päätyy aivan yläreunaan ja ympäröivä sisältö siirtyy pois paikaltaan.

Sääntö on yksinkertainen: **shortcode-callback palauttaa aina arvon ****return**-komennolla. Ei echo, print tai suoraa HTML-tulostusta puskurin ulkopuolella.

Init-koukku on pakollinen

WordPress.orgin kehittäjät suosittelevat shortcoden rekisteröinnin koukuttamista init-tapahtumaan, ei add_shortcode()-funktion kutsumista suoraan functions.php-tiedoston rungossa. Ilman init-koukkua WordPress ei välttämättä ole saanut sisäisiä mekanismejaan alustettua loppuun, ja shortcode ei yksinkertaisesti käynnisty.

Syntaksi ja parametrit

Funktion allekirjoitus:

1
add_shortcode( string $tag, callable $callback )

$tag, shortcoden nimi (ilman sulkeita). Jos kaksi lisäosaa rekisteröi shortcoden samalla tagilla, viimeisin ohittaa edellisen. Ristiriitojen välttämiseksi lisää yksilöllinen etuliite: ei [gallery], vaan [myplugin_gallery].

$callback, sen funktion nimi, joka palauttaa sisällön. Voit antaa merkkijonon, jossa on funktion nimi, nimettömän funktion tai luokan metodin (antamalla taulukon [ $object, 'method_name' ]).

Miten shortcodeja käytetään editorissa

WordPress-editorissa, Gutenbergissa tai Classicissa, shortcode lisätään hakasulkeissa. Esimerkillemme:

[hello-world]

Täysi muoto sulkevan tagin kanssa toimii myös:

[hello-world][/hello-world]

Toista vaihtoehtoa tarvitaan, kun sisältöä välitetään tagien välissä (siitä lisää alla).

Miten shortcodea kutsutaan PHP:ssä

Teematiedostoissa tai lisäosissa shortcodet suoritetaan do_shortcode()-funktiolla:

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

Funktio ottaa merkkijonon, joka sisältää shortcoden, ja palauttaa sen suorituksen tuloksen. Se on hyödyllinen, kun shortcoden tuloste pitää upottaa PHP-logiikkaan, esimerkiksi header.php-tiedostoon tai loopin sisälle.

Datan välittäminen shortcodelle: kaksi tapaa

Tapa 1: sisältö tagien välissä

Sijoita data avaavan ja sulkevan tagin väliin:

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

Callback vastaanottaa merkkijonon from John to Mary toisen parametrin $content kautta:

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

Tulos: "Hello from John to Mary World!".

Tapa 2: attribuutit

Välitä parametrit suoraan avaavassa tagissa:

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

Callback-funktiossa attribuutit ovat saatavilla ensimmäisen parametrin $attributes kautta, assosiatiivisena taulukkona, jossa avaimet vastaavat attribuuttien nimiä:

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

Tuloste: "Hello from John to Mary!". Attribuutit sopivat paremmin jäsennellylle datalle (hinta, URL, ID), kun taas tagien välinen sisältö sopii paremmin vapaamuotoiselle tekstille.

Käytännössä attribuutteihin kannattaa heti lisätä shortcode_atts(), WordPressin sisäänrakennettu funktio, joka yhdistää annetut attribuutit oletusarvojen taulukkoon. Ilman sitä $attributes['from']-kohdan käyttö aiheuttaa PHP-huomautuksen, jos käyttäjä ei määrittänyt attribuuttia. shortcode_atts()-funktiolla saat aina täytetyn taulukon: määritellyt avaimet varoarvoineen, ja tuntemattomat attribuutit suodatetaan automaattisesti pois.

Kaksi käyttövalmista shortcodea WordPressille

1. Automaattinen kuluva vuosi

[current-year]-shortcode lisää kuluvan vuoden itsestään, ei tarvetta päivittää päivämäärää alatunnisteessa joka tammikuu:

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

Sijoita [current-year] alatunnisteeseen tai artikkelitekstiin, ja vuosi päivittyy automaattisesti.

2. Rekisteröityneiden käyttäjien lista

[users-list]-shortcode tulostaa kaikkien sivuston käyttäjien nimet luettelomerkittynä listana. Hyödyllinen "Tiimi"-sivulla tai ylläpidon raporteissa:

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() ilman argumentteja palauttaa kaikki käyttäjät. Rajataksesi kyselyn roolin mukaan, anna taulukko: get_users( [ 'role' => 'editor' ] ). Koodi sijoitetaan aktiivisen teeman functions.php-tiedostoon tai mukautettuun lisäosaan.

Video: shortcodejen luominen WordPressissä

Lyhyt video aiheesta, shortcoden rekisteröinti alusta alkaen, funktion kirjoittamisesta testaamiseen editorissa:

⁉️🤔 Usein kysytyt kysymykset

Mitä tapahtuu, jos kaksi lisäosaa rekisteröi shortcoden samalla tagilla?

WordPress suorittaa sen, joka latautui viimeisenä. Ensimmäinen shortcode ohitetaan hiljaisesti, ilman virheitä. Siksi shortcodeissasi kannattaa aina käyttää etuliitettä: [acme_gallery] eikä [gallery]. Tämä poistaa ristiriidat minkä tahansa muun lisäosan tai teeman kanssa.

Voiko shortcodeja kutsua toisten shortcodejen sisällä?

Kyllä. Jos ensimmäisen shortcoden callback palauttaa merkkijonon, joka sisältää toisen shortcoden tagin, WordPress käsittelee sisäkkäisen shortcoden automaattisesti. Mutta älä unohda do_shortcode()-funktiota: jos rakennat sisältöä manuaalisesti ja se sisältää shortcodeja, aja merkkijono do_shortcode()-funktion läpi eksplisiittisesti. Tavallinen the_content-toiminto tekee tämän itse, mutta suora callback-kutsu ei.

Missä shortcode-koodin pitäisi sijaita, teemassa vai lisäosassa?

Mukautetut shortcodet kantavat toiminnallisuutta, eivät ulkoasua, joten ne on parempi erottaa erilliseen lisäosaan. Teeman vaihtaminen ei riko sivustoa: shortcodet jatkavat toimintaansa. Käytä vähintään lapsiteemaa, jos olet varma, ettet vaihda pääteemaa.

Onko tagin nimelle rajoituksia?

Nimen tulee koostua latinalaisista kirjaimista, numeroista ja yhdysviivoista. Välilyönnit, alaviivat ja erikoismerkit eivät ole sallittuja. Suositeltu pituus on enintään 20 merkkiä, pienillä kirjaimilla. Esimerkki: [my-plugin-shortcode].

Miten shortcodea debugataan, jos se ei tulosta mitään?

Ensimmäinen askel, ota WP_DEBUG käyttöön wp-config.php-tiedostossa. Toinen, tarkista, että callback palauttaa arvon return-komennolla, ei echo-komennolla. Kolmas, varmista, että init-koukku on läsnä. Jos virheitä ei ole, mutta tuloste on tyhjä, lisää error_log() callbackin sisälle ja tarkista palvelimen lokit.

Mitä WordPress-shortcodeista kannattaa muistaa

Shortcodet ovat kypsä ja vakaa mekanismi. add_shortcode() ei ole muuttunut vuosiin: tag, callback, init-koukku, return eikä echo. Muista nämä neljä asiaa, ja mikä tahansa mukautettu shortcode toimii ensimmäisellä yrittämällä.

• Jos tulostat vuoden alatunnisteeseen, nappaa valmis [current-year].
• Jos tarvitset käyttäjälistan, [users-list] roolisuodattimella.
• Jos kirjoitat oman shortcodesi alusta alkaen, käytä aina etuliitettä ja aina init-koukkua.

Seuraavana askeleena tutustu shortcoden paketointiin itsenäiseksi lisäosaksi ja sen lähettämiseen WordPress.org-hakemistoon, se on paras tapa erottaa toiminnallisuus teemasta ja nostaa kehittäjäprofiiliasi.