Continuing with Textpattern CMS structural tags, in this article I’m focussing on `category_list` and `section_list`. For today’s outing, there will be a similar approach to the previous tag explanation; the common elements and attributes will be covered, and then some of the tag-specific stuff will be interspersed. Please note that this is not an exhaustive list of what `category_list` and `section_list` can do, and you are encouraged to investigate Textpattern Resources if you’re curious.
At a base level `category_list` and `section_list` are instrumental in outputting a list of categories or sections. Both can be used as single or container tags, and both can be used as-is without any additional attributes, though it’s recommend you do make use of them. Briefly, `category_list` is used to output a list of linked categories, and `section_list` will do the same for sections. As single tags, these will work as-is:
<txp:category_list /> <txp:section_list />
In each case, they will assume defaults and the output will be affected accordingly. The two tags have some functionality attributes in common:
…and 5 common presentational attributes, too:
Using `active_class` will assign a CSS class to the currently-viewed item, whether it’s a section, a category or both. Adding the `exclude` attribute into a tag construct allows a comm-separated list of categories or sections to be excluded from the output. Using `form` is helpful if there is a very specific way that the list should be built, whether it’s simple or complex. The form will loop through and populate the category or section list with the relevant components.
The final item in the common functional attributes, `sort`, will arrange the output in a specific way, according to supplied details. This differs a little between `category_list` and `section_list`. For category lists, the `sort` values can be:
- rand() (random sorting)
…whereas the `section_list` sort value list comprises:
In each case, the items can be sorted by a given criteria (name, title, and so on) in ascending or descending order. To sort by name ascending, for example, the following code could be used:
<txp:category_list sort="name asc" /> <txp:section_list sort="name asc" />
Want to flip it round and have the items sorted by reverse title order? No problem:
<txp:category_list sort="title desc" /> <txp:section_list sort="title desc" />
The presentational attributes are all used to define how the list is presented once it’s been constructed. These can be largely ignored if the decision to use a custom-made form is taken as this route offers more functionality. That said, using the presentational attributes offers a bunch of control over straightforward lists. The `label` attribute defines what text will be prepended to the item; for example, a bullet or other motif. Related to this, the `labeltag` will extend the styling of `label` by providing the HTML with which to wrap around it. This differs to `wraptag` which is used to specify the HTML wrapper for the list block, and not the `label` value. The `class` attribute defines the CSS class for the list item, and `break` is the HTML wrapper for the list item. Make sense? Great.
Bearing all that in mind, it’s time to start building a few example code blocks. Note that although I am listing the `category_list` and `section_list` examples together, they do not need to be used in pairs like this; it’s more of a learning aid to assist you with seeing the common elements between the tags. This example will output categories/sections as paragraphs, with line breaks between each item:
<txp:category_list label="Categories" wraptag="p" break="br" /> <txp:section_list label="Sections" wraptag="p" break="br" />
The following adds a few more tags in
<txp:category_list label="Categories" wraptag="p" break="br" sort="title asc" form="cat_list" class="fancy-text" /> <txp:section_list label="Sections" wraptag="p" break="br" sort="title asc" form="sec_list" class="fancy-text" />
…and so on. The best way to learn what does what in real terms is to try it for yourself. Do stop by and leave a comment or question if you’re stuck.
Next time: `output_form`.