Radius Tags

tandroid edited this page Jan 6, 2016 · 15 revisions
Clone this wiki locally

At the heart of Radiant are Radius tags; sometimes just called tag(s) for brevity. A Radius tag is very similar to an HTML tag, if you’re familiar with HTML you’ll feel right at home. Here’s a simple example that demonstrates using tags that insert content to retrieve the current page’s title and URL.

This page's title is: <r:title/>
This page's URL is: <r:url/>

And here’s the same example except with the addition of a tag that changes scope so that the current page shows the title and URL of it’s parent page.

<r:parent>
  My parent's title is: <r:title/>
  My parent's URL is: <r:url/>
</r:parent>

Radiant comes with a useful selection of Radius tags right out the box and adding your own tags is straightforward. As we’ve already seen in the previous example some tags can insert content others can change the context we're in, behave like conditional statements or allow you to iterate over collections. Once you understand the basics of Radius, you should find that the tags not covered explicitly are fairly self-explanatory.

Basic Usage

In general, you can use a Radius tag wherever it would be appropriate to use an HTML tag, this means that tags can only be used in page, layout or snippet content, but not in names or titles.

As the <r:parent> example above shows, it is possible to nest Radius tags within other Radius tags, so long as they are separate elements. However, using a Radius tag as the the attribute of another Radius tag is NOT ALLOWED. For example:

<r:if_url matches="<r:parent><r:url/></r:parent>">...</r:if_url>
                   ^ DON'T DO THIS, it breaks! ^

Now you’re probably wondering, “How can I use variables or constants within the attributes of a Radius tag?” The answer is that you can’t.

The syntax of Radius is designed so that it fits within the namespace of XML. So if your text editor has syntax highlighting, then the illegal example above will probably look wrong.

Note: You CAN use Radius tags within the attributes of HTML tags. For example:

<body id="<r:slug/>">

Radius tags fall into four categories:

  • Tags that Insert Content are the self-closing style tags, like <r:title/>, and refer to the different page attributes or content. <r:link> and <r:snippet> are notable exceptions that can act as both a self-closing and container element, the <r:navigation> tag is always used as a container.
  • Tags that Change Page Context are the container style tags, like <r:parent>...</r:parent>, and control from which page the contained tags get their content.
  • Conditional Tags are the container style tags that begin with <r:if_ or <r:unless_, like, <r:if_content>we have a body part</r:if_content> and only render their containing elements when the condition is successfully met.
  • Tags that Work with Collections are the container style tags that don’t fit into another category, like <r:children>...</r:children> and operate on one or more pages at a time.