Help?

article custom

From Textpattern CMS User Documentation

<txp:article_custom />

The article_custom tag is a single or a container tag that provides a variety of custom options for sorting, selecting, and displaying articles (the tag will be replaced with one or more articles).

If used as a container, it must be specified as an opening and closing pair of tags, like this: 

<txp:article_custom>
...contained statements...
</txp:article_custom>

This is equivalent to putting the contained statements into a form named "my_form" and using <txp:article_custom form="my_form" />.


Unlike the article tag, article_custom will always return an article list and is not context-sensitive. This means while the article tag can only see posts within the currently viewed section/category/author and so forth, article_custom can see all posts from all sections, categories and authors unless you restrict it via attributes (see below), thus context-sensitive navigation tags, such as older and newer, will not work.

A comparison of how article and article_custom differ.

Related Info: Customizing txp:recent_articles.

Contents

Attributes

Tag will accept the following attributes (case-sensitive):

id="article ID"
Display the specific article or list of articles (each ID separated by a comma).
IMPORTANT: When a list is supplied, this does not imply a sort order (see Example 6).
Default: unset.
customfieldname="value"
Restrict to articles with specified value for specified custom field name. Replace "customfieldname" with the name of the custom field.
IMPORTANT: Using dashes (-) or spaces may cause errors or render this feature ineffectual. Underscores in both custom field names and values are confirmed to work.
Default: unset.
section="section name"
Restrict to articles from specified section(s).
Value: (comma separated list of) section name(s).
Default: unset, retrieves from all sections.
category="category name"
Restrict to articles from specified category/ies. Note: the category names may be different to the Title you typed when you created the category, as the names are sanitized for URL use. Check the Categories tab to ensure you are using the correct names.
Value: (comma separated list of) category name(s).
Default: unset, retrieves from all categories.
keywords="keyword(s)"
Restrict to articles with specified keyword(s).
Default: unset.
excerpted="y"
Restrict to articles with/without an excerpt.
Value: y (yes, return only those containing an excerpt).
Default: unset (no, return all).
status="status"
Restrict to articles with the specified status.
Values: live or sticky.
Default: live.
time="time"
Restrict to articles posted within specified timeframe.
Values: past, future, or any (both past and future).
Default: past.
expired="boolean"
Whether to include articles that have expired or not.
Values: 0 (don't include expired articles) or 1 (include expired articles).
Default: Setting of preference Publish expired articles.
month="yyyy"/"yyyy-mm"/"yyyy-mm-dd"
Restrict to articles posted within the specified year/month/day.
Default: unset.
author="author name" (Login name)
Restrict to articles by specified author(s).
Value: (comma separated list of) author name(s).
Default: unset, retrieves from all authors.
sort="sort value(s)"
How to sort resulting list.
Values:
ID (article id#)
AuthorID (author)
LastMod (date last modified)
LastModID (author of last modification)
Posted (date posted)
Expires (expiry date)
Title
Category1
Category2
comments_count
Status
Section
Keywords
Image (article image id#)
url_title
custom_1 through custom_10
(From 4.2.0 on: custom_n)
For numeric values use "(custom_n+0)"
rand() (random).
Each field in the "textpattern"-table can be used as a sort key.
Default: Posted desc.
offset="integer"
The number of articles to skip.
Default: 0.
limit="integer"
The number of articles to display.
Default: 10.
allowoverride="boolean"
Whether to use override forms for the generated article list.
Values: 0 (no) or 1 (yes).
Default: 0.
form="form name"
Use specified form.
Default: default.

Common Presentational Attributes

These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.

label="text"
Label prepended to item.
Default: unset (but see label cross-reference for exceptions).
labeltag="element"
HTML element to wrap (markup) label (e.g., labeltag="h3")
Default: unset.
wraptag="element"
HTML element to wrap (markup) list block (e.g., wraptag="ul")
Default: unset (but see wraptag cross-reference for exceptions).
class="name"
HTML class to apply to the wraptag attribute value.
Default: tag name or unset (see class cross-reference)
break="value"
Where value is an HTML element (e.g., break="li") or some string to separate list items.
Default: br (but see break cross-reference for exceptions).

Examples

Example 1: List articles published in specified month

<txp:article_custom form="month_list" sort="Section asc" month="2004-10" />

Example 2: Select by keyword

<txp:article_custom sort="Posted desc" keywords="One" />

Example 3: Select by author

<txp:article_custom form="author_list" author="Parkling" />

the author_list article form might go thus.

<p><txp:permlink><txp:title /></txp:permlink></p>

Other tags used: permlink, title

Example 3a: Container tag

The following is exactly equivalent to Example 3: 

<txp:article_custom author="Parkling">
<p><txp:permlink><txp:title /></txp:permlink></p>
</txp:article_custom>

Example 4: Combined with custom fields

This code will display articles that have a custom field named "colour" with a value "red":

<txp:article_custom colour="red" />

Example 5: Article sorting

<txp:article_custom sort="AuthorID asc, Posted asc" />

What this does...
uses the sort attribute to define values by which to order article output. In this case two values are declared. AuthorID asc first orders articles alphabetically by author names, then Posted desc orders them by date published ("desc" meaning newest to oldest).
Why you might do it...
Sorting is a powerful way to group articles (e.g., by author), and/or give priority to articles most recently published (typically better for your website visitors).

Example 6: Select by id

<txp:article_custom id="81,73" />

What this does...
outputs articles specified by list of IDs
order of articles may not match the order of the IDs in the list

<txp:article_custom id="81,73" sort="field(id,81,73)" />

What this does...
outputs articles specified by list of IDs, in the given order

Genealogy

Version 4.5.0

  • Added expired attribute.

Version 4.0.7

  • Can be used as a container tag.
  • id can take a comma-separated list of IDs.
  • wraptag and break attributes added.

Version 4.0.6

  • Support added for comma separated lists for section, category and author attributes

Version 4.0.4

  • listform deprecated (it never made a difference to article_custom anyway)
  • sort added (replaces sortby and sortdir)
  • sortby and sortdir deprecated
Retrieved from "http://www.textpattern.net/wiki/index.php?title=article_custom"
Translations [?]