⚡ Kuidas lisada oma lühikood WordPressis: näited ja kood

Sa pead iga artikli jaluses väljastama postituse viimase uuendamise kuupäeva. Või sisestama tellimisvormi täpselt teksti keskele, ilma koodiredaktori ja mallide akrobaatikata. WordPressis on selle tööriistaks lühikoodid.

Lühikood on lühike nurksulgudes silt: [myshortcode]. WordPress leiab selle sisust ja asendab selle PHP funktsiooni tulemusega. Sa kasutad standardseid lühikoode nagu [gallery] ja [embed] kogu aeg, ilma et sellele isegi mõtleksid. Aga sinu enda lühikood on hoob: kirjutad loogika ühe korra ja toimetaja sisestab selle kolme klõpsuga ükskõik kuhu.

10 minuti pärast oled loonud oma esimese töötava lühikoodi: tühjast funktsioonist kuni atribuutide ja ümbritsetud sisuga sildini. Kood on päris, töötab igal kaasaegsel WordPressil ja on testitud lavastussaidil.

💡 Kiirülevaade:

• Funktsioon add_shortcode: mida see vastu võtab ja kuidas see seesmiselt töötab
• Lihtne [current_year] lühikood, jooksev aasta tekstina
• Atribuutidega lühikood [cta text="Скачать"], kohandatud nupp
• Ümbritsetud sisuga lühikood [notice]Текст[/notice], kujundatud plokk
• Lisamine plugina või functions.php kaudu: kummagi lähenemise plussid ja miinused
• Levinud vead: echo return asemel, nimede konfliktid, tühi atribuut PHP 8+-s

Mida add_shortcode suudab ja kuidas see töötab

Funktsioon add_shortcode on ainus standardne viis uue lühikoodi registreerimiseks WordPressis. See võtab vastu kaks parameetrit:

• $tag (string), lühikoodi nimi, mille sa kirjutad nurksulgudesse. Ainult tähed, numbrid ja alakriipsud. Tühikud ja erimärgid & / < > [ ] = on keelatud; WordPress keeldub sellist silti vaikimisi registreerimast.
• $callback (callable), selle PHP funktsiooni nimi, mis käivitub, kui lühikood leitakse. See funktsioon genereerib HTML-i, mida külastaja näeb.

Funktsiooni lähtekood, viis rida loogikat ja kaks usaldusväärsuse kontrolli (täielik loetelu aadressil 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
}

Võtmepunkt: $shortcode_tags, globaalne massiiv. WordPress salvestab sinna kõik registreeritud lühikoodid. Sisu renderdamise ajal itereerib tuum üle selle massiivi ja kutsub iga leitud sildi jaoks välja seotud funktsiooni. Sellest tuleneb kaks järeldust:

• Registreeri init konksu külge. Kui kutsud add_shortcode otse pluginifailis välja, võib see käivituda enne, kui WordPress on täielikult initsialiseeritud. Õige viis on mähkida see konksu sisse:

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

• Prefiks on kohustuslik. Globaalne massiiv on jagatud kõigi pluginatega ja teemaga. Kui nimetad lühikoodi [button], kirjutab sinu [button] vaikimisi üle vormiplugina sama lühikoodi. Prefiks nagu myplugin_ või unikaalne lühend lahendab probleemi. Allolevates näidetes kasutan mysite_ prefiksit; päris projektis asenda see enda omaga.

1. Samm: lihtne lühikood ilma parameetriteta

Lühim tee töötava lühikoodini, kolm rida sinu alamteema functions.php failis (või Code Snippets pluginaga, mis on turvalisem ega kao teema uuendamisel).

Lisa see kood ja salvesta:

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

Nüüd kirjuta [mysite_current_year] ükskõik millisesse postitusse või lehele. Esiküljel ilmub lühikoodi asemel jooksev aasta: „2026".

Mis siin toimub. Funktsioon mysite_display_current_year ei võta argumente, kutsub välja PHP funktsiooni date('Y') ja tagastab neljakohalise stringi. WordPress sisestab selle stringi täpselt sinna, kuhu lühikood paigutati. Ei mingit maagiat.

Kus seda praktikas rakendada: aastaarv jaluses (© [mysite_current_year]), projekti vanus tekstis („töötame alates [mysite_current_year]"), juriidiliste lehtede kuupäevade automaatne uuendamine.

2. Samm: atribuutidega lühikood

Parameetriteta lühikood on kasulik, kuid tõeline paindlikkus algab atribuutidest. Klassikaline näide: kohandatava teksti ja lingiga nupp:

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
}

Redaktoris kasuta seda nii:

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

Funktsioon shortcode_atts teeb korraga kolme asja: ühendab kasutaja atribuudid vaikeväärtustega, filtreerib välja ainult tuntud võtmed ja normaliseerib tühja sõne massiiviks (ilma selleta viskaks [mysite_cta] kutsumine ilma atribuutideta PHP 8+-s TypeError-i, sest tagasikutse funktsiooni esimene parameeter saaks massiivi asemel tühja sõne).

