V předchozím článku jsme si ukázali, jak snadno pracovat s kategoriemi ve WordPressu. Věnovali jsme se tomu, jak můžeme třídit příspěvky do různých kategorií, které pak můžeme upravovat nebo mazat.

Pokud jsme probrali základy, je nyní čas podívat se na něco, co bude vývojáře zajímat více: na rozhraní Categories API a na to, jak získávat a zobrazovat data o kategoriích.

Stejně jako rozhraní Links Manager API je i rozhraní Categories API velké téma, ještě větší co do počtu dostupných funkcí. V tomto článku se budeme zabývat jednou funkcí, která je užitečná, když chceme vypsat naše kategorie.

Vypsání kategorií

V rozhraní API Správce odkazů najdeme důležitou funkci, která nám umožňuje vypsat naše odkazy. Není proto překvapením, že totéž najdeme i v rozhraní API pro kategorie: wp_list_categories(), to je funkce, se kterou zde budeme pracovat.

Zásadně musíte tuto funkci zavolat na místě, kde chcete vidět seznam svých kategorií.

wp_list_categories();

Jak si můžete představit, tento výsledek je zcela přizpůsobitelný. Abychom jej zformovali podle našich potřeb, můžeme této funkci předat argument: pole obsahující hodnoty pro možnosti, které chceme nastavit. Podívejme se na některé z dostupných možností.

Výběr zobrazovaných kategorií

Než se podíváme na to, jak výsledek přizpůsobit, začneme s některými možnostmi, které nám umožňují vybrat, co se má zobrazit.

Včetně a bez kategorií

Nejprve najdeme možnost include, která přijímá seznam ID kategorií, které se mají zobrazit. Při použití této volby wp_list_categories() se zobrazí pouze kategorie s předanými ID. Můžete uvést jedno nebo více ID. Pokud chcete uvést dvě nebo více ID, musíte tato čísla oddělit čárkou.

$args = array('include' => '15,16,9');wp_list_categories($args);

Pokud naopak nechcete vybírat, co se má zobrazit, ale spíše co se zobrazovat nemá, je pro vás určena možnost exclude. Lze ji použít přesně jako include .

$args = array('exclude' => '15,16,9');

Poznamenejte, že pokud chcete použít volbu exclude, musí být include prázdná (její výchozí hodnota). V opačném případě zvítězí volba include a zobrazí se pouze kategorie, které jí byly předány.

Další volbou pro vyloučení kategorií je exclude_tree. Opět přijímá seznam ID kategorií oddělených čárkou, které mají být vyloučeny. Rozdíl je v tom, že vyloučí vybrané kategorie a všechny jejich potomky. Všimněte si, že aby tato volba fungovala, musíte nastavit volbu hierarchical na 0 (níže uvidíme, co tato volba dělá).

// 14 is the ID of "My life", parent of "My goldfish" and "My garden" which will also be hidden$args = array('exclude_tree' => '14','hierarchical' => 0);

Uspořádání výstupu

Ve výchozím nastavení jsou kategorie uvedeny v abecedním pořadí. Toto chování můžete změnit díky volbě orderby, která přijímá řetězec. Můžete si vybrat z následujících možností: ID pro řazení kategorií podle jejich ID (ne, opravdu?), name pro řazení podle abecedy (výchozí hodnota), slug pro řazení podle abecedy jejich slug a count pro řazení podle počtu příspěvků, které obsahují.

Zvolené pořadí lze změnit nastavením DESC (sestupně) jako hodnoty pro volbu order (ve výchozím nastavení je tato volba nastavena na ASC (vzestupně)).

V níže uvedeném příkladu uvádíme kategorie podle počtu příspěvků, které obsahují: protože je pořadí obrácené, jako první se zobrazí kategorie obsahující největší počet příspěvků.

$args = array('orderby' => 'count','order' => 'DESC');

Omezit počet zobrazených kategorií

Pokud jsme seřadili kategorie, můžeme chtít omezit počet zobrazených položek. Toho lze dosáhnout pomocí volby number. Ve výchozím nastavení je tato volba nastavena na null a není zde žádné omezení, takže se zobrazí všechny kategorie. Zadáním čísla můžete definovat maximální počet zobrazovaných kategorií. Můžeme například vypsat pět nejpoužívanějších kategorií.

$args = array('orderby' => 'count','order' => 'DESC','number' => 5);

Tento příklad vypisuje kategorie s největším počtem příspěvků. Dalším řešením je skrytí nepoužívaných kategorií. K tomu můžeme použít hide_empty, boolean nastavený ve výchozím nastavení na 1: prázdné kategorie se nezobrazí. Můžete se rozhodnout pro jejich zobrazení nastavením této hodnoty na 0.

// Show me all the categories, even the empty ones$args = array('hide_empty' => 0);

Zadání zobrazovaných podrobností

Podrobnosti jsou důležité a vždy se najdou takové, které chceme zahrnout.

Počty!

