In een vorig artikel hebben we gezien hoe we eenvoudig met categorieën in WordPress kunnen werken. We hebben behandeld hoe we onze berichten kunnen sorteren in verschillende categorieën, die vervolgens kunnen worden bewerkt of verwijderd.

Na de basis te hebben behandeld, is het nu tijd om te kijken naar iets dat meer interessant zal zijn voor ontwikkelaars: de Categorieën API, en hoe categoriegegevens kunnen worden opgehaald en weergegeven.

Net als de Links Manager API, is de Categorieën API een groot onderwerp, zelfs groter in termen van het aantal beschikbare functies. In dit artikel behandelen we één functie die nuttig is wanneer we onze categorieën willen opsommen.

Listing Categories

In de Links Manager API vinden we een belangrijke functie die ons in staat stelt onze links op te sommen. Het is dan ook geen verrassing dat we hetzelfde vinden in de Categorieën API: wp_list_categories(), dit is de functie waar we hier mee zullen werken.

In principe moet je deze functie aanroepen op de plaats waar je je categorieën vermeld wilt zien.

wp_list_categories();

Zoals je je kunt voorstellen, is dit resultaat geheel aanpasbaar. Om het aan onze behoeften aan te passen kunnen we een argument aan deze functie doorgeven: een array met waarden voor de opties die we willen instellen. Laten we eens kijken naar een aantal van de beschikbare opties.

Kiezen van de weer te geven categorieën

Voordat we gaan kijken hoe we de uitvoer kunnen aanpassen, beginnen we met een aantal opties waarmee we kunnen kiezen wat we willen weergeven.

Insluiten en uitsluiten van categorieën

Eerst vinden we de optie include die een lijst van categorie-ID’s accepteert om weer te geven. Als u deze optie gebruikt, zal wp_list_categories() alleen de categorieën weergeven met de ID’s die u hebt doorgegeven. U kunt één of meer ID’s opgeven. Als u twee of meer ID’s wilt aangeven, moet u deze nummers scheiden met een komma.

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

Als u daarentegen niet wilt kiezen wat moet worden weergegeven, maar wat niet moet worden weergegeven, dan is de optie exclude iets voor u. Deze kan precies zo worden gebruikt als include .

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

Merk op dat als u de exclude optie wilt gebruiken, include leeg moet zijn (de standaard waarde). Anders wint de optie include en worden alleen de categorieën weergegeven die eraan zijn doorgegeven.

Een andere optie om categorieën uit te sluiten is exclude_tree. Ook deze optie accepteert een door komma’s gescheiden lijst van categorie-ID’s om uit te sluiten. Het verschil is dat het de geselecteerde categorieën en al hun kinderen zal uitsluiten. Merk op dat, om deze optie te zien werken, u de optie hierarchical op 0 moet zetten (we zullen hieronder zien wat deze optie doet).

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

Ordening van de uitvoer

Standaard worden de categorieën in alfabetische volgorde gezet. U kunt dit gedrag wijzigen dankzij de optie orderby, die een string accepteert. U kunt kiezen uit de volgende opties: ID om de categorieën te sorteren op hun ID (nee, echt?), name om ze alfabetisch te sorteren (de standaardwaarde), slug om ze te sorteren op de alfabetische volgorde van hun slugs, en count om ze te sorteren op het aantal posts dat ze bevatten.

De gekozen volgorde kan worden omgekeerd door DESC (aflopend) in te stellen als waarde voor de optie order (standaard staat deze optie ingesteld op ASC (oplopend)).

In het onderstaande voorbeeld worden de categorieën gerangschikt naar het aantal berichten dat zij bevatten: omdat de volgorde is omgekeerd, zal de categorie met het grootste aantal berichten als eerste worden weergegeven.

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

Limit the Number of Displayed Categories

Als we onze categorieën hebben gerangschikt, willen we misschien het aantal weergegeven items beperken. Dit kan worden bereikt met de number optie. Standaard is deze optie ingesteld op null en er is geen limiet, zodat alle categorieën worden getoond. Door een getal op te geven, kunt u het maximum aantal categorieën bepalen dat moet worden getoond. Bijvoorbeeld, we kunnen de vijf meest gebruikte categorieën tonen.

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

Dit voorbeeld toont de categorieën met het grootste aantal berichten. Een andere oplossing is om de ongebruikte categorieën te verbergen. Om dat te doen kunnen we hide_empty gebruiken, een boolean die standaard is ingesteld op 1: lege categorieën worden niet getoond. U kunt ervoor kiezen om ze te tonen door dit op 0 te zetten.

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

Specificeren van Details die getoond moeten worden

Details zijn belangrijk, en er zijn er altijd een paar die we willen opnemen.