*Miks esc_url ja esc_html.* Lühikoodi sisestab redaktor, täna oled see sina, homme aga sisuhaldur, kellel puudub juurdepääs koodile. Väljundi escapimine kaitseb juhusliku XSS-i eest, kui text atribuuti satub nurksulg või silt.

3. Samm: ümbritsetud sisuga lühikood

Mõned lühikoodid mähivad tekstilõigu: [mysite_notice]Важное сообщение[/mysite_notice]. Ümbritsetud sisu jõuab tagasikutse funktsiooni teise parameetrina $content. Tüüpiline stsenaarium: kujundatud hoiatusplokk:

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
}

Pane tähele do_shortcode( $content ). Kui redaktor sisestas sinu lühikoodi sisse teise lühikoodi (näiteks [mysite_current_year]), käivitab see ümbris ka selle. Ilma do_shortcode-ta kuvatakse pesastatud lühikoodid nurksulgudes toortekstina, [mysite_current_year], mitte „2026".

Ploki CSS, minimaalne, alustamiseks:

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
}

Lisa stiilid oma alamteema style.css faili või Välimus → Kohanda → Lisatud CSS kaudu.

4. Samm: lühikood pluginana (OOP-lähenemine)

Kui sul on üle kolme lühikoodi, muutub functions.php prügimäeks. On aeg viia loogika eraldi pluginasse ja ideaalis klassi sisse. Siin on mini-plugin’i skelett ühe lühikoodiga:

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

Paiguta see fail asukohta wp-content/plugins/mysite-shortcodes/mysite-shortcodes.php ja aktiveeri plugin halduspaneelis. Lühikood [mysite_email address="hello@example.com"] väljastab rämpspostirobotite eest kaitstud lingi; funktsioon antispambot kodeerib e-posti aadressi märgid HTML-entiteetideks.

Miks klass, mitte funktsioonide komplekt. Nimeruumid: kolm lühikoodi klassis ei lähe vastuollu kolmandate osapoolte funktsioonidega. Lisaks automaatne laadimine ja loetav kood, kui plugin kasvab tosina lühikoodini.

Lühikoodi testimine enne avaldamist

Pärast koodi lisamist kontrolli kolme stsenaariumi:

