Index · 25.03.04

  1. Intro
  2. Tag Types
  3. TXP Forms: an overview
  4. Attributes
    4.1 Frequent attributes
  5. Page column tags
    1. Article Tags: article, article_custom.
    2. Article Navigation Tags : link_to_next, next_title, link_to_prev, prev_title, newer, older.
    3. Page Navigation Tags: category_list, link_to_home, popup, recent_articles, recent_comments, related_articles, search_input, section_list.
    4. Feed Tags: feed_link, link_feed_link
    5. Miscellaneous tags: output_form, linklist, css, sitename, page_title, email, site_slogan, password_protect
    6. Image Tags : image_index, image_display
  6. Form Tags
    1. Articles
    2. Comments Listing
    3. Comments Writting
    4. Search Results
    5. Images: image.
    6. Links
  7. Other tags
    1. Conditionals
    2. Development Related Tags: txp:notice

Comment

* * *

Intro · 25.03.04

Among other features, TXP comes with a powerful mechanism to obtain a high degree of customization in the look & feel of your TXP powered website, providing us a fine grane control over almost all the aspects we should take into consideration when we manage our site with a CMS.
All output related things are handled throughout TXP tags.

TXP tags are prefixed by txp: and look like common HTML tags or, better yet, like XML tags – lowercased, of course – where the string “txp” is the qualified namespace prefix. Just after this prefix you can find the tag name.

Also like XML/XHTML tags, TXP tags can have one or two tag marks. So, we can have “single” tags, like the <img /> tag on XHTML, or “container” tags, like the <p></p> tag on XHTML.


TXP single & container tags



<!—single tag—>
<txp:page_title />
<!—container tag—>
<txp:link_to_home>Home</txp:link_to_home>

Comment

* * *

Tag Types · 27.03.04

We can differentiate between 2 big types of TXP tags: Page column tags & Form tags.

Page column tags are intended to appear on Page Templates. You can easily create them using the TXP TAG BUILDER ASSISTANT by clicking on anyone of the links on the left side of the page section, under the presentation tab of your TXP installation.

Obviously, Form Tags are destinated to be placed on TXP forms templates. You can also build them using the TXP TAG BUILDER ASSISTANT, again on the left side of your forms section, but be careful of use the appropriated tags for each form, due to there are several types of form tags, that will have sense only in the form they were created for.

Haven’t you heard anything about TXP forms previously?. Ok, let’s go to give them a quick look before to continue.

Comment

* * *

Textpattern Forms: An Overview · 27.03.04

In TXP, forms are small template fragments, wich can be used to specify what information we want to show about an article, a comment, a link, ..., when TXP finds a page column tag referred to one of these TXP sections.

TXP forms allow us to reuse a template fragment refered to an article on different TXP pages and, better yet, to choose what info we want to show for a given article, using the override default form select on that article. (One of the coolest TXP features, without doubt).

For example, the default article form looks like this:


Default article form



<h3>
   <txp:permlink><txp:title /></txp:permlink>
   &#183;<txp:posted />
</h3>
   <txp:body />
<p>
   <txp:comments_invite />
</p>

When TXP finds the tag <txp:article /> in a page, it will replace this tag by the contents of the selected form – the previous one, by default – and then, each form tag will be replaced by it corresponding value for the given article(s).

* * *

Attributes · 27.03.04

Many of the TXP tags can have attributes, which will be similar to common XHTML attributes on their syntax. Each tag can has its own attributes so, we’ll see them when we describe the tag they can be attached to.

But there are several attributes which can be used with a considerable number of TXP tags, keeping always the same significance. Due to this, and in order to prevent redundancy across this manual, seems logical to describe them together in any place.

This don’t mean that we can use these attributes with all TXP tags, but only with the ones listed after each attribute description.

Common attributes

limit

A lot of TXP tags are intended to show some kinda of lists: lists of links, articles, comments, ..., the limit attribute allow us to specify the maximun number of items to show on one of this TXP lists of things. The value must be a number.

So, for example, we can set the max number of articles to show on your default page by writting: <txp:article limit=”5” />

Tags which can have this attribute are: article, article_custom, linklist, recent_articles, recent_comments and related_articles.

label

Sometimes you need to add some “label” to a TXP element like, for example, a popup, (a popup is the XHTML select which comes, by default, at the right column of the TXP default page, providing your page visitors with a fast way to find and go to any section of your site).

In order to add your custom label to the elements you want, you have only to specify that label as the value for the label attribute for those elements tags. Returning to the sections popup: <txp:popup label=”Browse Site Sections” type=”s” />

