Textpattern : Articles

Textpattern logo

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 normally 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

Go to Content, then Write. In the centre column, you’ll see a blank article, which contains three boxes that you can fill in:

  • Title
  • Body
  • Excerpt
Textpattern blank article screen

Click Advanced Options in the left–hand column, and you will see some more boxes:

  • Up to 10 custom fields, each of which may contain a piece of text. This feature is useful if 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 for their phone numbers. You can name each of the custom fields by going to Admin then Preferences: Textpattern custom fields screen
  • An image field. To specify that a particular image should appear with a particular article, upload an image, note its ID number, and fill in the ID number in the 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 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)
  • 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 on 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 called ‘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:

  1. Go to Presentation, then Forms.
  2. Click Create new form.
  3. Give the form a name.
  4. From the drop–down Type list, select article.
  5. Click Save New.Textpattern form save screen

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 the two main parts of a Textpattern article: the title, as a second–level heading, followed by the body text. Your Textpattern article form would contain this code:
<h2><txp:title /></h2>
<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 followed by the body text, you would use this code:
<txp:custom_field name="phone_number" />
<txp:body />

You get the general idea. The Textbook 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 page.

In the above examples, the title tag was used as a heading, but it does not need to be. You can place it within any HTML tag and use it anywhere on a page.

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.

Other Text and HTML Within an Article Form

You can include all sorts of other things within a Textpattern article form. As with a Textpattern miscellaneous form, you can include as much text and HTML as you want. You can even include a miscellaneous form within an article form.The only requirement is that if a form includes any part of a Textpattern article, it has to be classified as an article form. Otherwise it won’t work.

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:
    <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:
    <h2><txp:title /></h2>
    <txp:body />

The Wrong Method

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

directly into a Textpattern page won’t work. (Well, actually it will work sometimes, but we’ll deal with that in the next tutorial.)

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>
  <h2><txp:title /></h2>
  <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 in single instances. Most of the time, however, you will find that using a form, like using a CSS stylesheet, is more efficient.

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.

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:
http://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.

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.]