Go to main content

Section list

On this page:

Syntax

<txp:section_list />

The section_list tag is a single or container tag which is used to produce a list of linked sections. When used as a container tag, it is used as an opening and closing pair, like this:

<txp:section_list>
    …contained statements…
</txp:section_list>

Attributes

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

active_class="class name" (only works in the single tag without the form attribute)
HTML class to apply to the ‘active’ or current link in a list.
Default: unset
default_title="text"
Text used as a title for the ‘default’ section when include_default is set to 1.
Default: site name.
exclude="section name(s)"
Comma-separated list of section names to exclude from the list. sections takes precedence over exclude. Using this attribute without any value omits non-searchable sections from its output.
Default: unset (none).
form="form name" v4.0.7+
Use specified form template to process each included section.
Default: unset.
html_id="id" v4.6.0+
The HTML id attribute applied to the wraptag, if set.
include_default="boolean"
Whether to include ‘default’ section in section list.
Values: 0 (no) or 1 (yes).
Default: 0.
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.
sections="section name(s)"
Comma-separated list of section names to include in the list, displayed in specified order (unless overridden by the sort attribute).
Default: unset (all sections).
sort="sort value(s)"
How to sort the resulting section 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:
css (order by the Stylesheet in use by the Sections).
in_rss (order by whether the Sections are syndicatable or not).
name.
on_frontpage (order by whether the Section allows articles on the front page or not).
page (order by the Page in use by the Sections).
rand() (random).
searchable (order by whether the Sections are searchable or not).
title.
Each field in the textpattern database table can be used as a sort key.
When viewing a search results list, score (how well the search terms match the article) is available as an additional value.
Default: name asc.

Common presentational attributes

These attributes, which affect presentation, are shared by many 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 (see break cross-reference).
breakby="integer(s)"
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 (unset) (see breakby cross-reference).

Common global attributes

These attributes are shared by all tags - and plugins, provided they do not override the functionality.

class="class name"
HTML class to apply to the wrapper.
Values: Any valid string.
Default: tag name or unset.
default="value"
The value to display if the tag’s output is blank.
Values: Any.
Default: unset.
escape="list, of, transforms"
The transforms to apply to the output. See tag escaping for details.
Values: html, js, json, url, float, integer, number, ordinal, spell, lower, upper, title, [r|l]trim, quote, tags, textile, _any tag_
Default: html.
html_id="value"
HTML id to apply to the wrapper.
Values: Any valid string.
Default: unset.
label="value"
The label to display before the output.
Values: Any valid string.
Default: unset.
labeltag="tag"
The tag (without angle brackets) to wrap the label.
Values: Any valid HTML tag, e.g. h3 or div.
Default: unset.
not="boolean"
Switch parts.
Values: 0 (no) or 1 (yes).
Default: unset (0).
replace="string"
Replace the content stripped via the trim attribute.
Values: Any valid string.
Default: unset.
trim="string or regex"
Remove the matching patterns from the output.
Values: Any. Use /value/ to trigger regular expression matching, otherwise the value will be treated verbatim as a set of characters to trim.
Default: unset.
wrapform="form name"
The form to be used as wraptag. Handy if the wraptag pattern is too long, or is reused.
Values: Any defined form name.
Default: unset.
wraptag="tag or pattern"
The tag (without angle brackets) to wrap the output.
Values: HTML tag or a string containing <+> pattern that will be replaced by the output.
Default: unset.

Examples

Example 1: Display a linked section list

<txp:section_list label="Sections" wraptag="p" break="br" />

Adds the label ‘Sections’ and wraps the output in a paragraph with each section on its own line.

Example 2: Display a styled section list

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

Example 3: Set active class using the container tag

<txp:section_list wraptag="ul" break="">
    <li<txp:if_section name='<txp:section />'> class="active"</txp:if_section>>
        <txp:section title="1" link="1" />
    </li>
</txp:section_list>

This code will add class="active" to the <li> element around the currently viewed section in the list.

Other tags used: if_section, section.

Genealogy

Version 4.8.0

Accepts valueless exclude attribute.

Version 4.7.0

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.
form attribute 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. :)