Thoughts on branding, design, writing and life by Kevin Potts. Established 2003.

The Power of Custom Fields in TXP

Textpattern’s custom fields have a lot of power behind them, and combing them with conditional statements can bring incredible flexibility to the most complex TXP installs.

Now that Textpattern has reached a stable, usable, well-tested version, I have been deploying it on more client sites than ever. Oddly enough, these sites have all been of the straight content variety—no blogs.

Travel With Your Kids is my most recent project gone live, and features my most complex TXP install yet, with nested categories and sections, customized ad positioning for every page, plus heavy use of custom fields.

Earlier versions of the software used to bury custom fields outside the backend GUI, but version 4 brought them into the admin user interface, making them an easy way of extending the CMS’s capabilities. TWYK utilizes custom fields in three important ways:

  • Content fields
  • Controlling the order of displayed articles
  • Template triggers

Content Fields

I imagine that custom fields were originally designed by Dean and company as a means of extending the number of content inputs, and they work beautifully doing so. Two custom fields for meta information have their content displayed with each article.

   <txp:if_custom_field name="meta_title">
      <txp:custom_field name="meta_title" />
   <txp:else />
      <txp:section title="1" />: <txp:title />

There is a custom field for the article title because the client requested this be manually controlled in case the title of the page should be different from the title of the article. (It’s an SEO thing.) The conditional script checks to see if the custom field “meta_title” is populated. If it is, we publish the contents; if not, we fall back to the section name followed by the default article title.

<meta name="description"
content="<txp:custom_field name="meta_desc" />" />

The custom field “meta_desc” is always populated (unlike “meta_title”), so we don’t have to use a if_custom_field tag to check for content.

<meta name="keywords" content="<txp:keywords />" />

Finally, the keywords meta, which pulls its data right from the “keywords” field in the article admin area. In my previous article about meta in Textpattern, I advocated using a custom field for the keywords, but since then the development team has allowed the default keywords field to be output.

Using custom fields for extra content is a no-brainer; graphicPUSH uses six for miscellaneous content stuff beyond meta output. In my book reviews, there is a custom field for each of the “book information” entries.

Using Custom Fields to Order Articles

When creating a non-blog CMS, the date of creation for the articles is mostly irrelevant, so it’s not logical to order articles from when they were posted. At the same time, sorting alphabetically doesn’t make much sense either.

Thankfully, Textpattern gives us a host of sorting options in the article tag, including the capability to sort by custom fields. For Travel With Your Kids, a category like Hong Kong needed to have the order of the articles tightly controlled. So I created a custom field called “custom_3,” and within the template, placed this:

   <txp:article limit="999" sortby="custom_3" 
      sortdir="asc" form="listlink" />

Inside each article, “custom_3” has a number entered, like 05, 07, 21 or 98 or whatever. These numbers represent the order of appearance of the articles when output in the list, so “01” would be first. (You could also use letters, like A-B-C, but that seems less intuitive.) If you decide to use this technique, here are two important tips:

  1. The custom field must have a default name like “custom_3” or “custom_7.” TXP/MySQL does not recognize custom field names beyond this, so you can’t call your custom field “pageorder” or something. I guess this is a bug. If Microsoft wrote this software, it would probably be called a “security feature.”
  2. You have to number your articles alphabetically, like file names on your OS. If you count from 1 to 12, your articles will go in this order: 1,10,11,12,2,3,4,5,6,7,8,9. To circumvent this, add a zero before single digit integers, like 01,02,03,04, etc.

Using Custom Fields as Template Triggers

This is where the real power comes in. The Textpattern wiki entry for if_custom_field hints at the capabilities with the last example, but TWYK needed some more advanced template switching. Let me explain.

Each section has its own page in Textpattern. So the “Destinations” section runs off a page called “destinations,” the “Before You Go” has a page called “beforeyougo,” etc. Each of these pages must display three things: the section landing page (/destinations), the category landing page (/destinations/?c=Grand-Canyon) and finally individual article pages (/destinations/grand-canyon-where-to-stay). Here is the code:

   <txp:article form="article_sticky_category"
       status="sticky" />
   <txp:article form="singlecategorypage" />
<txp:else />
   <txp:if_section name="destinations">
      <txp:article form="article_sticky_section"
         status="sticky" sortdir="asc" limit="1" />
   <txp:article form="article_full" />

Here is the logic for the first three lines: If it’s a category landing page, show either the “sticky” article of the category if the category has multiple articles, or show the single “live” article in that category if that category has only one article. (A multi-article category will always have a “sticky” article to serve as a landing page, and a category with only one article will never have a “sticky” article because the single article will serve as the landing page. Whew.)

An example of a multi-article category: The Grand Canyon.
An example of a single-article category: Genova.

The trick is that a category with only a single article must have its page look like any full article in any other section, not like a “sticky” article landing page, so we need a means of telling Textpattern when a category only has one article. How? Custom fields.

I created a custom field called “singlepage.” For most articles, it is blank so it triggers nothing. For the Genova article, I entered “yes” in the field. You’ll notice there is a article form called “singlecategorypage.” Here is what that form looks like:

<txp:if_custom_field name="singlepage" val="yes"> 
<txp:body />
.... other stuff ....