wraptag

This attribute offers us the possibility of place our tag contents inside an XHTML tag of our election, without the need of specify this tag enclosing our TXP tag.

Why?, because using this tag, you will asure that if the TXP tag is replaced by nothing, you will not have empty XHTML elements in your resulting document.

Let’s say we want to place our previous example inside a <p></p> tag: <txp:popup label=”Browse Site Sections” type=”s” wraptag=”p” />.

Important: Note that we pass to the wraptag attribute the name of the XHTML tag, without the < & > signs !!!.

break

What about the possibility of specify a tag after each item on a list?. The break attribute comes to the rescue.

Use it to say TXP what tag it must place after each list item.

Ok, let’s assume you’re a standards advocate who want to write semantical XHTML list for your links. The must question: How can I use wraptag and break combined to buil them?.

Fortunately, Dean thinked it before us. Add to your list tag the attributes break=”li” wraptag=”ul” and, with a kind of TXP magic, your lists are done!.

Feedback

* * *

Article Navigation Tags · 28.03.04

Navigating single articles

TXP provides us two groups of tags to display links to the previous and next article to the current one.

You can create a link to the next article using the container tag <txp:link_to_next></txp:link_to_next> and placing the text you want to show for the link inside, for example, “Next article”; (original, eh?).

If you want to show the next article title on this link, you can place inside the previous tag <txp:next_title />.
This is the default option when you use the TXP TAG BUILDER ASSISTANT, click on the “Link to the next article” link and, then click on the “Build Tag” submit button.

At the same way, you can combine <txp:link_to_prev></txp:link_to_prev> and <txp:prev_title /> to build your custom links to previous articles.

Navigating multiple articles pages

If you want to provide this kinda of navigation links for pages where multiple articles are listed, you must use the tags <txp:newer></txp:newer> for pages which are sorted after the current one, and <txp:older></txp:older> for those ones that are place previously, in agreement to the article sorting criteria.

Pages of multiple articles are section and category pages and, of course, your main page.

So, if we have tags intended to be used only with single articles, and the equivalent ones for multiple pages, how can we use them on the same template?.

Conditionals tags to the rescue. Let’s have a look to the next example:


Paginating articles and pages



<txp:if_individual_article>
<p><txp:link_to_prev><txp:prev_title /></txp:link_to_prev> |
<txp:link_to_next><txp:next_title /></txp:link_to_next></p>
</txp:if_individual_article>

<txp:if_article_list>
<p><txp:older>Prev Page</txp:older> |
<txp:newer>Next Page</txp:newer></p>
</txp:if_article_list>

One consideration about the <txp:newer> and <txp:older> tags. As of γ1.17b, it seems these tags works only if you place them in your template after the <txp:article> tag. But don’t show nothing if you place them previously.

If you want to know more about Conditional tags, check their [future] section on this manual.

* * *

Site Navigation Tags · 28.03.04

Under this epigraph we have some tags which make possible to quickly jump from one web section to another.

The <txp:category_list /> tag

Outputs a list of site categories.
Can takes the common attributes wraptag, label and break.

The <txp:section_list /> tag

Outputs a list of site sections.
Can takes the common attributes wraptag, label and break.
Until γ1.17b this option is not show on the TXP TAGBUILDER ASSISTANT.

Link to your home page.

You can use the tag <txp:link_to_home>Home</txp:link_to_home> to place a link to your home page enywhere on your pages. Of course, you can replace “Home” with the text or XHTML you want to show inside the link; for example, an image with your site logo, or the <txp:sitename /> tag, which will be replaced for your site name as it was set on “Admin>Preferences”.

This tag allow us to display a XHTML select, offering our site users the possibility to quickly jump to a section or category specific page. Appart of the common attributes label and wraptag, this tag takes the attribute type which can has one of the values “c” or “s”, in function of we want to show a select of site categories, or another one of site sections.

The <txp:recent_articles /> tag

As it name indicates, this tags allow us to show a list of recent articles, with some attributes which allow customization.
Apart of the common attributes label, limit, break and wraptag, this tag can also takes the attributes category, sortby and sortdir with exactly the same significance they take for the <txp:article_custom /> tag.

The <txp:recent_comments /> tag

A tag to list your site recent comments.
This tag can takes as attributes the 4 described on the common attributes section.

A tag to list articles related to the current one, it’s to say, articles belonging to one of our current article categories.
This tag can also takes as attributes the 4 described on the common attributes section.

