The Textpattern CMS `<txp:article>` tag is a monster. It’s one of the most extensive and sometimes misunderstood Textpattern tags, and on that basis I debated whether or not a 500 word blog post could do it justice. In the end I decided that no, it wouldn’t – but I’ve never been one to back down from a challenge, so here goes. Ladies and gentlemen, I present Pete Cooper’s Handy Guide To The Textpattern CMS `<txp:article>` Tag In Association With Arvixe And Hopefully Less Than Two Thousand Words For Great Justice. I’ll work on that title for a future revision.
At a fundamental level, the `<txp:article>` tag is used to output Textpattern articles. It is context-sensitive insofar as its location will dictate what it will do. It can also be used in a single or container tag context. The tag has a bunch of attributes, far more than most other tags, and has a number of similarities with the `<txp:article_custom>` tag which I’ll be exploring in more detail in my next post. There are some marked differences between `<txp:article>` and `<txp:article_custom>` and over time you’ll learn which is best to use for each situation.
Regarding context sensitivity, when `<txp:article>` is used on the front page of the site (i.e., the `default` section), its scope is for all articles in all sections which are set to display on the front page. If it’s used elsewhere, then the scope is narrowed to that of the current section, category or author, and so on.
The tag’s content and bbehavioralattributes are as follows, with default values (accurate as of Textpattern 4.5.7):
- allowoverride=”boolean” (default: 1 [yes])
- customfieldname=”value” (default: unset)
- form=”form name” (default: default)
- keywords=”keyword(s)” (default: unset)
- limit=”integer” (default: 10)
- listform=”form name” (default: unset)
- offset=”integer” (default: 0)
- pageby=”integer” (default: matches the `limit` value)
- pgonly=”boolean” (default: 0 [no])
- searchall=”boolean” (default: 1 [yes])
- searchform=”form name” (default: search_results)
- searchsticky=”boolean” (default: 0 [no])
- sort=”sort value(s)” (default: `Posted desc`, and `score desc` for search results)
- status=”status” (default: live)
- time=”time” (default: past)
That’s a chunky list. I’ll walk through it with you, line by line. Each Textpattern article has an article form that’s used to output it to the browser or user agent. It’s possible to change this form from a pre-determined default to any other article form; the `allowoverride` attribute. The `allowoverride` attribute determines whether an override form should be allowed or not, and is often used in conjunction with the `form` attribute which indicates which is the form to be used.
The list of articles that are processed and output can be fine-tuned with the `customfieldname` attribute. There is no `customfieldname` attribute in the strictest sense, it’s a placeholder for the actual name of the custom field within the article(s). Using this attribute will select articles that have the custom field matching a provided value. For example:
<txp:article fruit="lemon />
…will only select articles which have a custom field name of `fruit` set to a value of `lemon`.
The `form` attribute dictates which article form should be used to display the articles(s). If a list of articles is being processed, it’s normal to see this attribute used alongside `allowoverride` to determine whether per-article form overrides are permitted.
Using the `keywords` attribute is useful for populating an article list based on per-article keywords. It’s a different approach to using `customfieldname` as it doesn’t rely on an absolute custom field value; it can be used to search inside the keywords are for one of more comma-separated words.
The `limit` attribute defines how many articles are included in the list. This can be sensible (10, for example) or less sensible (100000, or even higher). Use with caution, lest your readers give you a hard time over page load times.
The `listform` attribute differs from the `form` attribute in that it can select a different form to construct the article list, if required. It’s unset by default, so you can make provision for building the article list in the default form, or keep things a bit more modular by offloading the list view into a different form.
Using the `offset` attribute will give you scope to start at a given point in the article list. A client asked me to insert a banner ad after the third article in her list, and then continue the article listing, and using `offset` was the most straightforward route to achieving this. Essentially, I used `<txp:article>` to output three articles, then inserted the ad code, then used an additional `<txp:article>` tag after that to output twelve articles, with an `offset` value of three so as not to repeat the first three articles.
The `pageby` attribute is helpful if you’re providing multi-page navigation. This is set to the `limit` default value (10) unless otherwise specified, and it ensures that pagination works correctly; that is, if you have an article list of 10 articles, you ideally want the next page to list the following 10 articles, and not miss any.
The `pgonly` attribute is used to determine the article count, but it doesn’t output anything to the browser or user agent. Useful for populating search result counts.
The `searchall` attribute determines the scope of the article search. Sections can opt in or out of article search via the admin-side interface, and this attribute either includes those sections or limits to the current section only.
The `searchform` attribute gives more control over the form to be used for displaying search results. It’s similar to `listform`, but only relevant to search results.
The `searchsticky` attribute tells Textpattern to either include or exclude articles which are marked as sticky.
The `sort` attribute is used to fine-tune the sorting used when articles are displayed. There’s a sizable list of values to pick from, too:
- `ID` (the article number)
- `AuthorID` (the article author’s name)
- `LastMod` (the date the article was most recently modified)
- `LastModID` ( the author name who performed the most recent modification)
- `Posted` (the article timestamp)
- `Expires` (the article expiry date)
- `Title` (the article title)
- `Category1` (the article’s category1)
- `Category2` (the article’s category2)
- `comments_count` (the number of article comments)
- `Status` (the article’s status)
- `Section` (the article’s section)
- `Keywords` (the article’s keywords)
- `Image` (the article’s image number)
- `url_title` (the article’s URL title)
- `custom_n` [where n is a number] (the article’s corresponding custom field)
- `rand()` (a random sorting process)
Additionally, each field in the `textpattern` database table (i.e., where the articles are stored) can be used as a sort key. All of the above attribute values should be applied with either `asc` for ascending sort order, or `desc` for descending sort order.
In the situation where search results are being viewed, the sort attribute list has an additional option:
…which, as you may have already deduced, sorts by the article score according to the search term(s).
The `status` attribute tells Textpattern to return articles with the `live` or `sticky` status.
Finally, the `time` attribute returns articles from the past, future or any and can take one of three possible values: `past`, `future` or `any`. Pretty straightforward when I put it that way, eh?
In addition to these content and/or bebehavioralttributes, `<txp:article>` can also take some presentational attributes to fine-tune styling and HTML output. These attributes, common to a bunch of other Textpattern tags, are:
- label=”text” (default: unset)
- labeltag=”element” (default: unset)
- wraptag=”element” (default: unset)
- class=”name” (default: unset)
- break=”value” (default: unset)
That’s a whole of unset attribute values, right? The aim here is to give you the option to style your output, but not force anything on you. The upshot of this being that if you want to do your styling thing, you’ll have to have a idea of what you want to achieve instead of using an out-of-the-box. Rightly or wrongly, if you’re looking for perfectly-styled elements with no additional work, you’ll have to use another CMS. Where Textpattern excels is giving you the platform to build, rather than providing an all-in solution from the outset.
Next time: `<txp:article_custom>` — a bit like `<txp:article>`, but sometimes not. It’s like `<txp:article>`’s bohemian cousin. Come back and read about it, you’ll love it.