Using Radiant
Building Blocks
A site built around Radiant is administered from the ”/admin” URL. Once logged in, the three main building blocks of Radiant can be edited: Pages, Snippets and Layouts.
- Layouts describe entire pages – where major content blocks will be placed.
- Snippets are typically small fragments of pages which get reused, but which might not appear on every page. Two different layouts can then share the same snippet without having to copy and paste between them. You may choose to use snippets even for text that is used on every page, just to keep your layout as terse as possible.
- Pages contain the content that fills in the scaffolding created by layouts and snippets. The very first parent page you create is the one that gets served by Radiant when you visit the root of your site. Any parent page can have one or more child pages, which in turn can have children. This allows you to structure the layout of your documents for management purposes. There is no necessary direct correlation between the parent and child structure you set up in Radiant and the structure of navigation that you build in the site itself, though if a particular structure makes sense for managing the pages, it usually makes sense for navigating them too.
Site Creation
Radiant supplies no page template data at all when running from a clean installation, so you have to do some work to get going – create a layout (including the DOCTYPE declaration, HTML container tags and so-on), snippets if need be, then populate the site with pages. As with any site, getting a good layout template sorted will help a lot in the long term with making things easier to maintain and aiding easy changes in the site look and feel for purposes of modernisation, corporate rebranding, or simply a change for change’s sake. Previous experience of setting up new sites will of course help a great deal. Radiant’s template scheme is not too different from many others out there; search around on the Web or look into some good technical Web design books for more information.
Layouts
If you select the Layouts tab at the top of the Radiant administration interface you’ll be presented with a list of layouts – an empty list, if you’ve never created any before. The New Layout button at the bottom of the list leads to a form consisting of a large name and body text field. Below the name field is a small More link, which if selected will add a content type field to the form. Layout names can’t contain spaces or tabs. Sticking to lower case letters with underscores separating the words is a reasonable rule if you’re used to creating Web sites by hand, as they mimic the sort of filenames with which you may already be familiar, although filename extensions are not necessary. There is an internal 100 character limit on name lengths and layout names must be unique.
As well as including page content and snippets, one layout can include another layout, which is where the content type field comes in – layouts default to text/xhtml content, but you could create a layout holding a stylesheet with content type text/css or you might just want to go retro and use earlier HTML versions with a text/html content type.
Layouts are written in whatever language is appropriate for the content type you selected (or text/xhtml if you’ve left it at the default setting). Usually this means HTML – no Textile or Markdown here. You should be careful to ensure that, where applicable, the layout will produce a syntactically valid document when served with its associated snippets and page content, assuming the snippets and pages themselves are valid. For HTML and CSS, the online validation services from the W3C can help enormously. Get this right once and you won’t have to worry again for the rest of the site, since pages and snippets do support filters such as Textile, in which case the filter ensures that the HTML is valid. At the time of writing, Textile is supported through RedCloth and Markdown through BlueCloth, unless your Radiant installation has been extended with extra filters.
In addition to the HTML, text or CSS you might be creating for a layout, Radiant has its own set of magic entries that it looks for in order to accomplish linking between layouts, snippets and page content. These take the form of XML elements. Some of these form containers and some form attributes (for example, one attribute could be a page’s title). Many of the containers define the object to which an attribute applies – for example, you might want the title for the current page, a child, or its parent.
These tags apply for all of layouts, pages and snippets and are described in detail later.
Snippets
Snippets are edited from the Snippets tab in the Radiant administrative interface. When you select the New Snippet button you’ll be presented with a form where you can give the snippet a name and some body text. The same naming restrictions apply as for layouts. Body text is relatively straightforward; you can select a filter from the drop-down menu underneath the body text if you want Textile or Markdown support. A snippet should be written in a language appropriate for the content type asserted by the layout that includes it, or layout used by a page that includes it – Textile or Markdown filter use implies the snippet will always be part of an [X]HTML document, though it’s conceivable that you might be serving, say, plain text, and deliberately use the filter as an example of generated markup for part of a wider technical document.
Pages
Unsurprisingly, pages are edited from the Pages tag in the Radiant administrative user interface. Pages can be added in a heirarchy which makes the initial management page a bit more complicated than for layouts or snippets, but the tree view is pretty self-explanatory and the add/edit/remove facilities all work in the way you would expect.
The very first page you add is implicitly your site’s Home page. Once added, you can only create children in future. Every page has a title, which is free text and is the sort of thing you would want to see appearing in
Note that children are listed in alphabetical order, not order of addition.
Page Behaviours
The Behaviour menu is left set to “None” for most cases. However, you can set up blog-style pages using the “Archive” setting. The parent page, with the “Archive” behaviour, forms the archive index page. Its children gain URLs in the form %Y/%m/%d (e.g. 2004/05/06) according to the date they are published. You can create custom year, month or day index pages for the archive using the “Archive Year Index”, “Archive Month Index” and “Archive Day Index” if you so wish. Another behaviour, “Page Missing”, lets you create a custom page to use whenever a 404 Not Found error is being raised. Finally, the “Env” behaviour is special and used for debugging – it dumps the environment variables under which the Radiant application is running rather than rending the page contents.
Publishing Status
The Status menu determines the page’s visibility. You can also set up Radiant tags that iterate over children of a particular page returning only those with a particular status. Only “Published” pages will be visible on the live site by default. “Draft” and “Reviewed” states can be used if you are creating documentation as part of a team to track a page’s peer review progress, as well as possibly within the site itself using the aforementioned Radiant tags. “Hidden” pages are, as their name suggests, not visible on the live site and also stand aside from the draft/reviewed/published progression. All this said, for many sites you probably won’t want to do anything except set the page status to “Published” once you’ve filled in the body text.
If a page isn’t showing up or links to it give a “page not found” response make sure its status is set to “published”!.
Saving Your Work
The Save and Continue Editing button is particularly useful for pages, pages will usually much more text than layouts or snippets. Web browsers and operating systems are not 100% reliable! If you are concerned about crashes you can use the Radiant database to save your work in progress, its status still set to “Draft”, from time to time. If anything goes wrong on your local machine at least you won’t lose any more than you’ve written since last saving and draft pages don’t show up on the live site so you don’t need to worry about half-finished being read by the rest of the world.
Parts
The special Radiant tags used to include page content within a wider layout, snippet or, indeed, containing page, allow the specification of a named page part. Normally, you edit the body of a page. However, by default there is an extended tab next to the body tab which lets you provide extra content that may be including using a relevant Radiant tag. In fact, “body” and “extended” are themselves just named parts within the page; you can even delete them both if you like, though the “body” part is shown by default. Deleting “body” means nothing will show up unless a layout is used which explicitly names the other part(s) you defined. Notice the small green ”+” and red ”-” icons to the far right hand side of the tab bar – these are how you add named parts or delete the current part, as you wish.
Slugs and Breadcrumbs
The intriguingly named slug refers to the name used by Radiant in links to your pages. Normally this is derived from the page title automatically. However, underneath the title field of the page editor is a small More link. If you click on this, a new section should open where, in the first of the two text fields that appear, you can type in different slug text.
For example, a child of the Home page with title Some source code would have link !http://myhost.com/some-source-code/ by default. If you change its slug text to “some_strangeLink.html”, this becomes !http://myhost.com/some_strangeLink.html/ – note that the trailing ”/” is still there. You should really avoid putting in filename extensions because they’re more or less meaningless with Radiant. Since the slug forms part of the URL for the page, Radiant limits the range of characters that you can include rather than escaping them. Note in particular that spaces aren’t allowed.
Breadcrumb trails are very different. Sites often use these trails to show the user where within the site hierarchy you have gone. The
It’s important to remember the distinction that the breadcrumb text changes things the user can see on the page, while the slug text changes the URLs that Radiant generates in order for pages to be fetched by a browser in the first place.
Caching
An optimisation feature of Radiant is the page cache, which stops it having to rebuild pages from scratch each time they are requested. However, when you edit pages, they may not seem to change when you look at the live site, particularly if the change is for children that some parent page is referencing (lists of links to children, that kind of thing). This is because the generated pages are cached for speed but at the time of writing Radiant does not flush the cache for certain kinds of page changes. To ensure that edits, additions or removals are visible on the live site, click on the Clear Page Cache button underneath the list of pages. This will of course cause a temporary performance hit as the cache must be rebuilt when pages are next fetched.
Radiant Tags
Now the interesting bit – the tags you can use in your layouts, snippets and page bodies to pull all the bits of your site together. This list and the description of the tags is taken from the Radiant source file app/models/page_context.rb if you want to look at the underlying implementation or check for changes if you think the documentation below may be inaccurate.
Tags can only be used in page, layout or snippet content, not in names or page titles.
Where square brackets are used below, they indicate that the thing contained inside is optional. If you decide to include it, don’t include the square brackets – e.g.:
<r:children:each [offset="number"]>
...indicates that you could use the following in a real layout, snippet or page:
<r:children:each offset="2">
Containers
Containers wrap around other Radiant tags. The tags inside will operate within the scope of the container, allowing you to get at, say, the title of the current page or a particular child.
<r:page>...</r:page>
Causes the tags referring to a page’s attributes to refer to the current page.
<r:parent>...</r:parent>
Gives access to page’s parent.
<r:children>...</r:children>
Gives access to a page’s children. This is not directly useful without an inner container to say which child is of interest (see example below).
<r:children:first>...</r:children:first>
or
<r:children>
<r:first>
...
</r:first>
</r:children>
Returns the first child according to sorting in ascending alphabetic order. Inside this tag all page attribute tags are mapped to the first child.
<r:children:last>...</r:children:last>
or
<r:children>
<r:last>
...
</r:last>
</r:children>
Returns the last child according to sorting in ascending alphabetic order. Inside this tag all page attribute tags are mapped to the last child.
<r:children:each [offset="number"]
[limit="number"]
[by="attribute"]
[order="asc|desc"]
[status="draft|reviewed|published|hidden|all"]>
...
</r:children:each>
Cycles through each of the children. Inside this tag all page attribute tags are mapped to the current child page. You can also use the
<r:child>...</r:child>
Page attribute tags inside of this tag refer to the current child. Not needed in most cases. Note that these are not directly useful from a parent, because they don’t say which child to select – there could be several. If you want to refer to child pages, you need to use things like the :first or :last child selectors described above.
<r:find url="value_to_find">...</r:find>
Inside this tag all page related tags refer to the tag found at the ‘url’ attribute.
Page Content
Some of the most important tags in Radiant are used to include snippet or page content within layouts.
<r:content [part="part_name"] [inherit="true|false"] [contextual="true|false"] />
Renders the main content of a page. Use the part attribute to select a specific page part (body or extended usually, unless you’ve added other custom part names to the page). By default the part attribute is set to body. Use the inherit attribute to specify that, if a page does not have a content part by the given part name, the tag should render the parent’s content part instead (this allows children to optionally override parts of a page). By default inherit is set to false. Use the contextual attribute to force a part inherited from a parent part to be evaluated in the context of the child page. By default contextual is set to false.
NEVER include a page within itself, ever! You’ll hang Radiant and the supporting Ruby interpreter. You’ll need to go to your hosting service and forcibly kill off the process, during which time it will be consuming all CPU resources and chewing up huge amounts of RAM. At the time of writing, Radiant does nothing to protect itself against recursive inclusions. So:
Example 1: Never do this!
<r:page><r:content /></r:page>
...If you do that inside a page, you’ll get exactly what you asked for!
<r:snippet name="snippet_name" />
Renders the snippet specified in the name attribute within the context of a page.
Attributes
Attributes include page URLs, titles or authors. The containers listed above determine which page an attribute will act upon. By default, the current page is always chosen.
<r:url />
Renders the URL of the current page.
<r:title />
Renders the title of the current page.
<r:author />
Renders the name of the Author of the current page. The author is set implicitly when someone logs in to the Radiant administrative interface and creates or modifies a page.
<r:date [format="format_string"] />
Renders the date that a page was published (or in the event that it has not ben modified yet, the date that it was created). The format attribute uses the same formating codes used by the Ruby strftime function. By default it’s set to %A, %B %d, %Y.
<r:link [anchor="name"] [other attributes...] />
or
<r:link>...</r:link>
Renders a link to the page. When used as a single tag it uses the page’s title for the link name. When used as a double tag the part in between both tags will be used as the link text. The link tag passes all attributes over to the HTML A tag. This is very useful for passing attributes like the class attribute or id attribute. If the anchor attribute is passed to the tag it will append a pound sign (’#’) followed by the value of the attribute to the href attribute of the HTML A tag, effectively making an HTML anchor. These are better explained by examples:
Example 2:
<r:children:first><r:link /></r:children:first>
Creates a link to the first child of this parent, using the child’s page title as the link’s visible text.
Example 3:
<r:children:last><r:link anchor="hello">Link to child</r:link></r:children:last>
Creates a link to the last child of this parent, using the visible text Link to child. The URL within the link treats the page as if it were a folder with a default index page inside, so it ends in ”/”. The anchor text #hello is appended after this, allowing the link to reference a local anchor within the child page, on the assumption that the HTML for the page defines such an anchor (<A name="..." ...>).
<r:children:count />
Renders the total number of children.
<r:navigation urls="[Title: url; Title: url; ...]">
<r:normal><a href="<r:url />"><r:title /></a></r:normal>
<r:here><strong><r:title /></strong></r:here>
<r:selected><strong><a href="<r:url />"><r:title /></a></strong></r:selected>
<r:between> | </r:between>
</r:navigation>
Renders a list of links specified in the urls attribute according to three states:
- normal specifies the normal state for the link
- here specifies the state of the link when the url matches the current page’s url
- selected specifies the state of the link when the current page is a child of the specified url
The between tag specifies what should be inserted in-between each of the links.
Please note that if you are using 0.6.x use | instead of ; to delimit the navigation urls.
Conditional Elements
Radiant supports a number of ways to include things conditionally using various different tags and matching strategies.
<r:header [name="header_name"] [restart="name1[;name2;...]"]>...</r:header>
Renders the tag contents only if the contents do not match the previous header. This is extremely useful for rendering date headers for a list of child pages.
If you would like to use several header blocks you may use the name attribute to name the header. When a header is named it will not restart until another header of the same name is different.
Using the restart attribute you can cause other named headers to restart when the present header changes. Simply specify the names of the other headers in a semicolon separated list.
<r:if_content [part="part_name"]>...</r:if_content>
Renders the containing elements only if the part exists on a page. By default the part attribute is set body.
<r:unless_content [part="part_name"]>...</r:unless_content>
The opposite of the if_content tag.
<r:if_parent>...</r:if_parent>
Renders the containing elements only if the the page has a parent.
<r:unless_parent>...</r:unless_parent>
The opposite of the if_parent tag.
<r:if_url matches="regexp" [ignore_case="true|false"]>...</r:if_url>
Renders the containing elements only if the page’s url matches the regular expression given in the matches attribute. If the ignore_case attribute is set to false, the match is case sensitive. By default, ignore_case is set to true.
<r:unless_url matches="regexp" [ignore_case="true|false"]>...</r:unless_url>
The opposite of the if_url tag.
<r:random>
<r:option>...</r:option>
<r:option>...</r:option>
...
</r:random>
Randomly renders the content given in of the options specified by the r:option containers.
Miscellaneous tags
<r:breadcrumbs [separator="separator_string"] />
Renders a trail of breadcrumbs to the current page. The separator attribute specifies the HTML fragment that is inserted between each of the breadcrumbs. By default it is set to ’ > ’.
<r:comment>...</r:comment>
Nothing inside a set of comment tags is rendered.
<r:escape_html>...</r:escape_html>
Escapes angle brackets, etc…
<r:rfc1123_date />
Outputs the date using the format mandated by RFC 1123. (Ideal for RSS feeds.)
