======  txp:article  ======

The basic ''article'' tag is a Single Tag and generally used in a Page template. The tag is used to output one or more articles depending on Attributes used. Default attributes will be used when nothing specific is assigned.

''article'' 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 "On front page".



=====  Syntax  =====
The ''article'' tag has the following syntactic structure...
<code php><txp:article /></code>

======  Attributes  ======

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

=====customfieldname="value"=====
Restrict to articles with specified value for specified custom field name. Replace "customfieldname" with the name of the custom field.

=====keywords="keyword"=====
Restrict to articles with specified keyword(s).

=====status="status"=====
Restrict to articles with specified status. Available values: __draft__, __hidden__, __pending__, __live__, __sticky__. Default is __live__.

=====time="time"=====
Restrict to articles posted within specified timeframe. Available values: __past__, __future__, or any (both past and future). Default is __past__.

=====sort="sort value(s)"=====
How to sort resulting list. Available values: __ID__ (article id#), __AuthorID__ (author), __LastMod__ (date last modified), __LastModID__ (author of last modification), __Posted__ (date posted), __Title__, __Category1__, __Category2__, __comments_count__, __Status__, __Section__, __Keywords__, __Image__ (article image id#), __url_title__, __custom_1__ through __custom_10__, __rand()__ [[http://dev.mysql.com/doc/refman/5.0/en/mathematical-functions.html#function_rand|random]]. When viewing a search results list, score (how well the search terms match the article) is an additional value available. Default value is __Posted__ desc (score desc for search results).

=====offset="integer"=====
The number of articles to skip. Default is __0__.

=====limit="integer"=====
The number of articles to display. Default is __10__.

=====pageby="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="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). Default is __0__ (no).

=====allowoverride="boolean"=====
Whether to use override forms for the generated article list. Default is __1__ (yes).

=====searchsticky="boolean"=====
When outputting search results, include articles with status "sticky". Default is __0__ (no).

=====form="form name"=====
Use specified form. Default is __default__.

=====listform="form name"=====
Use specified form when page is displaying an article list.

=====searchform="form name"=====
The form to be used for your customized search results output. Default is: __search_results__.




======  Examples  ======

=====Will display 5 articles using the article form Default=====


<code php><txp:article form="default" limit="5" /></code>

=====Will display 5 articles starting with the third article in the sort order=====


<code php><txp:article offset="2" limit="5" /></code>



=====Using pageby to split article output on a page=====

<code php>
<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>
</code>

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.


<code php>
<txp:article limit="5" pageby="10" />
<!-- google ad -->
<txp:article limit="5" offset="5" pageby="10" />
</code>


=====Will display articles that have a custom field named "colour" with a value "red"=====


<code php><txp:article colour="red" /></code>

=====Sort articles by author (a-z) then by date (oldest to newest)=====

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







======  Genealogy  ======

=====  Version 4.0.4  =====

  * __sort__ added
  * __sortby__ and __sortdir__ deprecated

=====  Version 4.0.2  =====

  * __pageby__ added