Category list
On this page:
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 theactive
or current link in a list. Only works in the single tag without theform
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). 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) orn
(show all nested categories and ‘flatten’ the list at the leveln
). - Default:
1
. exclude="category name(s)"
v4.0.4+- List of category names which will be excluded from the list.
categories
takes precedence overexclude
. - 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 thewraptag
, 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
ordesc
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) or1
(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, like2
(groups of 2 items) or1,2
(alternate groups of 1 and 2 items). - Default:
1
(actually unset). class="class name"
- HTML
class
to apply to thewraptag
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" />
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.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.