On this page:
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/author, etc.
When used on the front page, article’s context will include articles from all sections set to display via ‘Section appears on front page?’ settings (see the Sections panel for more information).
<txp:article /> is not the same as
<txp:article_custom /> - you can check out the differences of that tag if you’re unsure of the differences!
Tag will accept content/behaviour and presentation attributes (case-sensitive):
- Whether to use override forms for the generated article list.
breakby="integer or string"v4.7.2+
- Used to group list items when separating by
break. If its value is a list of integers, they will be used as groups size. For example,
2(groups of 2 items) or
1,2(alternate groups of 1 and 2 items).
- Otherwise, the value is evaluated on each loop and
breakhappens as soon as it changes. Note that
stringmust be enclosed in double quotes (see Example 7).
- A form to be used as
break, generally jointly with
breakbyattribute. The special
<+>pattern in this form will be replaced with the list “chunk” accumulated when break happens (see Example 7).
- Default: unset.
- Restrict to articles with specified value for specified custom field name. Replace
customfieldnamewith the actual 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.
- Use specified form template to process each article.
- Include only those articles with ‘Section appears on front page?’ set on the Sections panel. If set to
0, all articles are displayed.
- Restrict to articles with specified keyword(s).
- The number of articles to display.
- Use specified form when page is displaying an article list.
- The number of articles to skip.
- The number of articles to jump forward or back when an older or newer link is selected. 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
- Do the article count, but do not 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).
- When outputting search results, include only those articles with ‘Include in site search’ set on the Sections panel. If set to
0, only articles in the current section are displayed. See @@Fixing search results@@ for more.
- The form to be used for your customized search results output.
- When outputting search results, include articles with status
- How to sort the resulting article list. Specify a value from the ones below, followed by a space and then add either
descto sort in ascending or descending order, respectively. Note: values are case sensitive on some servers.
nis the number of your custom field - for numeric values use
Image(article image id#).
LastMod(date last modified).
LastModID(author name of last modification).
Each field in the
textpatterndatabase table can be used as a sort key.
- When viewing a search results list,
score(how well the search terms match the article) is available as an additional value.
score descfor search results).
- Restrict to articles with the specified
- Restrict to articles posted within specified timeframe.
future) or a PHP-compatible date format. In the latter case,
timewill be considered as the end date of the interval started by
Common presentational attributes
These attributes, which affect presentation, are shared by many tags. Note that default values can vary among tags.
- Where value is an HTML element, specified without brackets (e.g.
break="li") or some string to separate list items.
br(but see break cross-reference for exceptions).
classto apply to the
- Default: tag name or unset (see class cross-reference).
- Label prepended to item.
- Default: unset (but see label cross-reference for exceptions).
- HTML element to wrap (markup) label, specified without brackets (e.g.
- Default: unset.
- HTML element to wrap (markup) list block, specified without brackets (e.g.
- Default: unset (but see wraptag cross-reference for exceptions).
Note on ‘article list’ vs. ‘individual article’ context
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
Example 1: Basic use as single tag
Here is the article tag responsible for the main content of the home page on a new Textpattern installation:
<txp:article limit="5" />
default article form, which may contain any variation of article output you want to create. The
default form cannot be deleted; it is the form you see on first viewing the Forms panel.
limit attribute to specify the maximum number of articles displayed in article list context (if not specified, this defaults to
Example 2: 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 installation:
<txp:article form="article_listing" limit="5" />
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 select one of the category links near the bottom (right above the Comment link). Note the URL, similar to
category in the URL means this is a listing of articles by category. Here you see only the article title, posting date and article information (not the full article itself), because that is what is contained in the form named
article_listing. Now select the article title. Note the URL, similar to
https://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 (if comments are enabled).
Example 3: Offsetting article display
Continuing from the previous examples:
<txp:article listform="article_listing" limit="5" offset="2" />
Here we include the
offset attribute to offset article display by
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 might you 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.
Example 4: Using pageby to split article output on a page
<div class="first"> <txp:article limit="1" pageby="10" /> </div> <div class="middle"> <txp:article limit="8" offset="1" pageby="10" /> </div> <div class="last"> <txp:article limit="1" offset="9" pageby="10" /> </div>
<txp:article limit="5" pageby="10" /> <!-- google ad --> <txp:article limit="5" offset="5" pageby="10" />
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.
Example 5: Combined with custom fields
<txp:article colour="red" />
This code will display articles that have a custom field named
colour with a value
Example 6: Article sorting
<txp:article sort="AuthorID asc, Posted desc" />
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 might you 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 7: Build a
<section />-separated list of article titles grouped by section
<section id="about (section name)">
- About (section title)
- 1st Article from about section
- 2nd Article from about section
- …another article
<section id="family (section name)">
- Family (section title)
- 1st Article from family section
- 2nd Article from family section
- …another article
- …and so on
Create the following Form named
<section id='<txp:section />'> <h2> <txp:section title /> </h2> <+> </section>
In Textpattern Page templates, add this tag to loop through all articles from all sections:
<txp:article sort="Section asc, Title asc" breakby="<txp:section />" breakform="sections"> <h3> <txp:title /> </h3> </txp:article>
breakform attribute added,
breakby attribute modified.
breakby attribute added.
Can be used as a container.
wraptag attributes added.
sort attribute added (replaces
sortdir attributes deprecated.
pageby attribute added.