• Lühikood ilma atribuutideta. Lihtsalt [mysite_cta], see peaks renderduma vaikeväärtustega (tekst „Loe lähemalt", link #).
• Lühikood atribuutidega. Täielik parameetrite komplekt, kõik väärtused korjatakse üles ja kuvatakse õigesti.
• Viga atribuutides. Vigane e-post [mysite_email] sees, funktsioon tagastab vaikimisi tühja sõne, selle asemel et lehte katki teha.

Oluline: *ära kunagi kasuta echo-t tagasikutse funktsiooni sees.* Lühikood peab tagastama sõne return kaudu. Kui väljastad HTML-i echo-ga, ilmub see mitte sinna, kus lühikood asub, vaid lehe päris ülaossa, sest WordPress käivitab lühikoodide renderdamise enne sisu väljastamist. Sama loogika mis filtrite puhul: funktsioon annab väärtuse tagasi ja mootor ise otsustab, kuhu see paigutada.

Teine nüanss: kui lühikood ei kuvata (näed teksti [mysite_cta], mitte nuppu), kontrolli, et funktsioon on registreeritud init konksul, mitte otse plugin’i kehas. Ilma init-ita ei pruugi globaalne $shortcode_tags massiiv olla veel valmis uusi silte vastu võtma.

Lühikood teemas vs. pluginas: mida valida

Reegel: alusta functions.php-ga testsaidil, ehita kolm lühikoodi, seejärel vii need pluginasse. Kuue kuu pärast tehtav teemauuendus ei mata sinu loogikat ja sa saad lühikoodid minutiga teise projekti üle kanda.

⁉️🤔 KKK

Mis vahe on lühikoodil ja Gutenbergi plokil?

Lühikood on nurksulgudes tekstisilt, mida töödeldakse serveri poolel. Plokk on visuaalse redaktori komponent, React komponent, mille seadistused asuvad külgribal. Lühikoodid ilmusid WordPress 2.5-s (2008), plokid versioonis 5.0 (2018). Tänapäeval on plokid peamine viis dünaamilise sisu lisamiseks, kuid lühikoodid on endiselt asjakohased: neid on lihtsam arendada, need ei nõua JavaScripti tundmist ja töötavad igas redaktoris, sealhulgas klassikalises redaktoris ja leheehitajates.

Lühikood on tekstisilt, mille WordPress asendab lehe renderdamisel PHP funktsiooni tulemusega. Erinevalt Gutenbergi plokist ei ole lühikoodil redaktoris visuaalset liidest: sisuhaldur kirjutab tekstina [myshortcode] ja näeb valmis HTML-i avalikus vaates.

Kas ma saan kasutada lühikoodi teise lühikoodi sees?

Jah. Kui välimise lühikoodi callback-funktsioon mähib sisemise sisu do_shortcode() funktsiooni, töötavad sisemised lühikoodid korrektselt: [notice][current_year][/notice] väljastab kujundatud ploki jooksva aastaga. Ilma do_shortcode()-ta jääb sisemine lühikood nurksulgudesse tekstina alles.

Sisestatud lühikoode töödeldakse rekursiivselt: WordPress käib stringi mitu korda läbi, kuni töötlemata silte enam ei ole. Kuid selleks peab välimine lühikood selgesõnaliselt välja kutsuma do_shortcode($content). Vastasel juhul jääb string [current_year] tekstina alles, selle asemel et muutuda „2026"-ks.

Miks minu lühikood ei tööta ja kuvatakse nurksulgudes tekstina?

Kolm levinud põhjust. Esiteks: add_shortcode kutsutakse välja enne init konksu, liiguta registreerimine add_action('init', ...) sisse. Teiseks: sildi nimes on trükiviga, redaktoris on [my_shortcode], kuid registreeritud on myshortcode. Kolmandaks: callback-funktsioon kasutab return asemel echo-t, mistõttu väljund läheb lehe ülaossa ja lühikoodi asukoht on tühi.

Kõige sagedasem süüdlane on echo asemel return callback-funktsioonis. WordPress kutsub lühikoodide töötlejaid välja enne põhisisu väljastamist, seega jõuab echo tulemus väljundpuhvrisse enne lehe päist. Ava lehe lähtekood (Ctrl+U): kui näed lühikoodi HTML-i kõige üleval, enne <html> silti, ongi probleem just selles.

Kas ma pean lühikoodi väljundit eskeepima?

Absoluutselt. Lühikood võtab atribuute vastu redaktorist, mis tähendab potentsiaalselt igalt autorile või toimetajale ligipääsu omavalt kasutajalt. esc_html() teksti jaoks, esc_url() linkide jaoks, esc_attr() HTML atribuutide jaoks. Erandiks on juhud, kui tagastad tahtlikult HTML märgendi (nagu <div class="notice">). Kuid isegi siis eskeepi atribuudid märgendi sees.

Jah, eskeipimine on kohustuslik kõigele, mis tuleb lühikoodi atribuutidest või kasutaja sisendist. Isegi kui täna lisad lühikoode ainult sina, saab homme sisuhaldur toimetaja õigused. esc_html() teksti jaoks, esc_url() linkide jaoks, esc_attr() HTML atribuutide jaoks kaitsevad juhusliku või tahtliku XSS-i eest.

Mitu lühikoodi saan ma ühel saidil registreerida?

Tehnilist piirangut ei ole: $shortcode_tags on tavaline PHP massiiv, serveri mälulimiidini jõuad palju hiljem kui terve mõistuseni. Praktikas tasub pärast 15-20 kohandatud lühikoodi küsida: kas on aeg osa neist Gutenbergi plokkideks ümber tõsta? Jäta alles unikaalse loogikaga lühikoodid (e-posti peitmine, rollipõhine tingimuslik väljund). Lühikoodide puhul, mis lihtsalt kujundavad teksti ([highlight]), on parem kasutada ploki stiili või CSS klassi.

Tehniliselt nii palju kui soovid: $shortcode_tags massiivil ei ole kunstlikku piirangut. Praktiliselt viitab üle 20-25 lühikoodi ühel saidil sellele, et osa loogikast tuleks plokkidesse viia. Iga lühikood lisab sisu parsimise üldkulu: enne väljundit käib WordPress läbi kogu registreeritud siltide massiivi ja otsib postituse tekstist vasteid.

Kas ma peaksin ise lühikoode kirjutama või piisab valmispluginatest?

Valmisplugin katab enamiku tüüpilisi ülesandeid: vormid, Contact Form 7, tabelid, TablePress, ruudustikud, ükskõik milline leheehitaja. Kohandatud lühikoodi on vaja siis, kui loogika on sinu saidile spetsiifiline ja ükski valmislahendus ei sobi: kohandatud välja väljastamine täpselt sellel kohal lehel, järgmise veebiseminari kuupäev andmebaasist, isikustatud tervitus kasutaja rolli põhjal.

Lühidalt: standardse funktsionaalsuse jaoks kasuta pluginat ja ära programmeeri. Unikaalse loogika jaoks add_shortcode + functions.php või miniplugin. Kood ükskõik millises ülaltoodud näites on alla kümne rea. Kui oled omandanud need kolm mustrit (lihtne, atribuutidega, sisestatud sisuga), katad valdava enamuse ülesannetest, mille jaoks kohandatud lühikoode üldse kirjutatakse.