I’ll say this from the get-go: `<txp:article_custom>` and `<txp:article>` are not the same. They share a bunch of attributes, yes, but they do two different jobs and cannot be simply interchanged/swapped out with one another. There be dragons.
The Textpattern documentation website explains the differences pretty well and rather more succinctly than I can here, so here’s the deal:
Unlike the `<txp:article>` tag, `<txp:article_custom>` will always return an article list and is not context-sensitive. This means while the `<txp:article>` tag can only return posts within the currently viewed section/category/author and so forth, `<txp:article_custom>` can see all posts from all sections, categories and authors unless you restrict it via attributes, thus context-sensitive navigation tags, such as `<txp:older>` and `<txp:newer>`, will not work.
Note: I’ve edited some of the presentation above for clarity, but the gist is absolutely right on the money.
At this point, I’d recommend you refresh your memory by reading my previous post about `<txp:article>` because there’s a lot of common ground. And yes, I know I said `<txp:article>` and `<txp:article_custom>` are different; they do have a lot in common, however.
- allowoverride=”boolean” (default: 0 [no])
- author=”author name(s)” (default: unset [all authors])
- category=”category name(s)” (default: unset [all categories])
- customfieldname=”value” (default: unset)
- excerpted=”y or n” (default: n [no])
- expired=”boolean” (default: according to admin-side preference)
- form=”form name” (default: default)
- id=”article number(s)” (default: unset)
- keywords=”keyword(s)” (default: unset)
- limit=”integer” (default: 10)
- month=”yyyy”/”yyyy-mm”/”yyyy-mm-dd” (default: unset)
- offset=”integer” (default: 0)
- section=”section name(s)” (default: unset [all sections])
- sort=”sort value(s)” (default: Posted desc)
- status=”status” (default: live)
- time=”time” (default: past)
You will no doubt have picked up some common attributes between this tag and `<txp:article>`. You may have spotted some of the default values are different, and you’d be correct. Let’s dig in a little deeper.
The `allowoverride` attribute determines whether to permit article-specific form overrides. Each article is presented with a form, and this form is set by the `form` attribute (see below). If an article has a custom form specified, this can be allowed or denied.
The `author` attribute determines which author(s) should have their articles included in the output. The `category` attribute works in a similar way to choose which article categories should be included.
Using the `customfieldname` attribute is a neat way to select articles based on the content of one or more custom fields. If a custom field value equals the value provided, it will be displayed.
Articles with excerpts can be selected with the `excerpted` attribute. This is a `y` or `n` value, which contrasts with the `expired` value options of `1` or `0`. Don’t get confused.
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.
The `id` attribute is ideal for selecting specific articles according to their numerical ID. It doesn’t matter if their custom fields or other indicators change, the ID will stay the same.
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.
You can select articles from a given date range with the `month` attribute.
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 `section` attribute is perhaps the thing that separates `<txp:article_custom>` from `<txp:article>`. You can select which section(s) to include in the article output. Very useful.
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.
The `status` attribute tells Textpattern to return articles with the `live` or `sticky` status.
The `time` attribute returns articles from the past, future or any and can take one of three possible values: `past`, `future` or `any`.