Textpattern : Articles

One of the main purposes of a content management system is to allow non-technical users to add material to a website.

What the non-technical users actually add material to is a Textpattern article. The Textpattern article is inserted into the Textpattern page by a Textpattern article tag.

The Versatility of a Textpattern Article

A newspaper article typically consists of a headline, some text, and maybe an image.

A Textpattern article, on the other hand, can consist of all of those elements, or more, or fewer.

The system allows you to use different elements of an article in different situations, and in unlimited combinations. This versatility is one of Textpattern’s most useful features.

The Elements of a Textpattern Article

Click on Content, then Write. You’ll see a blank article with three boxes that you can fill in:

Title
Body
Excerpt

As well as these three boxes, the Write screen contains a number of other boxes into which you may place information. Their precise location will vary according to the theme or user interface you are using. In the ‘Classic’ interface, expandable links to these boxes can be found just to the right of the Body and Excerpt boxes:

Two of these features are particularly useful:

Up to 10 custom fields, each of which may contain a piece of text. This feature is useful whenever you have a series of articles, each containing the same types of information that need to be displayed or sorted in the same way. For example, if a company’s website contains an article for each department within the company, it might be convenient to create a custom field to contain each department’s phone number. You can name each of the custom fields by going to Admin then Preferences:
An article image field. To specify that a particular image should appear with a particular article, click on the Images tab, upload an image, note its ID number, and fill in the ID number in the relevant article’s image field.

The Title Field

The only field that must be filled in when creating an article is the title, which is required for reference purposes. Everything else is optional. In practice, an article’s title will normally be used somewhere in the website, but it does not need to be.

The Body and Excerpt Fields

In Textpattern’s default set-up as a blog, the body field was intended to contain the main substance of the article, while the excerpt field contained, as you might have guessed, an excerpt from the article.

Because the body field is larger than the excerpt field, it is a more practical choice for the bulk of the article. But the functions of both fields are essentially equivalent, and they may be used interchangeably.

Textpattern Articles are Versatile

The versatility of a Textpattern article is due to two factors:

When creating a Textpattern article, you may fill in any or all of the many available fields.
Any part of any Textpattern article may be used any number of times, anywhere in the website.

Each field in a Textpattern article is an item in the Textpattern database, and may be used by itself or in combination with any number of other items.

The Textpattern Article Tag

This is the basic Textpattern tag that must be inserted into a Textpattern page wherever the article (or part of an article) is to be displayed:
<txp:article />

This tag means: display all or part of an article here.

It can also be expressed as a container tag, like this:
<txp:article>
</txp:article>

Both types of article tag perform exactly the same function. The container tag, however, is less useful in practice, so we will ignore it for now and deal with it later.

Two More Details

Textpattern also needs to be told two more things:

Which article to display.
Which parts of that article to display.

Textpattern Article Forms

To specify which parts of a Textpattern article are to appear in a particular place in a Textpattern page, we need to use a Textpattern form. You had probably worked this out. It is what we did earlier when placing the website’s footer in a Textpattern form.

The tool for this purpose is not a miscellaneous form, but an article form. One important difference between the two types of form is the need to accommodate the range of extra options that a Textpattern article provides. The article form allows and requires us to specify the parts of the article that are to be used in a particular instance.

Unlike the miscellaneous form tag, which comes in two parts:

<txp:output_form />
(the basic tag) and
form="whatever"
(the specific Textpattern form that is to be used)

the article form comes in three parts:

<txp:article />
the basic tag;
form="whatever"
the specific Textpattern form that is to be used;
and the specific article that is to be displayed.

Specifying the Article

There are several ways to specify which article is to be displayed. For now, we will look at the most straightforward way, which is to specify the ID number that is automatically assigned to the article when it is created. It can be found by clicking the Articles tab, which reveals a list of the articles currently in the database.

If the article’s ID number is 25, this is what we need to add to the tag:
id="25"

So in this example, the full tag would be:
<txp:article id="25" form="whatever" />

