Go to main content

Menu

Category list

Contents

Syntax

<txp:category_list />

The category_list tag can be used as either a single tag or container tag which is used to produce a list of linked categories.

Attributes

Tag will accept the following attributes (case-sensitive) as well as the global attributes :

active_class="class name" v4.0.4+
HTML class attribute to be applied to the active or current link in a list. Only works in the single tag without the form attribute.
Default: unset.
categories="category name(s)" v4.0.4+
Comma-separated list of categories to include, displayed in the order specified (unless overridden by sort attribute - see Genealogy section for caveat). Use category names not titles here - note that Textpattern automatically converts the names to lowercase and converts spaces to hyphens when they are created.
Default: unset (all categories).
children="integer" v4.7.0+
Can limit the list depth to defined levels below the parent category.
Values: 0 (no children, i.e. only show one level below the parent) or n (show all nested categories and ‘flatten’ the list at the level n). Use the attribute without a value to mimic the nested structure of the categories.
Default: 1.
exclude="category name(s)" v4.0.4+
List of category names which will be excluded from the list.
Default: unset.
form="form name" v4.0.7+
Use specified form to process each included category.
Default: unset.
html_id="id" v4.6.0+
The HTML id attribute applied to the wraptag, if set.
Default: unset.
limit="integer" v4.6.0+
The number of articles to display.
Default: 0 (no limit).
offset="integer" v4.6.0+
The number of articles to skip.
Default: 0.
parent="category name"
Return only specified category and its children categories. Accepts comma-separated list of values.
Default: unset.
section="section name" v4.0.4+
Restrict to articles from specified section(s).
Values: (comma separated list of) section name(s).
Default: unset, retrieves from all sections.
sort="sort value(s)"
How to sort the resulting category list. Specify a value from the ones below, followed by a space and then add either asc or desc to sort in ascending or descending order, respectively.
Values:
id.
name.
parent.
rand() (random).
title.
type.
Default: name asc.
this_section="boolean" v4.0.4+
Link to currently active section (overrides section attribute).
Values: 0 (no) or 1 (yes).
Default: 0.
type="category type"
Values: article, image, link, file.
Default: article.

Common presentational attributes

These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.

break="value"
Where value is an HTML element, specified without brackets (e.g. break="li") or some string to separate list items.
Default: br (but see break cross-reference for exceptions).
breakby="integer" v4.7.0+
Used to group list items when separating by break. Possible values are lists of integers, like 2 (groups of 2 items) or 1,2 (alternate groups of 1 and 2 items).
Default: 1 (actually unset).
class="class name"
HTML class to apply to the wraptag attribute value.
Default: tag name or unset (see class cross-reference).
label="text"
Label prepended to item.
Default: unset (but see label cross-reference for exceptions).
labeltag="element"
HTML element to wrap (markup) label, specified without brackets (e.g. labeltag="h3").
Default: unset.
wraptag="element"
HTML element to wrap (markup) list block, specified without brackets (e.g. wraptag="ul").
Default: unset (but see wraptag cross-reference for exceptions).

Examples

Example 1: Labelled category list

<txp:category_list label="Categories" wraptag="p" break="br" />

Example 2: As an unordered list

<txp:category_list break="li" wraptag="ul" />

Or as a nested unordered list, starting at the “product-type” node:

<txp:category_list break="li" wraptag="ul" parent="product-type" children />

Example 3: Set active class using the container tag

<txp:category_list wraptag="ul" break="">
    <li<txp:if_category name="<txp:category />"> class="active"</txp:if_category>>
        <txp:category title="1" link="1" />
    </li>
</txp:category_list>

Example 4: Nested list of locations

Given a category tree:

  • Location
    • Europe
      • London
      • Paris
      • Rome
    • North America
      • Los Angeles
      • New York
      • Texas

To output the above list of locations (excluding the top level) as a hyperlinkable, nested ul/li list, use a valueless children attribute:

<txp:category_list parent="location" children label="All locations" labeltag="h2" wraptag="ul" break="li" exclude="location">
   <txp:category title link />
</txp:category_list>

This code will add class="active" to the <li> element around the current viewed category in the list, allowing your to style it with CSS as desired.

Other tags used: category, if_category.

Genealogy

Version 4.8.0

sort attribute now respects categories attribute instead of requiring sort="" override.

Version 4.7.2

sort attribute behaviour defaults to name asc to bypass some database server specific ordering. NOTE this introduced an unexpected backwards-compatibility bug with the categories attribute. When using this attribute, you must set sort="" for the list to remain in the order specified in the categories attribute. This has been fixed in Textpattern 4.8.0.

Version 4.7.0

children attribute behaviour extended (accepts integer instead of boolean values).
breakby attribute added.

Version 4.6.0

html_id, limit and offset attributes added.

Version 4.0.7

Can be used as a container tag.
children and form attributes added.

Version 4.0.4

active_class, categories, exclude, section and this_section attributes added.

If you notice any kind of problem with this page's construction or content (outdated information, typos, broken links, or whatever), open an issue to have it sorted. Or have a go at it yourself. :)