Průvodce WordPress shortcody

Co jsou WordPress shortcody

Shortcody jsou speciální značky v hranatých závorkách, které jádro WordPressu automaticky nahrazuje dynamickým obsahem. Například [gallery] zobrazí galerii obrázků, [video] vloží video a [contact-form] zobrazí kontaktní formulář. Shortcody umožňují uživatelům bez technických znalostí vkládat do článků a stránek složitý obsah pouhým napsáním krátkého kódu.

Vestavěné WordPress shortcody pokrývají základní potřeby, ale skutečná síla pramení z možnosti vytvářet vlastní shortcody. Vývojáři pluginů je používají k přidání funkcí jako formuláře, cenové tabulky, slidery a tlačítka, zatímco vývojáři šablon používají shortcody pro opakující se designové prvky. Pochopení systému shortcodů je důležitou dovedností každého uživatele i vývojáře WordPressu.

Vestavěné WordPress shortcody

WordPress přichází s několika vestavěnými shortcody pokrývajícími základní multimediální potřeby. Tyto shortcody fungují ihned bez potřeby dalších pluginů a podporují různé parametry pro přizpůsobení výstupu.

Seznam vestavěných shortcodů

• [caption] – přidá popisek pod obrázek se stylizovaným rámečkem
• [gallery] – zobrazí galerii obrázků z knihovny médií s možnostmi sloupců a velikosti
• [audio] – vloží audio přehrávač s ovládáním přehrávání
• [video] – vloží video přehrávač s podporou formátů MP4, WebM a Ogg
• [playlist] – vytvoří audio nebo video playlist z více souborů
• [embed] – vloží obsah z externích služeb pomocí protokolu oEmbed

Shortcode gallery podrobně

Shortcode gallery je nejčastěji používaným vestavěným shortcodem, protože umožňuje rychle vytvářet galerie obrázků. Podporuje parametry jako ids pro konkrétní obrázky, columns pro počet sloupců, size pro velikost obrázků, orderby pro řazení a link pro určení, kam vede kliknutí na obrázek. Například [gallery ids="1,2,3" columns="3" size="medium"] zobrazí tři konkrétní obrázky ve třech sloupcích střední velikosti.

Tvorba vlastních shortcodů

Tvorba vlastních shortcodů ve vývojovém prostředí WordPressu je překvapivě jednoduchá. Používá se funkce add_shortcode(), která bere dva argumenty: název shortcodu a callback funkci vracející HTML k zobrazení. Tuto funkci přidáte do functions.php své šablony nebo do vlastního pluginu.

Základní struktura

Callback funkce přijímá až tři parametry: $atts (pole atributů, které uživatel předává), $content (obsah mezi otevírací a uzavírací značkou) a $tag (název samotného shortcodu). Funkce musí vrátit řetězec s HTML a nikdy nesmí používat echo, protože to by narušilo pořadí zobrazení na stránce. To je častá chyba začátečníků vedoucí k tomu, že se obsah shortcodu objeví na začátku stránky místo tam, kde byl shortcode vložen.

Příklad jednoduchého shortcodu

Představte si, že chcete shortcode zobrazující zvýrazněný citát se jménem autora. Ve functions.php byste definovali funkci přijímající atributy (author, color) a obsah (text citátu) a vracející stylizovaný HTML blok. Uživatel by v editoru napsal [quote author="Karel Čapek"]Kdo chce psy bít...[/quote] a WordPress by to nahradil naformátovaným citátem se jménem autora pod textem.

Parametry shortcodů

Parametry (atributy) činí shortcody flexibilními, protože umožňují uživatelům přizpůsobit výstup bez změny kódu. Pro definování výchozích hodnot a sloučení s hodnotami, které uživatel předal, použijte funkci shortcode_atts(). Tím zajistíte, že shortcode funguje, i když uživatel neuvede všechny parametry.

Typy parametrů

• Text – titulek, barva, třída, ID (např. title="Titulek")
• Číselný – počet sloupců, limit výsledků, šířka (např. columns="3")
• Booleovský – možnosti ano/ne (např. show_date="true")
• Seznam – ID oddělená čárkou (např. ids="1,5,12,7")
• Výčet – předdefinované možnosti (např. size="small|medium|large")

