Continuing in the Textpattern CMS tag function theme for the month, this article will focus on article-related tags. Last time I talked about global tags – that is, tags that can be used just about anywhere in the Textpattern ecosystem. Article tags are, as the name implies, used in relation to single or multiple articles and allow functionality to be applied to said articles. In a similar vein to my previous article, I’ll be introducing some straightforward and easy-to-understand article tags. In addition, I’ll be introducing the concept of tag attributes. Tag attributes are not specific to article tags, and are not available on every tag, but this is an excellent point to show you some cool things. With that in mind, let’s go!
Textpattern article tags are best used inside an article form. I’ll break that sentence down in case you don’t understand the terminology:
- a Textpattern-powered website has one or more sections (such as about, journal, news, contact and so forth)
- each article is filed in one section (more if you use a plugin to extend functionality)
- articles can have zero, one or two categories (more if you use a plugin to extend functionality)
Ignoring the plugin element for now, if you can get your head around the idea of an article having a section or a section having one or more articles assigned to it, that’s the key point. Now, when articles are displayed in Textpattern, they can be displayed as a list – say, for a blog page that has a list of posts with the most recent at the top – or individually, which might be a news article. In each example case, the behind-the-scenes stuff works like this:
- a section has a page assigned to it
- this page calls an article form
- the article form retrieves data from the article
Essentially, if the browser is displaying an article list the form will loop for the number of articles in the list. A single article will mean the article form goes through once, whereas a blog page with the 15 most recent articles will make the form loop 15 times and refer to a different article in each case. There are, for completeness, exceptions to this rule, but for the meantime this will set you in good stead for understanding how Textpattern does its work.
A simple article form could look like this:
<h3><txp:title /></h3> <txp:body /> <span><txp:posted /> · <txp:author /></span>
Textpattern tags start with ‘txp':
- <txp:title /> – inserts the title assigned to the article
- <txp:body /> – inserts the body of the article
- <txp:posted /> – inserts the posted/published timestamp of the article
- <txp:author /> – inserts the author of the article
In each case, the tag will extract the relevant information from the article and substitute it in the browser markup. The article form above might end up looking like this to the browser:
<h3>My visit to the grocery store</h3> <p>Yesterday I visited my local grocery store and bought three apples. It made me want to bake an apple pie, so I will return to the store tomorrow to purchase the ingredients I need.</p> <span>Jan 25, 12:00pm · Jane Kent</span>
Note all the references to Textpattern tags have been replaced. You should also know that when the article form cycles (loops) through multiple times to create an article list, it will invariably read from multiple articles.
Let’s take a look at those tags again:
- <txp:title />
- <txp:body />
- <txp:posted />
- <txp:author />
The <txp:title /> tag takes the title from the article and displays it. The only other thing this tag can do is display the title as it is set, but prevent the typesetting widow phenomena of having a single word on one line. In order to do this, the <txp:title /> tag takes an attribute, like this:
<txp:title no_widow="1" />
The tag attribute is optional. Each attribute has a default setting. If an attribute is not set in the tag, the default value is taken. In the case of <txp:title /> and no_widow, the default is set by the administrator in the preferences (in English, the route is Admin -> Preferences -> Advanced -> Publish -> Prevent widowed words in article titles?). Rather than having Yes or No in the attribute, a numerical value is used instead: 0 is No, 1 is Yes.
Where the tag attribute is particularly useful is if you want set a global setting in preferences, and then override this preference for a specific area of the site. There’s no harm in setting a tag attribute where your supplied setting is already the default, especially if you decide to change a global setting in the admin pane at a later date.
The <txp:body /> tag has no attributes at all. It simply extracts the article body (content) and displays it. The <p> tag in the example above might have been added into the body manually or have been applied by Textile, Textpattern’s in-built text processor.
The <txp:posted /> tag has a number of attributes that affect the way the posted (published) timestamp is displayed, three of which are:
- format – a choice of ‘since’, strftime, iso8601, rfc822 or w3cdtf
- gmt – a choice of 1 or 0 for Yes or No
- lang – territory code in iso639-2 format
Where there are multiple attributes available to use, you can stick with the defaults and not use any of them, use one, or multiple. All of these are valid <txp:posted /> examples:
<txp:posted /> <txp:posted format="since" /> <txp:posted format="since" gmt="1" />
Notice how attributes are piggy-backed in the tag. This is absolutely valid and normal behaviour. The since option displays how long ago an article was published, ranging from ‘a few seconds ago’, minutes, hours or days.
If you want a very specific time format displayed, you can have it. If you want to let Textpattern use its defaults, you can set your preferred time format in your administration preferences from a drop down menu.
The <txp:author /> tag has numerous attributes, one of which is title. Using the title attribute selects whether the article author’s name is displayed as their real name (title=”1″) or Textpattern login name (title=”0″). The default is currently title=”1″.
There are many more Textpattern article tags to use, should you have a particular task or function in mind. If this article has sparked your interest, I recommend you look at the full list of Textpattern article tags to see what works for you. Next time we meet I’ll be introducing conditional tags, and I hope you’ll join me.