Kuvittele tilanne: lisäät artikkeliin 20 kuvan galleriaa. Ilman shortcodeja se tarkoittaa kymmeniä rivejä HTML:ää, jossa on kääreitä, luokkia, data-attribuutteja ja pikkukuvallisia linkkejä. Shortcodella se on yksi rivi: [gallery]. Juuri tämän rutiininomaisen työmäärän ja lopputuloksen välisen kontrastin vuoksi WordPress 2.5 toi shortcodet, ja lähes kaksi vuosikymmentä myöhemmin mekanismi on yhä korvaamaton.

Ongelma on, että useimmat käyttäjät joko pelkäävät shortcodeja "ohjelmoijan taikuutena" tai kopioivat niitä sokeasti ymmärtämättä syntaksia. Samaan aikaan yksi räätälöity shortcode voi korvata neljänkymmenen megatavun lisäosan tai säästää tunnin rutiinityötä kuukaudessa. Tämä perusteellinen katsaus, sisäänrakennetusta [gallery]- ja [audio]-shortcodesta omaan shortcodeesi functions.php-tiedostossa, antaa sinulle täyden hallinnan tähän työkaluun.

💡 Pikakatsaus:

• Mikä shortcode on: hakasulkeissa oleva tunniste, jonka WordPress korvaa PHP-funktion tuloksella sivua ladattaessa.
• Sisäänrakennetut shortcodet: gallery, audio, video, caption, embed ja playlist toimivat heti WordPressin asennuksen jälkeen ilman lisäosia.
• Shortcoden parametrit: key="value"-syntaksilla voit mukauttaa tulostetta muuttamatta koodia.
• Oman shortcoden luominen: yksinkertaisesta URL-korvauksesta kuvashortcodeen attribuuteilla, valmista PHP-koodia functions.php-tiedostoon.
• Shortcodet vimpaimissa ja teemapohjissa: miten tuki otetaan käyttöön yhdellä rivillä ja missä siitä on hyötyä.

Mikä shortcode on ja miten se toimii

Shortcode on lyhyt hakasulkeissa oleva tunniste, jonka WordPress korvaa PHP-funktion suorituksen tuloksella sillä hetkellä, kun sivu renderöidään. Kirjoitat editorissa [gallery], kävijät näkevät siistin kuvien ruudukon. Ei taikuutta: jokaisen shortcoden takana on funktio, joka on rekisteröity add_shortcode()-funktiolla ytimessä, teemassa tai lisäosassa.

Keskeinen ero staattisiin HTML-lisäyksiin: shortcode suoritetaan palvelinpuolella. Annat sille parametreja, ja tulos luodaan dynaamisesti. Sisältö muuttuu, tuloste muuttuu ilman, että kymmeniä sivuja tarvitsee muokata käsin.

Editorin näkökulmasta on yksi vivahde. Visuaalinen editori (Gutenberg tai klassinen TinyMCE) renderöi shortcoden heti esikatseluksi, joten parametrien ja sisäkkäisten tunnisteiden käsittelyä varten sinun on vaihdettava tekstimuotoon. Vain siellä näet todellisen rakenteen: aloitustunnisteen, attribuutit, sisällön ja lopetustunnisteen.

Sisäänrakennetut WordPress-shortcodet: mitä on saatavilla ilman lisäosia

WordPress sisältää kuusi rekisteröityä shortcodea. Sinun ei tarvitse ottaa niitä käyttöön tai määrittää niitä, lisää ne vain artikkeliin ja saat tulokset.

Näistä joustavin on [gallery]. ids-attribuutilla voit määrittää tietyt kuvat ID:n perusteella, myös ne, joita ei ole liitetty nykyiseen artikkeliin. size-attribuutti asettaa pikkukuvan koon (thumbnail, medium, large tai full). Näiden kahden parametrin yhdistelmä kattaa useimmat skenaariot, joita varten aiemmin asennettiin erillinen gallerialisäosa.

[audio] ja [video] tukevat useita lähteitä, selain valitsee yhteensopivan formaatin. Soittolistat [playlist]-shortcodella kootaan liitetiedostojen ID:stä gallerian tapaan, mutta ne tulostavat soittimen, jossa on kappaleiden vaihto.

Shortcoden parametrit: miten tulostetta hallitaan

