====== txp:custom_field ======

The ''custom_field'' tag is a Single Tag which is 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" 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 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. They include: thisid, posted, annotate, comments_invite, authorid, title, url_title, category1, category2, section, keywords, article_image, comments_count, body, excerpt. 

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

Once defined, like keywords, 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" type form.

Custom fields can save a lot of thinking and work and to make them even more powerful, there is a set of conditional tags to go with custom fields: the [[txp:if_custom_field]] tag. More explanation and examples on that page. 

Related info: <[[txp:if_custom_field]]>

===== Syntax =====

The syntax is as follows:

<code php><txp:custom_field name="FieldName" /></code>

This tag will be replaced with anything you write into the custom field named "FieldName". 


====== Attributes ======

=====name="fieldname"===== 
Display specified custom field.

=====default="value"===== 
Default value to use when field is empty.

=====escape="html"===== 
Escape HTML entities prior to echoing the field contents.


====== 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 "Author" containing "J.R.R. Tolkien"
  * a custom field named "Title" containing "The Lord of the Rings"
  * a custom field named "Publisher" containing "HarperCollins"
  * a custom field named "Year" containing "2004"

and an article form like the following:

<code php>
<p><txp:custom_field name="Author" />: <txp:custom_field name="Title" /><br />
	Published by <txp:custom_field name="Publisher" /> in <txp:custom_field name="Year" />.</p>
</code>

(X)HTML returned would be:

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

=====Power A Linklog =====

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:

<code php>
<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>
</code>

(X)HTML returned would be:

<code php>
<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>
</code>

Other tags used: <[[txp:posted /]]>, <[[txp:title /]]>

=====Escaping (X)HTML output =====

With a custom field named "foo" containing:

<code php>&lt;a href="../here/"&gt;</code>

using the following:

<code php>
<txp:custom_field name="foo" escape="html" />
</code>

(X)HTML returned would be:

<code php>&amp;#60;a href=&amp;#34;../here/&amp;#34;&amp;#62;</code>