This article form is going to be completely ignored 99.9% of the time because almost no articles have “yes” placed in the custom field “singlepage.” However, for those that do, it essentially tells TXP that there is no “sticky” article for the category and there are no further articles within that category.

Beyond This Article

I am sure there are uses for custom fields beyond the scope of this article, but these are just three uses for one project. While TXP allows for a lot of customization and flexibility, custom fields take that power and double it. By using them as template triggers or even simple content fields, it makes TXP all the more suited for professional deployment.

, ,

commentary + criticism

The Co-Worker

wrote the following on Thursday March 23, 2006

This is a perfect example of why you are much smarter than me.

Natalie Jost

wrote the following on Thursday March 23, 2006

Wow. I used them for my books, but never thought of these uses! Thanks for the real-world example too. It’s much easier to see it live.

One thing… your example links to Grand Canyon and Genova don’t go to the right place. :)

I’m curious, do you know of a way to get more than the 10 custom fields? I can imagine with a big site you could end up using them all.

Chris Johnson

wrote the following on Thursday March 23, 2006

I love the ability to use Textpattern for so much more than just a blog. Using forms and custom fields you can control so much more than you would normally think of from a “blogging” CMS.

@Natalie: I remember seeing somewhere a plugin / modification for Textpattern to allow more than 10 custom fields. Don’t have a link, but I think a Google search might get you there.


wrote the following on Thursday March 23, 2006

Natalie—links are fixed. I always find the real-world example to be easier to digest, so I tried to pull the code from a real live client. (With his permission of course.)


wrote the following on Monday March 27, 2006

cool article.
thank you for helpful information about TXP—especially for order fields and template triggers

Travis Schmeisser

wrote the following on Monday March 27, 2006

Wow this is incredibly helpful! I agree with Natalie – the real world examples blow away any snippets of example code anyone can use.

My company uses TXP as a CMS as well and I’m interested in how you handle sub-pages.

Right now we use stw_category_tree to output a category list starting with a parent category that is the same name of a section. This way the plugin generates all the here states and subpages for us. The problem is with ordering we have to name categories “01-Category-Name”, etc.

Do you have any other methods you can suggest? I notice your sub pages don’t highlight and show a “here” state – are your subpages hardcoded?


wrote the following on Tuesday March 28, 2006

My technique is probably not as efficient and glamorous as yours, but here goes …

The main section links are hard-coded and the category listing beneath the active section is generated via cbs_category_list which is a great little plugin that generates a list of categories relevant only to the active section. Because of this somewhat ghetto technique, there is no “active” state.

I know there are several plugins out there designed for generating navigation structures, I just have not had the time to test them and Christophe’s plugin works perfectly every time.

stw_category_tree does look interesting … reading the description now. Perhaps I can work this into a future project. I am working on a very large TXP site now … will report on this later if any interesting techniques bubble to the surface.

Travis Schmeisser

wrote the following on Wednesday March 29, 2006

Thanks it always helps to see how other people are pulling things off.

I’ve checked out the cbs_category_list one it’s nice. The main difference that I use between the two is stw_category_tree gives you here states and allows showing of child categories which comes in handy – maybe for your “very large” site. May save you some hardcoding. Good luck!

Sjarief Hilmy

wrote the following on Saturday April 15, 2006

Nice article, however I have some difficulty in implement it to my site.

I cannot display custom field contents directly on pages template. I need to use txp:article tag to call a form that display the custom field contents. Do you also need a txp:article to display the meta_title and meta_description?


wrote the following on Monday April 17, 2006

Sjarief - You have to run custom field output through txp:article since the custom fields are associated with specific articles.

Sjarief Hilmy

wrote the following on Tuesday May 2, 2006

Sorry for late response, but do that mean that you have to call txp:article twice?

I’ve tried this but I have to disable automatic append comment to articles, since it generate comment form twice. So now I cannot accept comments unless I use popup.

But I see that your site still can receive comments. I wonder how did you do that.

Bob Digital

wrote the following on Friday June 2, 2006

Anyone here know how I can have more than 10 custom fields? My Googling has turned up nothing so far…


wrote the following on Tuesday June 20, 2006

Mr. Bob Digital — Try the Packed Custom Fields plug-in for really stretching custom field capability. I currently use it on Sacred Dub for storing tons of info about each album release.

Steve Dickinson

wrote the following on Sunday June 25, 2006

To all who are looking to extend the TXP custom field limit beyond the magic 10, here is an article about how to do it.

But that means hacking your TXP installation. That’s one thing about the Packed Custom Fields plugin, you don’t have to hack to get more than 10 places to store stuff.

thanks for the pointer to my packed custom fields plugin :O)

3dsl Eugen

wrote the following on Saturday December 2, 2006

hey, its so simply :) perfect!

Luke Rumley

wrote the following on Thursday June 21, 2007

Great tips – I am learning a ton here. You may have already known this when talking about sorting display order by custom field, but I immediately tried to create one called &quot;sequence_id&quot; and it failed to sort.

I then read your disclaimer about naming, and changed only my article tag to sortby=&quot;custom_2&quot; because sequence_id happened to be my second custom field. It worked!

Sounds like a bug to me, but I like the fact that I can tell the user, &quot;This field called sequence_id will control the display of your articles…&quot; instead of &quot;This field called custom_2…&quot;

Thanks again!