⚡ Kuinka lisätä oma shortcode WordPressissä: esimerkkejä ja koodi

Sinun täytyy tulostaa artikkelin viimeisin päivityspäivämäärä jokaisen artikkelin alatunnisteeseen. Tai lisätä tilauslomake tarkalleen tekstin keskelle ilman koodieditoria ja mallinevoimistelua. WordPressissä shortcodet ovat työkalu tähän.

Shortcode on lyhyt tunniste hakasulkeissa: [myshortcode]. WordPress löytää sen sisällöstä ja korvaa sen PHP-funktion tuloksella. Käytät vakio-shortcodeja, kuten [gallery] ja [embed], koko ajan sitä edes ajattelematta. Mutta oma shortcodesi on vipuvarsi: kirjoitat logiikan kerran, ja toimittaja lisää sen minne tahansa kolmella klikkauksella.

Kymmenessä minuutissa luot ensimmäisen toimivan shortcodesi: tyhjästä funktiosta tunnisteeseen, jossa on attribuutteja ja sisään suljettua sisältöä. Koodi on aitoa, toimii missä tahansa modernissa WordPressissä, ja se on testattu staging-sivustolla.

💡 Pikaopas:

• add_shortcode-funktio: mitä se hyväksyy ja miten se toimii sisäisesti
• Perus [current_year]-shortcode, kuluva vuosi tekstinä
• Shortcode attribuuteilla [cta text="Скачать"], mukautettu painike
• Shortcode suljetulla sisällöllä [notice]Текст[/notice], tyylitelty lohko
• Lisääminen liitännäisen tai functions.php:n kautta: kummankin lähestymistavan hyvät ja huonot puolet
• Yleiset virheet: echo returnin sijaan, nimikonfliktit, tyhjä attribuutti PHP 8+:ssa

Mitä add_shortcode voi tehdä ja miten se toimii

add_shortcode-funktio on ainoa standardi tapa rekisteröidä uusi shortcode WordPressissä. Se hyväksyy kaksi parametria:

• $tag (merkkijono), shortcoden nimi, jonka kirjoitat hakasulkeisiin. Vain kirjaimet, numerot ja alaviivat. Välilyönnit ja erikoismerkit & / < > [ ] = ovat kiellettyjä; WordPress kieltäytyy hiljaisesti rekisteröimästä tällaista tunnistetta.
• $callback (kutsuttava), sen PHP-funktion nimi, joka suoritetaan, kun shortcode löytyy. Tämä funktio tuottaa HTML:n, jonka kävijä näkee.

Funktion lähdekoodi, viisi riviä logiikkaa ja kaksi järkevyystarkistusta (koko listaus osoitteessa developer.wordpress.org):

