Tag Primer

Posted by John W. Long on Thursday, May 11, 2006 | |

So you have this cool new content management system up and running and you are ready to get some real work done. But, uh, how are you going to make it happen? Sooner or latter you are going to have to start learning Radiant’s unique tagging language. I’d like to take a moment to introduce a few of the major tags that you will need for getting work done with Radiant.

Page Attributes

There are a few tags for the basic attributes on each page:

<r:title />      → Tag Primer
<r:breadcrumb /> → Tag Primer
<r:author />     → John
<r:slug />       → tag-primer
<r:url />        → /blog/2006/05/11/tag-primer/

As you would expect the first four tags give you access to the title, breadcrumb, author, and slug for the page. The url tag returns the full URL for the page minus the hostname and protocol.

The Link Tag

The link tag is useful for rendering a link for a page. When used as a single tag it will render the page’s title as a link:

<r:link /> → <a href="/blog/2006/05/11/">Tag Primer</a>

But when used as a double tag it will allow you to specify the link text:

<r:link>Read More...</r:link> →
  <a href="/blog/2006/05/11/">Read More...</a>

You can also specify an anchor on the page that you would like to link to:

<r:link anchor="extended">Read More...</r:link> →
  <a href="/blog/2006/05/11/#extended">Read More...</a>

Or additional attributes:

<r:link id=”special-link” class=”more-link”>Read More…</r:link> →
  <a href="/blog/2006/05/11/" id="special-link" class="more-link">Read More…</a>

The Date Tag

There is also the date tag:

<r:date /> → Thursday, May 11, 2006

Which returns the date that the page was published. The date tag contains an optional format attribute which allows you to specify a format string using the same formatting codes that the strftime function uses in Ruby:

<r:date format="%Y-%d-%m" />            → 2006-05-11
<r:date format="Created on %m-%d-%Y" /> → Created on 05-11-2006
<r:date format="at %I:%M%p" />          → at 08:56AM

The Content Tag

The content tag is the most useful of the tags. It allows you to insert content into a layout or page part from another page part:

<r:content />                → Content from the body part of the page.
<r:content part="sidebar" /> → Content from the sidebar part of the page.

The part attribute (shown above) allows you to specify which part of the page you would like to render. When used without a part attribute the content tag will render the “body” part.

The content part also has another attribute which is extremely useful for layouts. It’s the inherit attribute:

<r:content part="sidebar" inherit="true" />

The inherit attribute causes the page to render it’s parent’s part of the same name if it does not already a part by that name defined. This makes it easy to define a part for most of the pages in a section, but override it for sections that need to be customized. The most common use for this is to create a contextual sidebar.

Rendering Page Children

Radiant provides a group of tags that are useful for rendering a page’s child pages. The main tag which gives you access to each of page’s children is the children:each tag:

h3. <r:link />
<r:content />

The above code will spin through each of the page’s children and output a link to the child page and the body content part. Now if you used this with the archive behavior to create a blog you would probably want to limit the number of children that were displayed on the archive page:

<r:children:each limit="5" order="desc">
h3. <r:link />
<r:content />

But suppose you wanted to display the first 5 articles and then a bulleted list of the next 10 articles? You could create the list using the limit attribute in conjunction with the offset attribute:

<r:children:each limit="10" offset="5" order="desc">
* <r:link />

The order attribute specifies the order (“desc” or “asc”) that you want to cycle through the page’s children. By default the order attribute is set to “asc” for ascending. Children are normally sorted by their published date, but this can be changed so that they are sorted by another attribute. For example:

<r:children:each by="title">
* <r:link />

The above will render a bulleted list of page children sorted by the title attribute.

That should be enough to get you started. We will cover a few additional tags in a future article. If you can’t wait until then have a look at page_context.rb.