= Back Door, execute Ruby code directly inside Radiant templates
==Intro
Back door is a Radiant extension that allows executing Ruby code directly
inside Radiant templates. It provides the following main tags: , ,
, , , and .
The objective of this extension is to avoid writing Radiant extensions for easy
tasks. If you just need some Ruby/ERB code inside templates, this extension
is for you. If you want to implement Radius tags, modify the admin interface or
define some other complex behavior you should revert to writing a complete Radiant
extension.
Download:: git://github.com/aitorgr/radiant-backdoor.git
Project home:: http://github.com/aitorgr/radiant-backdoor
Current version:: 0.4.2
Author:: aitor.name[http://aitor.name]
Please discuss, report bugs and comments to the Radiant user's mailing-list[http://radiantcms.org/mailing-list]
or contact the author directly at me(at)aitor.name.
Thanks to RubyForge for hosting this project.
== Usage
This extension adds the following new tags:
===
Executes the content of the tag body as Ruby code and renders the returned value.
*Usage:*
[ruby code]
*Example:*
With this fine extension you have access to all this information: self.inspect
This machine identifies itself as `uname -a`
===
Executes the content of the tag body as ERB code and renders the returned value.
*Usage:*
[ERB template]
*Example:*
| name | password | uid | gid | class | home_dir | shell |
<% File.open( "/etc/passwd") do |io|
while line = io.gets
next if line =~ /^s*#/
fields = line.split( ":")
%>
<% fields.each do |field| %>
| <%= field %> |
<% end %>
<% end
end
%>
*Caveats:*
When using ruby looping constructs inside a ERB template, the Radius tags present in the template get expanded
only once, and then "repeated" multiple times by the Ruby code. For example, the following code:
<% 5.times do %>
<%= %>
<% end %>
returns "11111", though intuitively it should return "12345" (ignoring whitespace). This is because the
tag gets expanded only once.
Nearly always this is irrelevant, since Radiant tags are all side effect free, that is, they always return the same value
when called multiple times in the same context. Notable exceptions are the and tags.
For the case of tags with side effects, use the tag as documented in the description for that tag.
===
When used inside an "r:erb" tag, it expands the tag named in the "tag" attribute with the given attributes.
This tag avoids the "tag only expands once inside ruby loops" problem described in the "r:erb" tag. It takes a required
"tag" attribute that identifies an existing tag, and expands that tag passing it the rest of attributes.
NOTE that this tag must be used inside an ERB <%= %> construct.
*Usage:"
*Example:"
<% %>
<% 5.times do %>
<%=
%>
<% end %>
renders "23451" (ignoring whitespace)
===
Renders the tag body if the given Ruby expression evaluates to true. If not it renders an inner "r:else" tag, if present. Note that there are some caveats regarding the "r:else" tag, look the description of if for more information.
*Usage:*
[HTML content]
[HTML content] [HTML content]
*Example:*
*Caveats:*
There are two caveats with the "r:if/unless" and "r:else" tags (used "r:if" as example, but equally applicable to "r:unless"):
* to allow the expansion of an "r:else" part inside a "r:if" tag, the containing "r:if" tag must be
expanded even if the condition of the "r:if" tag evaluates to false. In this case, the body of the
"r:if" tag is ignored. This is not a problem unless the body of the "r:if" tag has "side effects":
@counter = 0
""
This text is evaluated and ignored, but the following "ruby" tag has a side effect that affects the "else" tag
@counter += 1
@counter
* the rendered value of the "r:if" tag contains also any data after an "r:else" tag:
Hello
Hello Radiant!
world!
evaluates to "Hello world!" (ignoring whitespace)
===
The inverse of the "r:if" tag. Refer to the description of the "r:if" tag for complete documentation.
===
Specifies the "else" part for "r:if" and "r:unless". Refer to the description of the "r:if" tag for complete documentation.
===
Defines a new tag, which can subsequently be used as a normal Radius tag. It can be seen as a programmable and parametrized snippet.
The new tag receives the tag context with the standard name "tag" (see the example below). Note that this tag must be rendered by
Radiant before the tag it defines is used. This typically means that this tag must be used early in a page layout.
*Usage:*
[Ruby code]
[content]
*Example:*
@request.remote_ip
Article posted from IP
===
Same functionality as the "tag" tag but the body of the tag is interpreted as ERB code. Handy for heavy parametrized templating.
*Usage:*
[Ruby code]
[content]
*Example:*
">
<%= tag.attr[ "title"] %>
<%= tag.expand %>