1
function add_shortcode( $tag, $callback ) {
2
    global $shortcode_tags;
3
 
4
    if ( '' === trim( $tag ) ) {
5
        _doing_it_wrong(
6
            __FUNCTION__,
7
            __( 'Invalid shortcode name: Empty name given.' ),
8
            '4.4.0'
9
        );
10
        return;
11
    }
12
 
13
    if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
14
        _doing_it_wrong(
15
            __FUNCTION__,
16
            sprintf(
17
                /* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
18
                __( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
19
                $tag,
20
                '& / < > [ ] ='
21
            ),
22
            '4.4.0'
23
        );
24
        return;
25
    }
26
 
27
    $shortcode_tags[ $tag ] = $callback;
28
}

Avainkohta: $shortcode_tags, globaali taulukko. WordPress tallentaa siihen kaikki rekisteröidyt shortcodet. Sisällön renderöinnin aikana ydin käy tämän taulukon läpi ja kutsuu kuhunkin löydettyyn tunnisteeseen liittyvää funktiota. Tästä seuraa kaksi asiaa:

• Rekisteröi init****-koukussa. Jos kutsut add_shortcode-funktiota suoraan liitännäistiedostossa, se voi suorittua ennen kuin WordPress on täysin alustettu. Oikea tapa on kääriä se koukkuun:

1
add_action( 'init', 'my_register_shortcodes' );
2
 
3
function my_register_shortcodes() {
4
    add_shortcode( 'mytag', 'my_shortcode_callback' );
5
}

• Etuliite on pakollinen. Globaali taulukko on kaikkien liitännäisten ja teeman yhteinen. Jos nimeät shortcoden [button], sinun [button]-shortcodesi korvaa hiljaisesti lomakeliitännäisen samannimisen shortcoden. Etuliite, kuten myplugin_ tai uniikki lyhenne, ratkaisee ongelman. Alla olevissa esimerkeissä käytän mysite_-etuliitettä; oikeassa projektissa korvaa se omallasi.

Vaihe 1: yksinkertainen shortcode ilman parametreja

Lyhin reitti toimivaan shortcodeen, kolme riviä lapsiteemasi functions.php-tiedostossa (tai Code Snippets -liitännäisessä, joka on turvallisempi eikä katoa teemapäivityksessä).

Lisää tämä koodi ja tallenna:

1
add_shortcode( 'mysite_current_year', 'mysite_display_current_year' );
2
 
3
function mysite_display_current_year() {
4
    return date( 'Y' );
5
}

Kirjoita nyt [mysite_current_year] mihin tahansa artikkeliin tai sivuun. Julkisella puolella kuluva vuosi ilmestyy shortcoden tilalle: "2026".

Mitä tässä tapahtuu. mysite_display_current_year-funktio ei ota argumentteja, kutsuu PHP-funktiota date('Y') ja palauttaa nelinumeroisen merkkijonon. WordPress lisää tämän merkkijonon tarkalleen siihen kohtaan, johon shortcode sijoitettiin. Ei mitään taikuutta.

Missä tätä kannattaa käyttää käytännössä: vuosiluku alatunnisteessa (© [mysite_current_year]), projektin ikä tekstissä ("toiminnassa vuodesta [mysite_current_year]"), automaattinen päivitys lakisääteisten vaatimustenmukaisuussivujen päivämääriin.

Vaihe 2: shortcode, jolla on attribuutteja

Shortcode ilman parametreja on hyödyllinen, mutta todellinen joustavuus alkaa attribuuteista. Klassinen esimerkki: painike, jossa on muokattava teksti ja linkki:

1
add_shortcode( 'mysite_cta', 'mysite_cta_button' );
2
 
3
function mysite_cta_button( $atts ) {
4
    $atts = shortcode_atts(
5
        array(
6
            'text' => 'Learn more',
7
            'url'  => '#',
8
        ),
9
        $atts,
10
        'mysite_cta'
11
    );
12
 
13
    return sprintf(
14
        '<a href="%s" class="mysite-cta-button">%s</a>',
15
        esc_url( $atts['url'] ),
16
        esc_html( $atts['text'] )
17
    );
18
}

Editorissa sitä käytetään näin:

1
[mysite_cta text="Download plugin" url="https://example.com/myplugin/"]

shortcode_atts-funktio tekee kolme asiaa kerralla: se yhdistää käyttäjän antamat attribuutit oletusarvoihin, suodattaa vain tunnetut avaimet ja normalisoi tyhjän merkkijonon taulukoksi (ilman sitä [mysite_cta]-kutsu ilman attribuutteja PHP 8+:ssa aiheuttaisi TypeErrorin, koska callback-funktion ensimmäinen parametri saisi tyhjän merkkijonon taulukon sijaan).

*Miksi esc_url ja esc_html.* Shortcoden lisää editori, tänään se olet sinä ja huomenna sisällönhallitsija, jolla ei ole koodioikeuksia. Tulosteen escapaus suojaa vahingossa tapahtuvalta XSS:ltä, jos text-attribuuttiin päätyy kulmasulku tai tagi.

Vaihe 3: shortcode, jolla on sisään suljettua sisältöä

Jotkin shortcodet kietovat sisäänsä tekstikatkelman: [mysite_notice]Важное сообщение[/mysite_notice]. Sisään suljettu sisältö saapuu callbackiin toisena parametrina, $content. Tyypillinen käyttötapaus on tyylitelty varoituslaatikko:

1
add_shortcode( 'mysite_notice', 'mysite_notice_box' );
2
 
3
function mysite_notice_box( $atts, $content = null ) {
4
    $atts = shortcode_atts(
5
        array(
6
            'type' => 'info',
7
        ),
8
        $atts,
9
        'mysite_notice'
10
    );
11
 
12
    $class = 'notice-' . esc_attr( $atts['type'] );
13
 
14
    return sprintf(
15
        '<div class="mysite-notice %s"><p>%s</p></div>',
16
        $class,
17
        do_shortcode( $content )
18
    );
19
}

Huomaa do_shortcode( $content ). Jos editori lisäsi shortcodesi sisään toisen shortcoden (esimerkiksi [mysite_current_year]), tämä wrapper suorittaa senkin. Ilman do_shortcode-funktiota sisäkkäiset shortcodet näkyvät tekstinä hakasuluissa, raakana [mysite_current_year]-merkkijonona eikä "2026".

Laatikon CSS, minimaalinen versio alkuun pääsemiseksi:

1
.mysite-notice {
2
    border-left: 4px solid #2271b1;
3
    background: #f0f6fc;
4
    padding: 1em 1.2em;
5
    margin: 1.5em 0;
6
    border-radius: 4px;
7
}
8
.mysite-notice.notice-warning {
9
    border-left-color: #dba617;
10
    background: #fcf9e8;
11
}

Lisää tyylit lapsiteemasi style.css-tiedostoon tai polun Ulkoasu → Mukauta → Lisä-CSS kautta.

Vaihe 4: shortcode lisäosassa (olio-ohjelmointitapa)

Kun sinulla on yli kolme shortcodea, functions.php muuttuu kaatopaikaksi. On aika siirtää logiikka erilliseen lisäosaan ja mielellään luokkaan. Tässä on minilisäosan runko yhdellä shortcodella:

1
<?php
2
/**
3
 * Plugin Name:  MySite Shortcodes
4
 * Description:  Custom shortcodes for the site.
5
 * Version:      1.0.0
6
 * Requires PHP: 7.4
7
 */
8
 
9
defined( 'ABSPATH' ) || exit;
10
 
11
class MySite_Shortcodes {
12
 
13
    public static function init() {
14
        add_action( 'init', array( __CLASS__, 'register' ) );
15
    }
16
 
17
    public static function register() {
18
        add_shortcode( 'mysite_email', array( __CLASS__, 'email_obfuscated' ) );
19
    }
20
 
21
    public static function email_obfuscated( $atts ) {
22
        $atts = shortcode_atts(
23
            array( 'address' => '' ),
24
            $atts,
25
            'mysite_email'
26
        );
27
 
28
        if ( ! is_email( $atts['address'] ) ) {
29
            return '';
30
        }
31
 
32
        return sprintf(
33
            '<a href="mailto:%1$s">%1$s</a>',
34
            antispambot( $atts['address'], 1 )
35
        );
36
    }
37
}
38
 
39
MySite_Shortcodes::init();

Sijoita tämä tiedosto polkuun wp-content/plugins/mysite-shortcodes/mysite-shortcodes.php ja aktivoi lisäosa hallintapaneelissa. Shortcode [mysite_email address="hello@example.com"] tulostaa roskapostisuojatun linkin; antispambot-funktio koodaa sähköpostiosoitteen merkit HTML-entiteeteiksi.

Miksi luokka, ei joukko funktioita. Nimiavaruus: kolme shortcodea luokassa eivät törmää kolmannen osapuolen funktioihin. Lisäksi autoloading ja luettavampi koodi, jos lisäosa kasvaa tusinaan shortcodeen.

Shortcoden testaaminen ennen julkaisua

Kun koodi on lisätty, tarkista kolme skenaariota:

• Shortcode ilman attribuutteja. Pelkkä [mysite_cta], sen pitäisi renderöityä oletusarvoilla (teksti "Lue lisää", linkki #).
• Shortcode attribuuteilla. Täysi parametrisetti, kaikki arvot poimitaan ja näytetään oikein.
• Virhe attribuuteissa. Virheellinen sähköpostiosoite [mysite_email]-shortcodessa, funktio palauttaa hiljaisesti tyhjän merkkijonon rikkomatta sivua.

Tärkeää: *älä koskaan käytä echo-komentoa callback-funktion sisällä.* Shortcoden on palautettava merkkijono return-lauseella. Jos tulostat HTML:ää echo-komennolla, se ilmestyy ei shortcoden kohdalle, vaan sivun yläreunaan, koska WordPress suorittaa shortcodejen renderöinnin ennen sisällön tulostusta. Sama logiikka kuin filttereissä: funktio antaa arvon takaisin, ja moottori itse päättää, mihin se sijoitetaan.

Toinen vivahde: jos shortcode ei näy (näet [mysite_cta] tekstinä, et painikkeena), tarkista, että funktio on rekisteröity init-koukkuun, ei suoraan lisäosan runkoon. Ilman init-koukkua globaali $shortcode_tags-taulukko ei välttämättä ole vielä valmis ottamaan vastaan uusia tageja.

Shortcode teemassa vs. lisäosassa: kumpi valita

Sääntö: aloita functions.php-tiedostolla testisivustolla, rakenna kolme shortcodea ja siirrä ne sitten lisäosaan. Puolen vuoden päästä tuleva teemapäivitys ei hautaa logiikkaasi, ja voit siirtää shortcodet toiseen projektiin minuutissa.

⁉️🤔 UKK

Mitä eroa on shortcodella ja Gutenberg-lohkolla?

Shortcode on hakasulkeissa oleva tekstikoodi, joka käsitellään palvelinpuolella. Lohko on visuaalisen editorin komponentti, React-komponentti, jonka asetukset ovat sivupalkissa. Shortcodet tulivat WordPressiin versiossa 2.5 (2008), lohkot versiossa 5.0 (2018). Nykyään lohkot ovat ensisijainen tapa lisätä dynaamista sisältöä, mutta shortcodet ovat yhä käyttökelpoisia: niiden kehittäminen on yksinkertaisempaa, ne eivät vaadi JavaScript-osaamista ja ne toimivat missä tahansa editorissa, mukaan lukien Classic Editor ja sivunrakentajat.

Shortcode on tekstikoodi, jonka WordPress korvaa PHP-funktion tuloksella sivua renderöidessään. Toisin kuin Gutenberg-lohkolla, shortcodella ei ole visuaalista käyttöliittymää editorissa: sisällöntuottaja kirjoittaa [myshortcode] tekstinä ja näkee valmiin HTML:n lopputuloksessa.

Voinko käyttää shortcodea toisen shortcoden sisällä?

Kyllä. Jos ulomman shortcoden callback-funktio käsittelee sisäkkäisen sisällön do_shortcode()-funktiolla, sisemmät shortcodet toimivat oikein: [notice][current_year][/notice] tulostaa tyylitellyn lohkon, jossa on kuluva vuosi. Ilman do_shortcode()-kutsua sisäkkäinen shortcode jää hakasulkeissa olevaksi tekstiksi.

Sisäkkäiset shortcodet käsitellään rekursiivisesti: WordPress käy merkkijonon läpi useita kertoja, kunnes käsittelemättömiä tageja ei ole jäljellä. Mutta jotta tämä toimisi, ulomman shortcoden täytyy nimenomaisesti kutsua do_shortcode($content). Muuten merkkijono [current_year] jää tekstiksi sen sijaan, että se muuttuisi muotoon "2026".

Miksi shortcodeni ei toimi ja se näkyy hakasulkeissa olevana tekstinä?

Kolme yleistä syytä. Ensimmäinen: add_shortcode kutsutaan ennen init-koukkua, siirrä rekisteröinti add_action('init', ...)-kutsun sisään. Toinen: kirjoitusvirhe tagin nimessä, editorissa on [my_shortcode] mutta rekisteröity on myshortcode. Kolmas: callback-funktio käyttää echo-komentoa return-komennon sijaan, jolloin tuloste menee sivun alkuun ja shortcoden paikka jää tyhjäksi.

Yleisin syyllinen on echo return-komennon sijaan callback-funktiossa. WordPress kutsuu shortcode-käsittelijöitä ennen pääsisällön tulostamista, joten echo-komennon tulos osuu tulostuspuskuriin ennen sivun otsikkotietoja. Avaa sivun lähdekoodi (Ctrl+U): jos näet shortcoden HTML:n aivan ylhäällä, ennen <html>-tagia, ongelma on juuri tämä.

Täytyykö shortcoden tuloste suojata?

Ehdottomasti. Shortcode vastaanottaa attribuutteja editorista, eli mahdollisesti keneltä tahansa käyttäjältä, jolla on author- tai editor-oikeudet. esc_html() tekstille, esc_url() linkeille, esc_attr() HTML-attribuuteille. Poikkeuksena on tilanne, jossa palautat tarkoituksella HTML-merkkausta (kuten <div class="notice">). Mutta silloinkin suojaa attribuutit merkkausten sisällä.

Kyllä, suojaaminen on pakollista kaikelle, mikä tulee shortcoden attribuuteista tai käyttäjän syötteestä. Vaikka tänään vain sinä lisäät shortcodeja, huomenna sisällöntuottaja saa editor-oikeudet. esc_html() tekstille, esc_url() linkeille, esc_attr() HTML-attribuuteille suojaavat tahattomalta tai tahalliselta XSS:ltä.

Kuinka monta shortcodea voin rekisteröidä yhdelle sivustolle?

Teknistä rajaa ei ole: $shortcode_tags on tavallinen PHP-taulukko, ja palvelimen muistiraja tulee vastaan paljon myöhemmin kuin terve järki. Käytännössä 15-20 mukautetun shortcoden jälkeen kannattaa kysyä: onko aika siirtää osa niistä Gutenberg-lohkoiksi? Pidä shortcodet, joissa on uniikkia logiikkaa (sähköpostin piilotus, ehdollinen tulostus roolin mukaan). Shortcodeille, jotka vain tyylittävät tekstiä ([highlight]), on parempi käyttää lohkotyylejä tai CSS-luokkaa.

Teknisesti niin monta kuin haluat: $shortcode_tags-taulukolla ei ole keinotekoista rajaa. Käytännössä yli 20-25 shortcodea yhdellä sivustolla viittaa siihen, että osa logiikasta kannattaisi siirtää lohkoihin. Jokainen shortcode lisää sisällön jäsentämisen kuormaa: ennen tulostusta WordPress käy läpi koko rekisteröityjen tagien taulukon ja etsii osumia julkaisun tekstistä.

Kannattaako kirjoittaa omat shortcodet vai riittävätkö valmiit lisäosat?

Valmis lisäosa kattaa useimmat tyypilliset tehtävät: lomakkeet, Contact Form 7, taulukot, TablePress, ruudukot, mikä tahansa sivunrakentaja. Mukautettua shortcodea tarvitaan, kun logiikka on sivustollesi ominainen eikä valmista ratkaisua ole: juuri tämän mukautetun kentän tulostaminen tähän kohtaan sivua, seuraavan webinaarin päivämäärä tietokannasta, personoitu tervehdys käyttäjän roolin perusteella.

Lyhyesti: vakiotoiminnallisuuteen käytä lisäosaa äläkä koodaa. Uniikkiin logiikkaan add_shortcode + functions.php tai minilisäosa. Koodi kaikissa yllä olevissa esimerkeissä on alle kymmenen riviä. Kun hallitset nämä kolme mallia (yksinkertainen, attribuuteilla, sisäkkäisellä sisällöllä), katat valtaosan tehtävistä, joita varten mukautettuja shortcodeja ylipäätään kirjoitetaan.