Textpattern tags are arguably the most interesting and important feature of Textpattern.
They represent a shorthand method for calling functions defined inside Textpattern core. The functions themselves represent content components, their sources, and means of displaying them.
The tags may be added to Pages and Forms in a great variety of ways depending on what you are trying to do. The tags are replaced with the content output they call as users move from one page to another in your site.
A self-closed tag is the most basic form of a Texpattern tag. Its structure is similar to that of a self-closed tag in HTML (e.g., <br />), most notably the inclusion of the terminating forward slash. Any self-closed Textpattern tag has the following syntactic structure: <txp:tagname />.
The tag is replaced by contents when Textpattern displays a page.
Self-closed tags can usually take attributes. For example, the following article tag demonstrates using the form and limit attributes:
<txp:article form="formName" limit="15" />
Most Textpattern tags are self-closed tags. The other type of tag is the container tag.
Container tags are composed of both an opening and closing tag element, giving them the syntactic structure of...
<txp:tag_name> ...content added here... </txp:tag_name>
The content that is added between container tags may be either text or other TXP tags.
Typical container tags are the permlink tag: <txp:permlink></txp:permlink> and all conditional tags. Container tags are used when something has to be enclosed by tags instead of being replaced by them.
A link is a good example: you have a text string (or a title tag) around which you want to wrap an HTML anchor element.
<txp:permlink><txp:title /></txp:permlink> bla bla <txp:permlink>Read more...</txp:permlink>
Would turn into something like:
<a href="/article/42/this-article-title">This article title</a> bla bla <a href="/article/42/this-article-title">Read more...</a>
Similar to (X)HTML, TXP allows you to nest tags within tags, as long as you close them in the correct order (i.e. tag closing cannot overlap).
Indenting is used here to show which tags belong to which bits of contained content. Notice the order in which the tags are openend and closed; it follows standard (X)HTML and XML principles:
<txp:if_section name="archive"> <txp:if_category> category list within the archive section <txp:else /> not a category list </txp:if_category> <txp:else /> some other section </txp:if_section>
From Textpattern 4.0.7 and above, there are no limits on nesting depth and you can nest the same tag within itself:
<txp:if_section name="article"> My Articles <txp:else /> <txp:if_section name="about"> About this website <txp:else /> Umm, something else. </txp:if_section> </txp:if_section>
Conventions for attributes
Most Textpattern tags allow you to specify attributes as key/value pairs to override default behaviour.
Example of an override <txp:tag key="value" /a>:
<txp:category type="image" title="1" /a>
Usage of attributes in Textpattern tags is similar to attributes in HTML.
A few important rules to remember:
- attribute values must always be delimited by double (or single) quotes. Single quotes have special meaning, so use double quotes by default.
- attribute keys must be lower case.
- for plugin developers: attribute keys can consist of the letters 'a' through 'z' and underscore (not as the first or last character).