Skip to content
Textpattern

Making use of Textpattern's yield tag

4 min read

Since Textpattern 4.2.0 there's been this slightly mysterious yield tag added to the menagerie of Textpattern tags. Its use and value seems to confuse a lot of people, and until recently I'd have included myself amongst them; but I've been converted — it is a truely useful tag.

Basically it works in unison with the output_form tag: you place a <txp:yield > in a form and then whenever you use that form the contents wrapped in the output_form tag gets placed where the yield tag was. I'll give some examples of this in a moment, but essentially the value of this is that you can use forms as flexible building blocks. Each building block has a common structure, but individualised content.

So let's take a look at a couple of example applications of the yield tag…

Block content

To help style my pages I find it useful to wrap up a block of content in a div tag. For example, each block of content in the side bar of this site gets wrapped as <div class="block">some content here</div>. This seems like a useful thing to package up as a common form in my site's template, so I create a "block" form:-

<div class="block"><txp:yield ></div>

The <txp:yield /> tag is going to get replaced by whatever content I wish to place in my block when I call the form. Let's say I want a block of the most recent articles; all I need to do in my page template is use output_form in the following way:-

<txp:output_form form="block">
    <txp:recent_articles break="li" label="Recent Articles" labeltag="h2" limit="5" sort="Posted desc" wraptag="ul" >
</txp:output_form>

Flexible <head> form

What about the content of the HTML document's <head> tag? A site more than likely has a common header markup across the entire site with just the occassional additional bit of customisation for a particular section, like some additional stylesheets or some JavaScript.

We'll create a "head" form for this containing all the common head tags for the site, and a yield tag for all the extras:-

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title><txp:page_title /></title>
  <link rel="home" href="<txp:site_url />" />
  <txp:feed_link flavor="atom" format="link" label="Atom" />
  <txp:feed_link flavor="rss" format="link" label="RSS" />
  <txp:css format="link" />
  <txp:yield />
</head>

Now we can just add the head form to the top of each of the templates in the usual manner:-

<txp:output_form form="head" >

Then for templates that need that little bit extra in the header we replace the above with a wrapped version. For example, let's include some additional CSS:-

<txp:output_form form="head">
    <txp:css format="link" n="extra" >
</txp:output_form>

When the output_form tag is used as a self closing tag the yield tag just gets ignored. This is perhaps the real beauty of this tag, it allows common bits of code held within a form template to be just tweaked a bit when it's required, but can be used untouched in all the other cases.

Final words

The yield tag is one of those things that seems utterly pointless when you first discover it, but when you do come across a useful application for it in a site you start to wonder how you managed without it.

What uses have others found for this tag?

© 2024 Andy Carter