Můžete například chtít zobrazit počet příspěvků obsažených v každé kategorii. Pro jeho zobrazení můžete použít volbu show_count a nastavit ji na 1. Ve výchozím nastavení je tento boolean nastaven na 0 a tento počet se nezobrazuje.

$args = array('show_count' => 1);

Všimněte si, že příspěvek v podřízené kategorii se také přičte k celkovému počtu příspěvků svého rodiče. Například snímek obrazovky níže je pořízen se třemi příspěvky v kategorii „Můj život“: zatímco v této kategorii je pouze jeden příspěvek, další dva jsou v podřízených kategoriích.

Toto chování můžete upravit díky volbě pad_counts. Pokud ji nastavíte na 0, budou počty rodičů zobrazovat pouze počet příspěvků v těchto rodičovských kategoriích a nebudou zahrnovat příspěvky v jejich podřízených kategoriích.

$args = array('show_count' => 1,'pad_counts' => 0);

Popisy kategorií

Jak jsme viděli v předchozím článku, můžeme nastavit popis našich kategorií. Tento popis lze zobrazit pomocí volby use_desc_for_title. Jedná se o boolean nastavený ve výchozím nastavení na 1: popisy se zobrazují v atributu title odkazů v seznamu. Pokud nechcete tento popis zobrazovat, můžete jej nastavit na 0.

$args = array('use_desc_for_title' => 1);

Feeds

Stejně jako WordPress vytváří feed pro vaše příspěvky, vytváří jej také pro každou kategorii. Návštěvníci si mohou vybrat, zda chtějí sledovat pouze aktualizace kategorií, které je zajímají, pokud se jim nelíbí veškerý váš obsah.

Odkazy na tyto kanály se mohou zobrazovat v seznamu našich kategorií díky možnosti feed. Ve výchozím nastavení je tato volba nastavena na prázdný řetězec a odkazy se nezobrazují. Následující kód ukazuje, jak tuto volbu zapnout.

$args = array('feed' => 'RSS');

Ve výchozím nastavení je odkazovaným kanálem kanál RSS2. WordPress však může generovat více typů kanálů. Pokud dáváte přednost například Atomu, můžete WordPress přinutit, aby zobrazoval tento typ feedu místo RSS2.

Pro výběr typu feedu, který chcete zobrazit, můžete zadat některou z následujících možností : atom, rss, rss2 a rdf.

$args = array('feed' => 'Atom','feed_type' => 'atom');

Pokud dáváte přednost použití obrázku jako odkazu na RSS kanály, můžete v možnosti feed_image uvést adresu URL obrázku, který chcete zobrazit. Text v možnosti feed se pak stane alternativním textem obrázku.

$args = array('feed' => 'RSS','feed_image' => 'http://website.org/my-awesome-rss-image.png');

Je tato kategorie ta aktuální?

Použijete-li wp_list_categories() na archivní stránce (v šabloně archive.php), můžete si všimnout, že aktuální kategorie (ta, kterou zobrazuje archivní stránka) je zvýrazněna: značka li uzavírající odkaz na tuto kategorii má o jednu třídu více než ostatní, jmenuje se current-cat. Pro aktivaci tohoto chování nemusíte nic dělat a nemůžete ho ani deaktivovat (ale můžete ho ve svém CSS nepoužívat!).

Možná je to však chování, které chcete vidět na více stránkách, například na těch, které zobrazují příspěvek. Dobrá zpráva je, že můžete, a to díky možnosti current_category. Tento boolean je ve výchozím nastavení nastaven na 0. Nastavením na 1 bude aktuální kategorie zvýrazněna dříve citovanou třídou.

$args = array('current_category' => 1);

Předpokládejme například, že zobrazujeme seznam našich kategorií na šabloně single.php. Pak se pomocí předchozího pole zvýrazní kategorie aktuálního příspěvku díky třídě current-cat. Jediné, co nyní musíme udělat pro její zobrazení, je přidat příslušné CSS.

Zobrazení hierarchie

Pokud máme mnoho kategorií, je dobré je uspořádat do logické hierarchie, kde najdeme nadřazené kategorie a pod nimi jejich potomky. Existuje řada možností, jak se zobrazením hierarchií zacházet.

Nejprve se podíváme na hierarchical. Jedná se o boolean nastavený ve výchozím nastavení na 1, přičemž wp_list_categories() zobrazuje hierarchii mezi kategoriemi (s rodiči a dětmi), přesně jako na snímcích obrazovky od začátku tohoto článku. Pokud nechcete hierarchii zobrazovat, můžete ji nastavit na 0: kategorie pak budou uvedeny v jednom sloupci bez odsazení podřízených kategorií.

Všimněte si vedlejšího efektu volby hierarchical: pokud se rozhodnete zobrazit hierarchii, pak budou rodičovské kategorie zobrazeny vždy, i když jsou prázdné a volba hide_empty je nastavena na 1.

// Don't show me the hierarchy$args = array('hierarchical' => 0);