Vždy validujte a sanitizujte parametry, které uživatel předává, protože shortcody mohou být vektorem pro XSS útoky, pokud je uživatelský vstup vkládán přímo do HTML. Pro vyčištění výstupu používejte funkce esc_attr(), esc_html() a wp_kses(). Číselné parametry převádějte na int pomocí intval() a booleovské parametry porovnávejte s řetězcem true nebo false.

Vnořené shortcody

WordPress podporuje vnořování shortcodů, což znamená, že můžete umístit jeden shortcode dovnitř druhého. To je užitečné pro tvorbu složitých rozvržení, kde máte například shortcode pro řádek a uvnitř něj shortcode pro sloupce. Vnořený obsah se zpracuje voláním funkce do_shortcode() na parametru $content uvnitř vaší callback funkce.

Důležitým omezením je, že nemůžete vnořit stejný shortcode do sebe samého, protože parser WordPressu nedokáže správně rozlišit otevírací a uzavírací značky. Pokud takovou funkcionalitu potřebujete, vytvořte varianty shortcodů s odlišnými názvy jako [row] pro řádek a [column] pro sloupec uvnitř řádku. Toto omezení je záměrné a je nepravděpodobné, že se v budoucích verzích změní.

Příklad vnořování

Klasickým příkladem je shortcode pro rozvržení, kde [row] vytvoří flex nebo grid kontejner a [col width="6"] vytvoří sloupec konkrétní šířky. Uživatel může napsat [row][col width="4"]Levý sloupec[/col][col width="8"]Pravý sloupec[/col][/row] a získat dvousloupcové rozvržení. Shortcode row musí volat do_shortcode($content), aby WordPress zpracoval vnořené shortcody col před vrácením finálního HTML.

Shortcody v blokovém editoru WordPressu

Se zavedením blokového editoru Gutenberg dostaly shortcody vyhrazený blok zvaný Shortcode přijímající jakýkoli shortcode. Trend moderního vývoje WordPressu se však posouvá směrem k nahrazování shortcodů vlastními bloky poskytujícími vizuální náhled v editoru místo holého textu v hranatých závorkách. U nových projektů zvažte tvorbu bloků místo shortcodů, ale u existujících webů zůstávají shortcody plně podporované a funkční.

Kdy použít shortcody a kdy bloky

• Shortcody jsou lepší pro jednoduché vsuvky (citát, tlačítko, ikona)
• Bloky jsou lepší pro složité prvky rozvržení s vizuálním zobrazením
• Shortcody fungují v klasickém i blokovém editoru
• Bloky fungují jen v blokovém editoru (Gutenberg)
• Shortcody se vyvíjejí rychleji, bloky vyžadují znalost JavaScriptu
• Pro kompatibilitu s pluginy jsou shortcody univerzálnější

Praktické tipy a osvědčené postupy

Pojmenovávejte shortcody předponou své šablony nebo pluginu, abyste se vyhnuli konfliktům s jinými pluginy. Například místo [button] použijte [beo_button], protože je méně pravděpodobné, že jiný plugin použije stejný název. Ke každému shortcodu, který vytvoříte, přidejte dokumentaci včetně seznamu parametrů, výchozích hodnot a příkladů použití, protože bez dokumentace si po několika měsících ani vy sami nevzpomenete na všechny možnosti.

U složitějších shortcodů generujících významné množství HTML použijte buffering výstupu nebo šablonové soubory místo zřetězování řetězců. Díky tomu je kód čitelnější a snáze udržovatelný. Cachujte výsledky shortcodů vyžadujících dotazy do databáze. Použijte nástroj pro kontrolu výkonu s pomocí Transients API, protože shortcody se spouštějí při každém načtení stránky a pomalé shortcody mohou web výrazně zpomalit. Vždy testujte shortcody v různých kontextech včetně widgetů, perexů a RSS kanálu, protože chování se může lišit.