Useimmat shortcodet hyväksyvät attribuutteja key="value"-muodossa. Arvojen korvaaminen muuttaa funktion logiikkaa puuttumatta koodiin.

Otetaan [gallery]. Ilman parametreja se näyttää kaikki artikkelin kuvat vakiokoossa. Lisää tarkennuksia:

1
[gallery ids="12,34,56" size="large" columns="3"]

Nyt tuloste on rajattu kolmeen määritettyyn kuvaan, koko on suurennettu arvoon large ja ruudukko on järjestetty kolmeen sarakkeeseen. Parametreja voi yhdistellä vapaasti, ja ne, joita ei määritetä, saavat oletusarvonsa.

Jotkin shortcodet käyttävät aloitus- ja lopetustunnisteita, kun niiden välissä on tarpeen välittää sisältöä. Esimerkiksi Google Maps -lisäosa saattaa odottaa tällaista rakennetta:

1
[maps]New York, USA[/maps]

Lopetustunniste alkaa aina kauttaviivalla /. WordPress käyttää tätä merkintätapaa erottaakseen tunnisteiden välisen sisällön aloitustunnisteen sisällä olevista attribuuteista.

Miten luot oman shortcoden

Kun olet lisännyt saman URL-osoitteen, HTML-lohkon tai toimintakehotteen artikkeleihin kymmenennen kerran viikon aikana, on aika kirjoittaa shortcode. Tämä ei vaadi PHP-kehittäjän taitoja: perusrakenne mahtuu kolmeen riviin.

Yksinkertainen shortcode URL-osoitteelle

Lisää tämä koodi teemasi functions.php-tiedoston loppuun (Ulkoasu → Teemaeditori → functions.php):

1
function techblog_short_url() {
2
    return 'https://techblog.sdstudio.top';
3
}
4
add_shortcode( 'techblog', 'techblog_short_url' );

Nyt missä tahansa artikkelissa [techblog] korvataan automaattisesti sivuston URL-osoitteella. Funktio palauttaa merkkijonon, ja WordPress sijoittaa sen shortcoden paikalle.

Kaksi kriittisen tärkeää sääntöä virallisesta dokumentaatiosta:

• Funktio palauttaa arvon return-lausekkeella, ei tulosta echo-komennolla. Suora tulostus rikkoo renderöintijärjestyksen ja johtaa odottamattomiin tuloksiin.
• Rekisteröi shortcodet init-koukussa, jotta WordPress ehtii ladata kaikki riippuvuudet:

1
add_action( 'init', 'techblog_register_shortcodes' );
2
function techblog_register_shortcodes() {
3
    add_shortcode( 'techblog', 'techblog_short_url' );
4
}

Shortcode kuvalle, jossa on muokattavia attribuutteja

Hieman monimutkaisempi tilanne: haluat lisätä kuvan ja määrittää leveyden ja korkeuden suoraan editorissa. functions.php-tiedostossa:

1
function techblog_img_shortcode( $atts, $content = null ) {
2
    $atts = shortcode_atts(
3
        array(
4
            'width'  => '',
5
            'height' => '',
6
        ),
7
        $atts,
8
        'img'
9
    );
10
    return '<img src="' . esc_url( $content ) . '" width="' . esc_attr( $atts['width'] ) . '" height="' . esc_attr( $atts['height'] ) . '" alt="" />';
11
}
12
add_shortcode( 'img', 'techblog_img_shortcode' );

Käyttö editorissa:

1
[img width="800" height="600"]https://example.com/photo.jpg[/img]

shortcode_atts()-funktio yhdistää annetut attribuutit oletusarvoihin, tämä on standardi ja turvallinen tapa käsitellä parametreja. Huomaa esc_url() ja esc_attr(): escapointi on pakollista, kun tulostat käyttäjän syötettä julkisella puolella. Täydellinen lista käytettävissä olevista kuvan attribuuteista löytyy W3C-spesifikaatiosta.

Erillisen maininnan ansaitsee attribuuttien validointi. Kun otat vastaan arvoja editorista ja lisäät ne HTML:ään, tarkista aina tietotyypit. Numeerisille attribuuteille, kuten width ja height, käytä intval()-funktiota, tämä leikkaa pois mahdolliset kirjaimet. Merkkijonoille aseta sallittu arvojoukko in_array()-funktion avulla, esimerkiksi pienoiskuvakoot (thumbnail, medium, large). Näin asettelu pysyy ehjänä ja julkisen puolen tulokset ovat ennustettavia, vaikka kirjoittaja tekisi virheen attribuutin arvossa.