The <txp:search_input /> tag

This tag offer us a fast way to place a Search Button anywhere on our page. It can also take the common attributes label and wraptag, and two special new ones:

Observations?

* * *

Miscellaneous tags · 28.03.04

The <txp:css /> tag

This tag is intended to be used on the head section of our XHTML template, and it will load the css pointed by the attribute n, which must be the name of one of our CSS. If this attribute is not suplied, the default CSS selected for the current section will be used. (The CSS called “default” is used on front page).

So, the n=”“ option in the css tag builder is only useful if you want to override the stylesheet assigned to a section, or if you want to use more than one stylesheet on your page.

The <txp:email /> tag

This tags will show a common email XTHML link, but replacing all your email characters by their hexadecimal equivalents, in order to prevent spam. The attributes we can assign to this tag are:

Logically, the mission of this tag is to show a list of your links. Besides the common attributes limit, wraptag and break, it can takes also the next ones:

The <txp:sitename /> tag

Put this tag in your document on the place you want to show your Site Name as configured on “Admin>Preferences”.

The <txp:page_title /> tag

This tag will be replaced by your site name, followed by the current article title, if we’re in a single article page. You can select what character(s) will be placed between the one and the other throught the attribute separator.

This tag will output also different titles in function of the page type we’re on:

The <txp:output_form /> tag:

The textpattern include mode.

Suppose you have a static page fragment you want to include in more than one of your pages. This fragment can change with the time, and you want all these changes be reflected on all your pages at once.

With output_form you can write that page fragment in a TXP form, and then, place it inside your page templates. Thit fragment will be included in all those pages, in the place you put this tag.

Can takes the attribute form, which indicates the form to display.

The tag can be used recursively, it’s to say, you can place this tag inside another form, and then put a the same tag pointing to the new form in another one, and so on…

Specially recommended for page headers, footers, navigation bars and almost any component repeated on your templates.

The <txp:password_protect /> tag

You can use this tag to protect some pages of your site – with HTTP_AUTH – in order to make them visibles only for people who know the required username and password. These are specified to the tag using the attributes login with the required username as value and pass, which is, of course, the password.

The <txp:site_slogan /> tag

Put this tag in your document on the place you want to show your Site Slogan as configured on “Admin>Preferences”.

Observations? [2]

* * *

Feed Tags · 11.04.04

TXP allow us to provide quick links to our XML feeds, both for articles and links.

We can use this tag to create links to an XML feed of our articles. This feed can be both RSS and Atom.

Among the common attributes label, wraptag and limit, this tag can also take the following ones:

With this tag we can create a link to the XML feed for our links.

Among the common attributes label, wraptag and limit, this tag can also take the following ones:

Comment

* * *

Article Related Tags · 6.06.04

The <txp:article /> tag

Being probably the most important of all TXP tags, the <txp:article /> tag is a single page column tag – due to it will appear on page templates – which will be replaced by one or more articles, depending on the context it is being processed.

If TXP detects we’re requesting a determinated article, it will show that article. Otherwise, it will show a list of articles.

Can take one or more of the following attributes:

The <txp:article_custom /> tag

This is very similar to <txp:article />, and is intended to be used when a high degree of customization is required to show one or more articles. For this reason, it can take a lot of attributes:

Comment

* * *

Image Tags · 8.06.04

You can easily build your photo galleries using textpattern, even though image tags are not in TEXTPATTERN TAG BUILDER yet.

Next instructions are stolen directly from Textpattern Forum (thanks Dean):

First, you must upload fullsize images and corresponding thumbnails, and make sure each is in a specific category (keep the image category names simple: without spaces if possible, ‘newyear_2004’ for example).

To make an image gallery page:

  1. Create a new Page called something like ‘photo_page’
  2. Create a new section called something like ‘photo’, and tell it to use ‘photo_page’.
  3. In photo_page, put the tag <txp:image_index /> wherever you want the index to appear: a good idea would be to use a <div> and CSS to govern the space available for the index, and how the <img /> tags should be positioned.
  4. Wherever you want the fullsize image to appear on the page, put a <txp:image_display /> tag.

Then to call the gallery page (provided it is in the section ‘photo’), use:

your-txp-site.com/photo/?c=IMAGECATEGORY

At the same forum post you can find also 2 easy to use templates.

Now, a small description of these two tags:

The <txp:image_index /> tag

This tag will output a list containing all the thumbnails for a given category of images in our TXP installation. Of course, our images need to have a thumbnail, in order to display them on this index.

