Category list / Textpattern CMS user documentation

On this page:

Syntax
Attributes
Examples
Genealogy

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):

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).; Default: 1.
exclude="category name(s)" v4.0.4+: List of category names which will be excluded from the list. categories takes precedence over exclude.; 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

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

Example 2: As an unordered list

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

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>

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.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 after (not in) Textpattern 4.7.3.

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.

See something wrong in this document? Outdated info, a broken link, faulty code example, or whatever? Please open an issue and we’ll investigate.

Category list