<txp:article /> sing/cont tag, 14 attributes

article

The basic article tag can be used as either a single tag or container tag and used to output one or more articles depending on the attributes used. Default attributes will be used when nothing specific is assigned.

It may be used as a container tag, in which case it must be specified as an opening and closing pair of tags, like this:

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

This is equivalent to putting the contained statements into a form named “my_form” and using:

<txp:article form="my_form" />

The tag is context−sensitive, which means it will grab articles from the currently viewed section, category or author.

When used on the front page, it will include articles from all Sections set to display “On front page”.

Related: if_article_list, if_first_article, if_last_article, if_individual_article

attributes

customfieldname="unset"
  • Restrict to articles with specified value for specified custom field name.
  • Replace “customfieldname” with the name of the custom field.
keywords="unset"
  • Restrict to articles with specified keyword(s).
status="live"
  • Restrict to articles with the specified status.
  • Values: live or sticky
time="past"
  • Restrict to articles posted within specified timeframe.
  • Values: past, future, or any (both past and future).
sort="Posted desc"
  • Values
    • ID (article id#)
    • Posted (date posted)
    • Expires (expiry date)
    • AuthorID (author name)
    • LastMod (date last modified)
    • LastModID (author name of last modification)
    • Title
    • Image (article image id#)
    • Category1
    • Category2
    • comments_count
    • Status
    • Section
    • Keywords
    • url_title
    • custom_1 through custom_10
      • Note: Each field in the “textpattern” table can be used as a sort key.
    • rand() (random)
    • score (how well the search terms match the article) is available as an additional value when viewing a search results list. (score desc is the default sort order for search results)
  • Direction
    • asc (ascending)
    • desc (descending)
offset="0" (integer)
  • The number of articles to skip.
limit="10" (integer)
  • The number of articles to display.
pageby="10" (integer)
  • The number of articles to jump forward or back when an older or newer link is clicked. Allows you to call the article tag several times on a page without messing up older/newer links. Default value matches the value assigned to limit.
pgonly="0" (boolean)
  • Do the article count, but do no display anything. Used when you want to show a search result count, or article navigation tags before the list of articles. Just Make sure that, other than pgonly, both article tags are identical (form−related attributes are the exception, they do not need to be assigned).
allowoverride="1" (boolean)
  • Whether to use override forms for the generated article list.
searchsticky="0" (boolean)
  • When outputting search results, include articles with status “sticky”.
form="default"
  • Use specified form.
listform="unset"
  • Use specified form when page is displaying an article list.
searchform="search_results"
  • The form to be used for your customized search results output.

presentation

label="unset"
  • Label prepended to item (or as first list item, where appropriate).
  • if wraptag is available and is set to ol or ul, the label will be the first list item.
labeltag="unset"
  • (X)HTML tag (without brackets) to wrap around label.
break="unset"
  • (X)HTML tag (without brackets) or string to separate list items.
wraptag="unset"
  • (X)HTML tag (without brackets) to wrap around the list.
class="unset"
  • (X)HTML class attribute to apply to the wraptag.

notes

  • The article tag is context−sensitive. It will produce different results depending on whether the page being viewed is an article list or an individual article.
  • Article−list context includes the default (home) page, section front pages, and category pages.
  • Individual−article context applies on an article page (i.e., a page with a URL like <http://example.com/archives/24/my−article>).

genealogy

Version 4.0.7

  • Can be used as a container.
  • wraptag and break attributes added.

Version 4.0.4

  • sort added (replaces sortby and sortdir)
  • sortby and sortdir deprecated

Version 4.0.2

  • pageby added
category: article
<txp:article /> 6 examples

Basic Use as Single Tag

Here is the article tag responsible for the main content of the home page on a new Textpattern 4.0.7 installation:

<txp:article limit="5" />

What this does…
Calls the default article form, which may contain any variation of article output you want to create. The default form cannot be deleted; it is theform you see on first viewing the Forms tab.
Uses the limit attribute to specify the maxiumum number of articles displayed in article list context. (If not specified, this defaults to 10.)

Specifying a Form

Expanding on example 1, here is the article tag responsible for showing lists of articles by category in the default Page of a new Textpattern 4.0.7
installation:

<txp:article listform="article_listing" limit="5" />

What this does…
In article list context, the form named “article_listing” will be processed and displayed for each article in the list. In individual article context, the default form would be used.

To see this in action…
On a new Textpattern install, from the home page click on one of the category links near the bottom (right above the Comment link).

Note the URL, similar to <http://example.com/category/meaningful−labor>
The category in the URL means this is a listing of articles by category. Here you see only the article title and posting date, because that is what is contained in the form named “article_listing”. Now click on the article title.

Note the URL, similar to <http://example.com/articles/1/welcome−to−your−site>
This is an individual article page. Once again you can see the full article, this time with comments showing.

Offsetting Article Display

Continuing from the previous examples:

<txp:article listform="article_listing" limit="5" offset="2" />

What this does…
Here we include the offset attribute to offset article display by two (2) articles. This means the five articles that will be displayed (i.e., limit="5") in article list context will begin with the third most recent article published in the site. (The offset will not be applied in individual article context.)

Why you might do it…
Offsetting articles is useful in situations where the most recent article(s) are already accessible in some way and you don't want them appearing again in normal article flow.

Using pageby to split article output on a page

<div id="first"><txp:article limit="1" pageby="10" /></div>
<div id="middle"><txp:article limit="8" offset="1" pageby="10" /></div>
<div id="last"><txp:article limit="1" offset="9" pageby="10" /></div>

Another: 

<txp:article limit="5" pageby="10" />
<txp:article limit="5" offset="5" pageby="10" />

The pageby number should be the total number of articles displayed on the page. Without pageby, each article tag would page independently based on its own limit, as if it was the only article tag.- From Alex’s original forum post.

Combined with Custom Fields

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

<txp:article colour="red" />

Article Sorting

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

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 web site visitors).

category: article