Shortcodet tekstiwidgeteissä ja PHP-tiedostoissa

WordPress-versiosta 4.9 (marraskuu 2017) lähtien shortcodet toimivat automaattisesti tekstiwidgeteissä. Mutta jos käytät mukautettua teemaa ilman sisäänrakennettua tukea, voit ottaa sen käyttöön yhdellä rivillä functions.php-tiedostossa:

1
add_filter( 'widget_text', 'do_shortcode' );

Välttääksesi <p>- ja <br>-tagien automaattisen lisäämisen shortcoden ympärille widgetissä (WordPress muotoilee rivinvaihdot automaattisesti), lisää myös:

1
add_filter( 'widget_text', 'shortcode_unautop' );

Sama periaate toimii PHP-pohjissa. Jos sinun täytyy suorittaa shortcode suoraan header.php-tiedostossa tai muussa teematiedostossa, kääri se do_shortcode()-funktioon:

1
echo do_shortcode( '[techblog]' );

Näin sama logiikka on käytettävissä editorissa, widgetissä ja pohjassa ilman koodin kopiointia.

Koodin näyttäminen: miten shortcode-teksti esitetään ilman suoritusta

Joskus shortcodea ei haluta suorittaa, vaan sen syntaksi pitää näyttää lukijalle, kuten tässä artikkelissa. Jos kirjoitat editoriin pelkän [gallery], WordPress suorittaa sen heti tai näyttää paikkamerkin. Tämän voi välttää kahdella tavalla.

Tuplahakasulkeet. Yksinkertaisin tapa on tuplata uloimmat sulkeet:

1
[[gallery]]

Parillisissa tageissa ensimmäinen avaava ja viimeinen sulkeva tuplataan:

1
[[maps]New York, USA[/maps]]

HTML-merkkikoodit. Tekstimuotoisessa editorissa hakasulkeet voi korvata niiden ASCII-koodeilla: [ merkin [ sijaan ja ] merkin ] sijaan. Merkintä [gallery] näkyy tekstinä [gallery], mutta sitä ei suoriteta.

Ensimmäinen tapa on yksinkertaisempi ja lähdekoodissa luettavampi, toinen on luotettavampi monimutkaisen muotoilun kanssa. Valitse tuplahakasulkeet nopeisiin muokkauksiin tekstieditorissa ja ASCII-koodit silloin, kun shortcode on muiden hakasulkeiden vieressä, esimerkiksi koodilohkojen sisällä tai metakenttien kuvauksissa. Molemmissa tapauksissa sivuston kävijät näkevät juuri shortcode-tekstin, eikä WordPress suorita sitä.

Video: WordPress-shortcodet perusteellisesti

Niille, jotka pitävät visuaalisesta selityksestä, tässä on Kinstan tiimin yksityiskohtainen opas. Tekijä näyttää shortcoden luomisen, virheenkorjauksen ja aitoja esimerkkejä live-projektissa teeman asennuksesta frontend-tulosteeseen asti.

⁉️🤔 Usein kysytyt kysymykset

Voiko shortcodeja käyttää Gutenbergissa?

Kyllä, "Shortcode"-lohkon kautta, joka löytyy lohkonlisäyspaneelista. Shortcode lisätään lohkon kenttään, ja WordPress suorittaa sen renderöinnin yhteydessä. Monimutkaiset shortcodet, joissa on sisäkkäistä sisältöä, voivat kuitenkin toimia arvaamattomasti, jolloin on luotettavampaa vaihtaa koodinmuokkaustilaan. Gutenberg renderöi shortcodet palvelinpuolen callbackin kautta, joten lopputulos riippuu siitä, palauttaako funktio oikeaa HTML:ää. Lohkoteemat (Full Site Editing) ja theme.json saattavat osittain rajoittaa shortcoden tulostusta mallipohjissa, joten tarkista teeman yhteensopivuus.

Mitä tehdä, jos shortcode ei toimi?

