Understanding Textpattern CMS tag

admin-ajax

In Textpattern CMS, articles typically comprise of an article title, some article body text and sometimes an article excerpt, perhaps to summarize or provide a call to action. Each of these components is stored as text fields in the Textpattern CMS database and can be outputted to the browser using Textpattern-specific tags in your theme code. While a typical Textpattern CMS instance typically follows this title + body approach, it’s possible—and pretty straightforward—to have additional information stored in each article, outside of the bounds of the title, body and excerpt.

Every article has custom fields associated with it, but they are entirely optional. These are available to anyone who has the rights to write or edit articles, but are blank (empty) in the database. The upshot of this is that Textpattern databases aren’t bloated from unused data. Bluntly, if you never use custom fields you’re not going to have any additional administrative burden; the fields will lay dormant in your database until the time comes that you decide you want or need to use them. You don’t need to know how custom fields work, but they’re very handy when you start using Textpattern to construct more complex websites.

Each article, new and existing, has ten (10) custom fields available. It’s possible to extend this further with some code finagling, but for most websites ten custom fields are sufficient. These fields have a name and a text field in which to store text. The field name is typically used to describe what the custom field does or relates to, or can simply be a generic identifier. All of the following are valid names for custom fields:

  • co-author
  • location
  • notes
  • custom_field_number_1_of_10
  • foo123bar456baz789
  • pete-cooper-is-my-textpattern-wingman

The names for the fields are set via the Textpattern admin-side at Admin → Preferences → Advanced → Custom Fields. When it leaves the factory, Textpattern ships with two of the ten fields named: `custom1` and `custom2`. The remaining eight custom field names are intentionally left blank. When a custom field has a name, it will be available in the Write tab when an article is authored or edited. Conversely, if a custom field does not have a name it will not be shown. Depending on the theme used in the admin-side of Textpattern, the custom fields will either be immediately apparent or be available from a clickable/tappable link. Typically, click or tap the Content tab, then Write, then locate Custom Fields from the left sidebar.

When a custom field has a name, it can be used with the `<txp:custom_field>` tag, regardless of whether the custom field in the article(s) queried has content or not. Take the following example:

<txp:custom_field name="co-author" />

In the example above, the code will display (output) the contents of the custom field named `co-author`. If the field name is set correctly in the admin preferences and the content is empty, nothing will be shown, nor will any errors be thrown. For this example, the `co-author` field could be used if an article is was co-written by an additional author and some method of attribution is appropriate; as it stands, Textpattern records one (1) author name for each article, and populating this field with one of more additional names would be a smart way to do it.

Extending the example to the following would give the tag some context:

<p>This article was written by <txp:author />, with additional support from <txp:custom_field name="co-author" />.</p>

This will display the article author, and then display the contents of the `co-author` field after it. The above code could be baked into an article form, but will fall flat if the `co-author` field is empty; remember that `<txp:custom_field>` will output nothing if the field has no content. Applying some logic to this, it would make more sense to automatically check if a field has content, and then do stuff depending on the results of that check. Like this:

<txp:variable name="co-author-check" content='<txp:custom_field name="co-author" />' />
<txp:if_variable name="co-author-check" content=""><txp:else />
<p>This article was written by <txp:author />, with additional support from <txp:custom_field name="co-author" />.</p>
</txp:if_variable>

This is a big step up, so I’ll explain what’s happening above. In line #1, a Textpattern variable is set up with the name `co-author-check`, and the value stored is the results of the `<txp:custom_field name=”co-author” />` tag. This means that if the `co-author` field is set (i.e., there is one or more co-author listed), then the variable will have a value. Otherwise, if the field is blank, the variable will still be set up, but not have a value. Line #2 checks to see if the `co-author-check` variable value is empty. On the basis that the variable was set up in the previous line, it will be empty or not. If it’s blank, nothing will happen. If it’s not empty, the text on line #3 is outputted. Line #4 closes the variable checking tag.

This is now suitable for use in an individual article form, and Textpattern will automatically perform a check on the custom field as the article is rendered to the browser. This is an example of how that might work:

<txp:title />
<txp:variable name="co-author-check" content='<txp:custom_field name="co-author" />' />
<txp:if_variable name="co-author-check" content=""><txp:else />
<p>This article was written by <txp:author />, with additional support from <txp:custom_field name="co-author" />.</p>
</txp:if_variable>
<txp:body />

In this instance, the title will be outputted, then the co-author attribution check happens, then the article body is published.

There are two additional attributes that can be used with `<txp:custom field>`: `default` and `escape`. The `default` attribute is used to substitute a custom field value if it’s not set. Using a previous example, a somewhat snarky example follows:

<p>This article was written by <txp:author />, with additional support from <txp:custom_field default=”absolutely nobody else” name=”co-author” />.</p>

If the `co-author` field is blank, then the text ‘absolutely nobody else’ will be used in place of the co-author.

If the custom field contains HTML (e.g., a hyperlink or some example code), the text field contents will be escaped by default; that is, the code itself will be output as plain text. If custom fields are to contain HTML, the escaping needs to be disabled. To do this, use the `escape` attribute to turn off escaping. In this example, the `co-author` field may link to the co-author’s website or profile:

<txp:title />
<txp:variable name="co-author-check" content='<txp:custom_field name="co-author" />' />
<txp:if_variable name="co-author-check" content=""><txp:else />
<p>This article was written by <txp:author />, with additional support from <txp:custom_field escape="" name="co-author" />.</p>
</txp:if_variable>
<txp:body />

Note the `escape=””` on line #4. If the field value contains HTML, it will no longer be escaped; if the field value does not contain HTML code it will be outputted as normal.

While you’re getting to grips with tags and their constructs, I recommend you stick to variables and the long-form approach rather than squeezing as much as you can into one line. There’s plenty of opportunity to show off as your knowledge and awareness increases, and I trust you’ll come along to the Textpattern support forum (http://forum.textpattern.com) to show us what you can do.

Next time: `<txp:category1>` and `<txp:category2>`. See you then.

Looking for quality Textpattern Hosting? Look no further than Arvixe Web Hosting and use coupon TEXTPATTERN for 20% off your first invoice!

Tags: , , , , , , , | Posted under Textpattern | RSS 2.0

Author Spotlight

Pete Cooper

Pete Cooper has been using Textpattern since 2005. Textpattern is his preferred CMS weapon of choice. Its logical and flexible approach to content management makes Pete happy, as does its lightweight core and helpful user community. Pete's website - petecooper.org - runs on top of Textpattern and chronicles his day-to-day experiences from his home near the Atlantic in north Cornwall, United Kingdom.

Leave a Reply

Your email address will not be published. Required fields are marked *