Textpattern CMS uses, amongst other things, sections and categories as methods of managing its content. The significance of sections and categories relates primarily to articles, rather than images or files. Broadly, it breaks down like this: a text article is assigned to a section (mandatory), and can optionally have one or two categories. With this in mind, the statement can be turned on its head: sections can refer to articles, and categories can also refer to articles. Images, files and links can (optionally) be assigned to one category. This article explains some of the things that the Textpattern `section` and `category` tags can do; both of these tags refer to the articles, and not images, links or files, with an exception toward the end. Confused? OK, let’s go.
Both `section` and `category` tags share some common elements and tag attributes. At a base level, the following tag usage will display the current section or category respectively:
<txp:section /> <txp:category />
Sections and categories have names and titles. The given name is typically in a format used in a URL, whereas the title can be more verbose or descriptive. By default, the section and category tag will output the name rather than the title. Both tags can be tweaked to output the title instead:
<txp:section title="1" /> <txp:category title="1" />
Both tags can make use of a CSS class too, either for the text itself:
<txp:section class="fancy-text" /> <txp:category class="fancy-text" />
…or for the wrap tag (i.e., what the output will be wrapped in) supplied:
<txp:section class="fancy-text" wraptag="span" /> <txp:category class="fancy-text" wraptag="span" />
Again, both tags can be made into hyperlinks (default behaviour is not to hyperlink):
<txp:section link="1" /> <txp:category link="1" />
Related to this, the both tags can have their output changed into a URL instead:
<txp:section url="1" /> <txp:category url="1" />
The final common attribute between the two tags can change the default behaviour from the current section/category to a specific section/category:
<txp:section name="fruit" /> <txp:category name="fruit" />
Many of the above attributes can be backpacked into the same tag construct, like this:
<txp:section title="1" class="fancy-text" wraptag="span" link="1" name="fruit" /> <txp:category title="1" class="fancy-text" wraptag="span" link="1" name="fruit" />
The attribute notable by its absence from that block is `url`; the output can only ever be one of:
- the section/category name
- the section/category title
- the section/category URL
If more than one of these is required, then multiple tag instances are required. The default behaviour is to output the name of the section/category, and using the `title` or `url` attributes will change that. Using both won’t work, and makes the Textpattern overlords weep.
The `category` tag has some specific attributes that are not relevant to or recognised by `section`:
- section=”section name”
The `section` attribute will restrict the the category search to just the named section. If it’s omitted then the current section is used. Using the `section` attribute will override the `this_section` attribute which, perhaps unsurprisingly, will restrict the search to the the current section. There are some backward-compatibility issues going on with this, so using `this_section` is not relevant if you’re up-to-date with Textpattern. The final attribute, `type`, will instruct Textpattern to restrict to articles, images links or files accordingly. The default here is `article`.
Next time: `category_list` and `section_list`.