Tellers!

Het kan bijvoorbeeld zijn dat u het aantal berichten wilt tonen dat in elke categorie zit. Om dit weer te geven kunt u de optie show_count gebruiken en deze op 1 zetten. Standaard is deze boolean ingesteld op 0 en wordt deze telling niet getoond.

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

Merk op dat een post in een child categorie ook wordt opgeteld bij het totaal aantal posts van zijn parent. Bijvoorbeeld, de schermafbeelding hieronder is genomen met drie berichten in de categorie “Mijn leven”: terwijl er slechts één bericht in deze categorie is, zijn de twee anderen in de kindcategorieën.

Je kunt dit gedrag wijzigen dankzij de optie pad_counts. Als u deze instelt op 0, zullen de tellingen van de ouders alleen het aantal berichten in de categorieën van deze ouders weergeven en niet de berichten in hun kindcategorieën.

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

Beschrijvingen van de categorieën

Zoals we in ons vorige artikel hebben gezien, kunnen we een beschrijving voor onze categorieën instellen. Deze beschrijving kan worden weergegeven met de optie use_desc_for_title. Het is een boolean die standaard is ingesteld op 1: beschrijvingen worden getoond in het title attribuut van de links in de lijst. Als u deze beschrijving niet wilt zien, kunt u dit instellen op 0.

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

Feeds

Net zoals WordPress een feed genereert voor uw berichten, maakt het er ook een aan voor elke categorie. Bezoekers kunnen ervoor kiezen om alleen de updates van categorieën waarin ze geïnteresseerd zijn te volgen, als ze niet van al uw inhoud houden.

De links naar deze feeds kunnen worden getoond in de lijst van onze categorieën, dankzij de optie feed. Standaard is deze optie ingesteld op een lege string en worden de links niet getoond. De onderstaande code laat zien hoe u deze optie inschakelt.

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

De standaard feed waarnaar wordt gelinkt is de RSS2 feed. Maar WordPress kan meer feed types genereren. Als je bijvoorbeeld de voorkeur geeft aan Atom, kun je WordPress dwingen dit type feed weer te geven in plaats van de RSS2.

Om het type feed te selecteren dat je weergegeven wilt zien, kun je een van de volgende opties opgeven : atom, rss, rss2 en rdf.

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

Ten slotte, als u liever een afbeelding gebruikt om naar uw RSS feeds te linken, kunt u de URL van de afbeelding die u wilt zien in de feed_image optie aangeven. De tekst in de feed optie wordt dan de alternatieve tekst voor de afbeelding.

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

Is This Category the Current One?

Als U wp_list_categories() gebruikt op een archief pagina (in het archive.php template), dan kunt U zien dat de huidige categorie (degene die door de archief pagina wordt getoond) is gemarkeerd: de li tag die de link naar deze categorie omsluit heeft een klasse meer dan de andere, genaamd current-cat. Je hoeft niets te doen om dit gedrag te activeren, en je kunt het ook niet deactiveren (maar je bent vrij om het niet te gebruiken in je CSS!).

Hoe dan ook, misschien is het een gedrag dat je op meer pagina’s wilt zien, zoals die welke een post tonen. Het goede nieuws is dat dit kan, dankzij de optie current_category. Deze boolean is standaard ingesteld op 0. Door het in te stellen op 1 zal de huidige categorie worden gemarkeerd met de eerder geciteerde class.

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

Voorbeeld, laten we aannemen dat we de lijst van onze categorieën weergeven op de single.php template. Dan, met de vorige array, is de categorie van het huidige bericht gemarkeerd dankzij de klasse current-cat. Alles wat we nu hoeven te doen om het weer te geven is het toevoegen van de juiste CSS.

Tonen van de Hiërarchie

Als je veel categorieën hebt, is het een goed idee om ze te organiseren in logische hiërarchieën, waar we bovenliggende categorieën vinden en hun kinderen eronder. Er zijn een aantal opties om met de weergave van hiërarchieën om te gaan.

We zullen eerst naar hierarchical kijken. Het is een boolean die standaard is ingesteld op 1, waarbij wp_list_categories() de hiërarchie tussen de categorieën toont (met ouders en kinderen), precies zoals in de screenshots aan het begin van dit artikel. Als je de hiërarchie niet wilt laten zien, kun je hem op 0 zetten: je categorieën worden dan in één kolom getoond, zonder inspringen van de kind-categorieën.

Neem het neveneffect van hierarchical in acht: als je ervoor kiest om de hiërarchie te tonen, dan zullen de categorieën van de ouders altijd worden getoond, zelfs als ze leeg zijn en de hide_empty optie is ingesteld op 1.

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

