When a Textpattern CMS article is saved, it can optionally have one or two categories assigned to it. These categories can be useful if you want or intend to display selected articles based on their category or categories, either in the front-side for your users, or in the admin-side. It’s important to know that the article category is not required, whereas the article section is mandatory. If you’re becoming accustomed to Textpattern terminology, section and category can be somewhat confusing. Briefly:
- an article section dictates which part of the website it is assigned to and is required
an article category provides additional sorting (categorization) of the article and it optional
- An example of a section might be `blog`, `about`, `contact` and so forth; think of an area of a website that the content will reside in. Example category names could be `2015`, `bestsellers`, `guest posts` and the like; these are more like badges to define what the article is, rather than where it should live.
There are two Textpattern tags that deal with article categories: `<txp:category1>` and, perhaps unsurprisingly, `<txp:category2>`. They both have identical tag attributes; a tag attribute is a way of fine-tuning the output of a tag. Both `<txp:category1>` and `<txp:category2>` can be used on their own without attributes, and that will assume certain default settings as dictated by the version of Textpattern you’re running. Just because the attribute wasn’t explicitly included doesn’t mean it isn’t absorbed and processed. There are 6 attributes associated with the tags, each with their own default settings (correct as of Textpattern version 4.5.7):
- class=”class name” (default: unset)
- link=”boolean” (default: 0 [no])
- section=”section name” (default: unset)
- title=”boolean” (default: 0 [no])
- this_section=”boolean” (default: 0 [no])
- wraptag=”tag” (default: unset)
The `class` attribute assigns a CSS class to the output. The `link` attribute will determine if the outputted text is linked to an article list of other articles in the category. The `section` attribute determines whether the link should relate to a specifically named section. The `title` attribute will output the category title instead of the title name if it’s set to `1`. The `this_section` attribute determines whether the link should relate to the current section. The `wraptag` attribute defines what, if any, tag is used to enclose the outputted text.
Another point to note about `<txp:category1>` and `<txp:category2>` is that they can be used as single or container tags. The `link` attribute can only be used in a single category context, the other attributes can be used in both instances.
For the following code snippets, an article is assigned to two categories: `fruit` is the name for the first category, and `lemon` is the name for the second. In each case, the category title can be different (or the same) as the category name. In this example, the `fruit` category has a title of `Articles about fruit` and `lemon` is titled `When life deals you lemons…`. In its simplest form, category tags can be used on their own, like this:
That code will be translated into HTML by Textpattern and, in the absence of provided attributes, will assume the attribute defaults. That code will output the first category name (`fruit`). It won’t have a CSS class, or be linked, or output the title or have any tag wrapped around it. As it’s not linked, the `this_section` attribute is redundant. Overriding the defaults is straightforward enough. For example, to switch the output from the category name (`fruit`) to the category title (`Articles about fruit`), just throw in a `title=”1″`:
<txp:category1 title="1" />
Want to make it into a link, too? No problem:
<txp:category1 link="1" title="1" />
Now, that link will show a list of articles in the whole site with the same category. To restrict to the current section, add in `this_section=”1″`:
<txp:category1 link="1" this_section="1" title="1" />
Let’s throw the whole thing inside a `<span>` tag:
<txp:category1 link="1" this_section="1" title="1" wraptag="span" />
…and give that wrapper a CSS class:
<txp:category1 class="primary" link="1" this_section="1" title="1" wraptag="span" />
That’s 5 of the 6 attributes in action. The remaining attribute is `section`, and is not relevant as `this_section` is in use; it’s an either-or thing, the link can’t point to two places at once.
Next time I’ll be showing you some of the fancy things `<txp:article>` can do. Bring a beverage, it’ll be fun. And a bit terrifying.