<txp:custom_field /> single tag, 3 attributes

custom_field

The basic custom_field tag is a single tag and used to display the contents of a custom field.

Custom fields are useful if you publish content that has a consistent structure. They are defined in the Advanced Preferences tab, under the Custom Fields heading. You may have up to and including 10 fields. With a default Textpattern installation, you will just see two custom fields with the names “custom1” and “custom2”, which you may rename or remove.

The contents of custom fields are limited to 255 characters in length.

Custom field names may include letters (uppercase or lowercase), numbers and under_scores, but no spaces or other special characters.

There are certain names reserved by Textpattern, which should not be used to name custom fields:

  • thisid
  • posted
  • annotate
  • comments_invite / comments_count
  • authorid
  • title / url_title
  • category / category1 / category2
  • section
  • keywords
  • article_image
  • body / excerpt
  • status
  • sort / offset / limit / form, or any other tag attribute, just in case

A symptom of a name clash is when you go to check or display the contents of a custom field and receive unexpected (or no) output. Check your names aren’t already used by Textpattern in the first instance as it might save you a headache.

To remove a custom field, simply clear its name. Don’t forget to save your changes.

Once defined, you may set values for your custom fields for each post (under “advanced options” in the Write tab), and may display custom field information in any article form.

Custom fields can save a lot of work, and to make them even more useful there is the if_custom_field conditional tag to complement them. More explanation and examples on that page.

Related: if_custom_field

attributes

name="unset"
  • Display specified custom field.
default="unset"
  • Default value to use when field is empty.
escape="html"
  • Escape HTML entities prior to echoing the field contents.
  • Values: html or unset

genealogy

Version 4.0.7

  • default value for attribute escape changed from unset to html
category: article
<txp:custom_field /> 3 examples

Book Reviews

You might, for example, publish book reviews for which you add the author, the title of the book, the publishing company and the year of publication.

With:
a custom field named “Book_Author” containing J.R.R. Tolkien
a custom field named “Book_Title” containing The Lord of the Rings
a custom field named “Book_Publisher” containing HarperCollins
a custom field named “Book_Year” containing 2004

and an article form like the following:

<p><txp:custom_field name="Book_Author" />: <txp:custom_field name="Book_Title" /><br />
	Published by <txp:custom_field name="Book_Publisher" /> in <txp:custom_field name="Book_Year" />.</p>

(X)HTML returned would be:

<p>J.R.R. Tolkien: The Lord of the Rings<br />
	Published by HarperCollins in 2004.</p>

Power A Linklog

This works well with variation of Sencer’s Txp bookmarklet.

With an article title of Textpattern, an excerpt of Textpattern is awesome., a custom field named “Link” containing http://textpattern.com/, and an article form like the following:

<div class="linklog-entry">
	<div style="float: left;"><a href="<txp:custom_field name="Link" />"><txp:title /></a></div>
	<div style="float: right;"><txp:posted format="%d %d %Y" /></div><br>
	<txp:excerpt />
</div>

(X)HTML returned would be: 

<div class="linklog-entry">
	<div style="float: left;"><a href="http://textpattern.com/">Textpattern</a></div>
	<div style="float: right;"><txp:posted format="08 Aug 2005" /></div>
	<p>Textpattern is awesome.</p>
</div>

Other tags used: title, posted, excerpt

Unescaping (X)HTML output

With a custom field named “foo” containing: 

<a href="../here/">

using the following: 

<txp:custom_field name="foo" />

will return this hunk of (X)HTML: 

<a href=&#34;../here/&#34;>

whereas using: 

<txp:custom_field name="foo" escape="" />

will render the URL as you’d expect, exactly as written in the custom field itself. Thus, it will be rendered as a link by the browser.

category: article