Tarkista kolme tyypillistä syytä. Ensimmäinen: lisäsit shortcoden visuaalisessa editorissa, joka muutti hakasulkeet HTML-entiteeteiksi, vaihda tekstimuotoon ja varmista, että sulkeet ovat tavalliset. Toinen: shortcoden rekisteröivä lisäosa on poistettu käytöstä, mene "Lisäosat"-osioon ja tarkista tila. Kolmas: shortcode-funktio käyttää echo-komentoa return-komennon sijaan, tämä on kehittäjän virhe, ja tuloste ilmestyy väärään kohtaan sivulla. Järjestelmällinen vianmääritys: avaa wp-config.php, ota käyttöön WP_DEBUG ja WP_DEBUG_LOG. Kun olet ladannut shortcoden sisältävän sivun, tarkista wp-content/debug.log, sieltä löytyvät tarkat PHP-virheet, jotka osoittavat tiedoston ja rivin.

Voiko shortcodeen lisätä suoraan PHP-koodia?

Ei. Shortcode on liipaisin, ei säiliö mielivaltaiselle koodille. Palvelinpuolella add_shortcode()-funktiolla rekisteröity funktio suorittaa toiminnon. Jos tarvitset mukautettua logiikkaa, kirjoita se functions.php-tiedostoon (tai erilliseen lisäosaan) ja sido se shortcodeen. Hakasulkeiden väliin voi välittää vain sisältöä ja attribuutteja, ei suoritettavaa koodia. Turvallista PHP:n suorittamista sisällössä varten tutustu lisäosiin, kuten "Code Snippets", niiden avulla voit hallita koodinpätkiä hallintaliittymän kautta muokkaamatta functions.php-tiedostoa ja suojattuna vakavilta virheiltä.

Hidastavatko shortcodet sivustoa?

Itsessään eivät. add_shortcode() ainoastaan rekisteröi tagin ja funktion vastaavuuden globaaliin $shortcode_tags-taulukkoon. Kuormaa syntyy, kun shortcode-funktio suorittaa raskaita tietokantakyselyjä tai ulkoisia API-kutsuja jokaisella sivulatauksella. Ongelma ei ole shortcode-mekanismissa, vaan tietyn lisäosan toteutuksessa. Ohje: jos sivu sisältää yli 20 shortcodea, joista jokainen tekee WP_Query- tai wp_remote_get()-kutsun, välimuistita tulokset Transients API:n avulla. Tyypillisissä tilanteissa (yksi tai kaksi shortcodea sivua kohden) suorituskykyvaikutus on mitättömän pieni.

Miten shortcode poistetaan tulosteesta poistamatta sitä artikkelista?

Käytä remove_shortcode()-funktiota functions.php-tiedostossa. Esimerkiksi sisäänrakennetun gallerian poistaminen käytöstä: remove_shortcode( 'gallery' ). Tämän jälkeen [gallery] artikkelitekstissä näkyy tavallisena hakasulkeissa olevana tekstinä ilman suoritusta. Tästä on hyötyä, kun siirryt toiseen ratkaisuun tai selvität ristiriitoja. Osittainen poistaminen käytöstä: voit ohittaa shortcoden rekisteröimällä oman käsittelijän samalla tagilla add_shortcode()-funktiolla. Viimeksi rekisteröidyllä käsittelijällä on etusija.

Kannattaako shortcodeja opetella vuonna 2026

Gutenberg ja lohkoeditori ratkaisivat monet tehtävät, joita varten shortcodeja aiemmin kirjoitettiin: palstat, painikkeet, median lisääminen, kääreet. Mutta shortcodet eivät ole kadonneet minnekään. Lisäosat rekisteröivät niitä edelleen sadoittain, tilauslomakkeista WooCommerce-ostoskoreihin. Ja mikä tärkeintä, yksi räätälöity shortcode voi korvata lisäosan ja tehdä juuri sen, mitä projektisi tarvitsee, kuormittamatta hallintaa jonkun toisen asetuksilla.

Jos toistat artikkeleissa säännöllisesti samaa HTML-lohkoa, linkkiä tai mallipohjaa, käytä 10 minuuttia add_shortcode()-funktioon functions.php-tiedostossa. Sijoitetun ajan tuotto: kymmeniä tunteja vuodessa, joita et käytä kopioi-liitä-toimintoon. Shortcodet ovat taaksepäin yhteensopivia, tänään kirjoitettu koodi toimii tulevissa WordPress-versioissa, koska shortcode-rajapinta ei ole muuttunut ilmestymisensä jälkeen ja on yksi vakaimmista ydinelementeistä.