You can specify the attribute c to this tag in order to specify a default category for the images you want to display. If you don’t specify it, you need to pass to your image pages, at the end of the url, ?c=IMAGECATEGORY, where IMAGECATEGORY is the category of the images you want to show.

The <txp:image_display /> tag

Once we’ve created our image index, we can place this tag anywhere on the page, to show the image pointed by the thumbnails.

The <txp:thumbnail /> tag

[Avaliable since γ1.19]

Whith this tag we can output one of the thumbnails on our TXP image section anywhere in our pages. Of course, that thumbnails must exists in order to be displayed.

This tag can takes the next attributes:

Note that if both name and id attributes are present at once, the name value will override the id one.

Comment [2]

* * *

Displayed Comments · 28.03.04

At the same way we can select different forms to show our articles, we can choose the aspect of our comments, but with one restriction: there is a form called comments, and this is the form used to display our users comments.

Tags allowed to be placed on a comment display form are:

Comments about comments?

* * *

Comment Form · 28.03.04

Under this epigraph we’re going to see all the tags which we can use to customize the look of the form we present to our users to write their opinions about our articles.

These tags are:

To add custom text before each one of these inputs, we can use the TXP general purpose tag <txp:text />, which will be replaced by the value you specify it on the attribute item.

Textile is also allowed in comments. No XHTML is allowed for security reasons.

Comment

* * *

Links · 3.04.04

When you want to list your links – using the <txp:linklist /> page column tag – you can choose what form TXP must use to display them. These links forms can contain any of the next tags.

Comment

* * *

Search results · 3.04.04

The next group of tags will be used by TXP to display your site search results if you create a form called search_results and place them inside. (If this form doesn’t exists, TXP will use a default format to display search results). Tags allowed in a search_results form – all referred to articles which match the search criteria – are:

Comment

* * *

Images · 11.04.04

The <txp:image /> tag

Using this tag, you can display the image you want, using the id attribute.

We can easily obtain the id attribute value for anyone of the images we’ve uploaded througt TXP: go to the “Write>Images” section, click on the textpattern link correspondent to your image, and you’ll obtain a nice <txp:image /> tag with the correct id attribute.

Once we’ve got our tag, we can customize it with any of the following attributes:

Comment

* * *

Article Form Tags · 8.06.04

The next group of tags involves all tags which can appear inside an article form, determining the article parts that will be shown on our page, in function of the form we’re choosed to use for that article.

Comment [1]

* * *

Conditional tags · 12.04.04

TXP conditional tags are special tags intended to be used when we want to display the results of a template fragment only when a given condition is true.

This tags are:

All of them are container tags so, the fragment we want to display only when the given condition is true, must be placed inside one of these tags.

You can see an example of if_individual_article and if_article_list on the Article Navigation Tags of this manual.

About the if_comments tag, since the logic behind this tag is that, when used on an article form, everything inside this tag will only appear if commenting for the article is open, or was open in the past; you can use it to add to your articles forms comment related things.

Comment

* * *

Error Notices · 12.04.04

The <txp:notice /> tag

This tag is intended to be used by plugins developers when they need to send to the users an error message, without break TXP internal “mechanism”.

The error message needs to be specified as the value of the message attribute.

For example, if you misuse an image tag, you’ll obtain a notice saying “malformed image tag” notifying you that something is wrong with the tag. This message is the resulting output of: <txp:notice message=”malformed image tag” />

Comment

* * *

Textpattern Tag Manual Changelog · 8.06.04

June, 08 2004.

June, 06 2004.

April, 12 2004.

April, 11 2004.

To Do list:

Anything more which you want to see on this manual? [2]

* * *

Textpattern 1.0RC3 · 20.02.05

As you probably know, the third release candidate of Texpattern 1.0 is out. You should know that I’ve been on the development progress for this TXP release too and, of course, that I haven’t updated the Tag Manual since May.

Jeff Soo has sent my a nice revision of the manual made by an english speaker person – which was, of course needed: to admit your limitations is the first step to solve them – and I have to properly update the existing texts, add more examples and the new tags.

Johanes Gamper is currently translating the manual to German; Hideo Joho to Japanish and TTX – my work partner – is helping me on the spanish translation.

Main idea is to collaborate with the full manual to Textpattern Book but – AIM talks are very amusing sometimes – I’ve said Dean that I jib to write on a wiki instead of use TXP to document TXP!. He is, more or less, persuaded, once wikis are now one of the favourites spammers places. Other option is to use Hieraki, this rails app really rocks, and is focused on books, so… .

* * *