Je kunt hiërarchie ook gebruiken om andere dingen te doen, zoals het tonen van de kinderen van een bepaalde categorie met child_of . We zouden het kunnen beschrijven als het tegenovergestelde van exclude_tree: we geven het de ID van een categorie en wp_list_categories() zal alleen de kinderen tonen. De naam van de bovenliggende categorie wordt echter niet getoond.

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

In tegenstelling tot exclude_tree kunnen we slechts een enkel ID aan child_of doorgeven.

Met de optie depth kunt u het aantal niveaus bepalen dat in de lijst kan worden getoond. Dit kan nuttig zijn als u van categorieën houdt en een complexe boom hebt met veel generaties. Standaard staat deze ingesteld op 0 en toont alle generaties. Het voorbeeld hieronder toont slechts twee niveaus van categorieën: de ouders en hun kinderen van het eerste niveau. Als deze kinderen hun eigen kind-categorieën hebben, worden ze niet getoond.

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

Noteer dat depth is gekoppeld aan hierarchical. In feite, als u hierarchical instelt op 0, heeft het geen zin om een waarde toe te kennen aan depth: alle categorieën zullen worden getoond, ongeacht hun niveau in de boom. Integendeel, u kunt de waarde van hierarchical ook overschrijven met depth in één geval: u stelt depth in op -1. Het effect van deze waarde is dat alle categorieën zonder enige relatie worden weergegeven. Alle categorieën worden getoond in één kolom, zelfs als hierarchical is ingesteld op 1.

Bepalen van de uitvoer

Normaal toont wp_list_categories() de lijst van onze categorieën. Als u dat niet wilt en het resultaat liever in een variabele opslaat om het later weer te geven, kunt u echo op 0 zetten.

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

Dit kan handig zijn als u de lijst wilt wijzigen voordat u hem weergeeft.

Naar show_option_none gaan we nu kijken. Standaard, als wp_list_categories() geen categorie vindt (dit kan gebeuren als de andere opties te beperkend zijn bijvoorbeeld), toont het de tekst “Geen categorieën”. U kunt dit veranderen in de tekst die u wilt met deze optie.

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

Next title_li. In onze tests is het u misschien opgevallen dat de lijst met categorieën is ingekapseld in een item van een andere lijst. Dit kan handig zijn als u bijvoorbeeld wp_list_categories() in een menu gebruikt. Bovendien, WordPress toont een titel voor deze lijst, die standaard “Categorieën” is.

U kunt deze standaard titel wijzigen of zelfs uitschakelen door te spelen met title_li. Het accepteert een string, die de weer te geven titel is. Als u deze optie een lege tekenreeks geeft, zal de lijst van categorieën helemaal niet worden ingekapseld in een andere lijst.

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

Wees voorzichtig: als u de weergave van de lijst met een lege tekenreeks uitschakelt, moet u uw lijst omsluiten in ul tags!

Houdt u niet van lijsten? U zult dol zijn op de optie style: standaard staat deze ingesteld op list en wp_list_categories() geeft categorieën weer als lijst-items. Als u style instelt op none, worden uw categorieën gescheiden door br tags.

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

Ten slotte kunt u WordPress vragen om een link naar al uw categorieën weer te geven dankzij de optie show_option_all. U geeft een string aan deze optie, en WordPress zal een nieuwe link weergeven, die naar al uw categorieën wijst.

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

Conclusie

Dat is het voor wp_list_categories(). Het aantal opties dat beschikbaar is voor deze functie is vrij groot, zoals u kunt zien.

Natuurlijk is de Categorieën API niet beperkt tot deze functie. Het is echter een belangrijke: als je geen specifieke behoefte hebt en gewoon een basis lijst van categorieën wilt, zoek dan niet naar een andere functie, deze is uw eenvoudigste optie!

Merk op dat we in dit artikel niet hebben gesproken over wp_dropdown_categories(). Deze functie toont onze categorieën in een dropdown HTML element. Net als wp_list_categories(), kan de uitvoer volledig worden aangepast dankzij een reeks opties. Deze opties zijn vergelijkbaar met de opties die beschikbaar zijn met wp_list_categories(), dus we zullen ze hier niet beschrijven. De enige moeilijkheid is dat sommige opties andere standaardwaarden hebben. Om meer te leren over wp_dropdown_categories(), kunt u naar de WordPress Codex gaan.

Maar er zijn nog andere gevallen: wat als we onze categorieën op een speciale manier willen weergeven? In dit geval is wp_list_categories() niet flexibel genoeg, omdat we onze eigen DOM boom moeten bouwen. Daarom zullen we in het volgende artikel kijken naar enkele andere nuttige functies in de Categorieën API.