The order in which the last two elements appear doesn’t matter, so this would work in exactly the same way:
<txp:article form="whatever" id="25" />

Both of these tags mean: display here the parts of article number 25 that are specified in the form named ‘whatever’.

The final part of the process is to specify which parts of the article are to be displayed. To do this, we first need to create an appropriate form.

Creating a Textpattern Article Form

The only type of Textpattern form that will work with a Textpattern article is an article form. Creating an article form is much the same as creating a miscellaneous form:

Go to Presentation, then Forms.
Click New form.
Give the form a name.
From the drop-down Form type list, select Article.
Click Save.

Specifying the Parts of a Textpattern Article

There are no restrictions on which parts (or combination of parts) of a Textpattern article you can use in a Textpattern article form.

As an example of a very simple Textpattern article form, let’s assume that you just want to display in an HTML page the two main parts of a Textpattern article: the title, as a first-level heading, followed by the body text. Your Textpattern article form would contain this code:
<h1><txp:title /></h1>
<txp:body />

If you wanted to display the title as a third-level heading followed by the text from the excerpt field, you would use this code:
<h3><txp:title /></h3>
<txp:excerpt />

And if you wanted to display the text from a custom field named phone_number within a paragraph, followed by the body text, you would use this code:
<p><txp:custom_field name="phone_number" /></p>
<txp:body />

You get the general idea. The Textpattern website contains a full list of Textpattern tags and their properties. Other tags, not part of the default Textpattern installation, are generated by plug-ins, and work in the same way.

The Title Tag

Placing a Textpattern title tag in a Textpattern page simply instructs Textpattern to insert the contents of the title field into the appropriate HTML page.

In the above examples, the title would be displayed as a heading, but it does not need to be used in that way. You can place a title tag within any pair of HTML tags and use it anywhere in an HTML page, as often as you like.

The Body and Excerpt Tags

You will have noticed that in the above examples, the Textpattern title tag is enclosed within HTML tags while the body and excerpt tags are not. If you like, you may enclose the body and excerpt tags within HTML tags, but in practice you rarely will, because these fields will invariably contain HTML tags, either coded by hand or formatted using Textile.

Articles and Forms Go Together

It is important to remember that there are two parts to using a Textpattern article:

The Textpattern article tag is placed in the Textpattern page, e.g.:
<txp:article form="whatever" id="25" />
and a Textpattern form specifies which part or parts of the article are to be used, and how they are to be displayed. In this example, the form named ‘whatever’ might contain:
<h1><txp:title /></h1>
<txp:body />

The Wrong Method

Placing the individual parts of an article, such as this:
<h1><txp:title /></h1>
<txp:body />

directly into a Textpattern page won’t work. (Well, actually, it will work sometimes, but you will probably never need to use this method, so we’ll put it aside for now.)

An Alternative Method

There is, however, a method that doesn’t require the use of a Textpattern form, although it is rarely used.

Instead of treating the article tag as a self-closing tag, you can use it as a container tag, like this:
<txp:article>
<h1><txp:title /></h1>
<txp:body />
</txp:article>

This type of article tag can be used directly in a Textpattern page without having to use a form. Like inline CSS, you may find it useful occasionally. Most of the time, though, you will find that using a form, like using a CSS stylesheet, is more efficient.

Reminder: Articles Belong to Sections

As well as placing an article inside a page by using a form, it’s also necessary to assign each article to a section. Think of a section as a directory or folder in which you store documents. In this case, the documents are Textpattern articles.

To create a new Textpattern article, click on Content then Write. The section can be selected from a drop-down list:

Each article can belong to only one section. This may seem like a limitation, but is in fact a strength. It is essential to some of Textpattern’s structural functions, not least because it allows each article to possess a unique URL:
https://www.mywebsite.com/section-name/article-name

A section is the main structural unit of a Textpattern website. By using articles and sections together, we can create complex database websites, as we are about to find out.

Next …

Continue with the next article: Textpattern Articles and Sections.

[This tutorial is part 4 of a series intended to introduce the Textpattern content management system to web designers who have no knowledge of PHP or databases.]