Hierarchii můžete použít i k dalším věcem, například k zobrazení dětí dané kategorie pomocí child_of . Mohli bychom ji popsat jako opak exclude_tree: zadáme jí ID kategorie a wp_list_categories() zobrazí pouze její děti. Název nadřazené kategorie se však nezobrazí.

// Show me all the children of this category$args = array('child_of' => 14);

Na rozdíl od exclude_tree můžeme child_of předat pouze jedno ID.

Volba depth umožňuje řídit počet úrovní, které lze v seznamu zobrazit. Může být užitečná, pokud máte rádi kategorie a máte složitý strom s mnoha generacemi. Ve výchozím nastavení je nastavena na 0 a zobrazuje všechny generace. Níže uvedený příklad zobrazuje pouze dvě úrovně kategorií: rodiče a jejich potomky první úrovně. Pokud mají tyto děti vlastní podřízené kategorie, nebudou zobrazeny.

$args = array('depth' => 2);

Všimněte si, že depth je propojena s hierarchical. Pokud totiž nastavíte hierarchical na 0, bude zadání hodnoty depth zbytečné: zobrazí se všechny kategorie bez ohledu na jejich úroveň ve stromu. Naopak v jednom případě můžete hodnotu hierarchical přepsat hodnotou depth: nastavíte depth na -1. Výsledkem této hodnoty je zobrazení všech kategorií bez jakéhokoli vztahu. Všechny kategorie se zobrazí v jednom sloupci, i když je hodnota hierarchical nastavena na 1.

Kontrola výstupu

Ve výchozím nastavení wp_list_categories() zobrazuje seznam našich kategorií. Pokud to nechcete a dáváte přednost uložení výsledku do proměnné pro pozdější zobrazení, můžete nastavit echo na 0.

$args = array('echo' => 0);$cats = wp_list_categories($args);

To může být užitečné, pokud chcete seznam před zobrazením upravit.

Dále se podíváme na show_option_none. Ve výchozím nastavení, pokud wp_list_categories() nenajde žádnou kategorii (to se může stát, pokud jsou například ostatní možnosti příliš omezující), zobrazí text „Žádné kategorie“. Pomocí této volby jej můžete změnit na požadovaný text.

$args = array('show_option_none' => 'Nothing found :(');

Další title_li. Při našich testech jste si mohli všimnout, že seznam kategorií je zapouzdřen do položky jiného seznamu. To může být užitečné, pokud například v nabídce použijete wp_list_categories(). Kromě toho WordPress zobrazuje nadpis tohoto seznamu, který je ve výchozím nastavení „Kategorie“.

Tento výchozí nadpis můžete upravit nebo dokonce zakázat hraním si s title_li. Ten přijímá řetězec, což je název, který se má zobrazit. Pokud této volbě dáte prázdný řetězec, nebude seznam kategorií vůbec zapouzdřen do jiného seznamu.

$args = array('title_li' => 'My awesome categories');

Dejte si pozor: pokud zakážete zobrazování seznamu prázdným řetězcem, musíte svůj seznam uzavřít do značek ul!

Nemáte rádi seznamy? Bude se vám líbit volba style: ve výchozím nastavení je nastavena na list a wp_list_categories() zobrazuje kategorie jako položky seznamu. Pokud nastavíte style na none, budou vaše kategorie odděleny značkami br.

$args = array('style' => 'none');

Nakonec můžete WordPress požádat, aby zobrazil odkaz na všechny vaše kategorie díky možnosti show_option_all. Této možnosti zadáte řetězec a WordPress zobrazí nový odkaz, který bude směřovat na všechny vaše kategorie.

$args = array('show_option_all' => 'All categories');

Závěr

To je pro wp_list_categories() vše. Jak vidíte, počet možností, které má tato funkce k dispozici, je poměrně velký.

Rozhraní Categories API se samozřejmě neomezuje pouze na tuto funkci. Je však důležitá: pokud nemáte žádnou specifickou potřebu a chcete jen základní seznam kategorií, nehledejte jinou funkci, tato je vaší nejjednodušší možností!“

Všimněte si, že jsme v tomto článku nemluvili o wp_dropdown_categories(). Tato funkce zobrazí naše kategorie do rozbalovacího prvku HTML. Stejně jako wp_list_categories() lze její výstup plně přizpůsobit díky řadě možností. Tyto možnosti jsou podobné těm, které jsou k dispozici u wp_list_categories() , takže je zde nebudeme popisovat. Jediné úskalí spočívá v tom, že některé možnosti mají jiné výchozí hodnoty. Chcete-li se o wp_dropdown_categories() dozvědět více, můžete přejít do kodexu WordPressu.

Ještě existují další případy: co když chceme naše kategorie zobrazit speciálním způsobem? V takovém případě není wp_list_categories() dostatečně flexibilní, protože musíme vytvořit vlastní strom DOM. Proto se v příštím článku podíváme na některé další užitečné funkce v rozhraní Categories API.