link

basic links

The simplest usage is to display a link to the current node and use the title as linked text:

<r:link/>

link text

If you want to change the text of the link, you can either use a block or the text attribute:

<r:link text='hop'/>
<r:link text='#{first_name} #{name}'/>
<r:link do='img'/>
<r:link do='t'>translated text</r:link>

In order to be able to use dummy text in templates, the text in a link block is not used if it is purely static (no zafu). In the example below, the first one shows the title as link while the second evaluates to “contact Jim” or equivalent.

<r:link>dummy text not used</r:link>
<r:link>contact <r:first_name/></r:link>

href

Create a link to another node. The two versions below produce the same result: a link to the project.

<r:link href='project'/>
<r:project do='link'/>

You can also use a stored variable_ or any RubyLess that resolves to either a Node or String :

<r:link href='find("letter in site")'/>
<r:link href='"http://example.com?url=#{url}"'/>

modes and format

When creating a link, you may want to display the target object with a special mode (‘print’, ‘review’, etc) depending on the specialized templates you have created.

<r:link mode='changes'/>

To display a link for a given format (‘data’, ‘xml’, ‘vcard’, etc). Except for ‘data’ which has a special meaning, you need specialized templates or processing tools (pdf) to display other formats. data is used to get the content of Document . It might translate into “image45.jpg” for an image or “document32.odx” for a text file.

<r:link format='data'/>
<r:link format='data' do='t'>download</r:link>

query params

You can add dynamic or static params to the query string (the thing after ’?’ in the url). You just need to set the parameters on the zafu tag:

<p do='link' date='project.start_date' z='%{foobar}' y='this.date.year'/>

If you need to simply pass existing url parameters, you can write:

<r:link encode_params='z,date,y'/>
instead of
<r:link z='params[:z]' date='params[:date]' y='params[:y]'/>

action

Example:

<span do='link' confirm='Destroy "#{title}" ?' action='destroy' redir='url(find("parent"))' do='t'>destroy_action</span>

You can also use the “data-confirm” html attribute on any link.

host, port, protocol

Sometimes you need to force the links to include protocol with host and port (like when you want a link back from an email). You do this with the ‘host’ and ‘ssl’ options:

<a href='#{url(this, :host =&gt; "some.host:445", :ssl =&gt; true)}' do='title'/>

anchors

Sometimes, you want to link to another part on the same page. You can achieve this by using “anchor” :

<r:link anchor='true'/>

Note that “true” is a special case that uses the default anchor format.

This is exactly the same as the example below:

<a href='#node#{id}' do='title'/>

But “anchor” is nicer to read and easier to use as a “do” method (here we use the node name as anchor):

<li do='each' do='link' anchor='#{node_name}'/>

If you need very special stuff in your links, you can always use RubyLess evaluated parameters:

<a href='#{parent.url}##{node_name}' onclick='...' do='title'/>

Pagination

In a pagination context, we can use the “page” attribute to show the previous or next page or the list of pages:

<ul do='nodes in site limit 10 paginate p'>
  <li do='link' page='list' page_count='10'/>
  <li>...</li>
</ul>

Remote update

You can use links to update blocks. This can be used to paginate with ajax:

<ul id='posts' do='block' do='posts in site limit 5 paginate p'>
  <li do='link' page='list' update='posts'/>
  <li do='each'> ... show Post ...</li>
</ul>

Or to load more posts by inserting new ones below:

<ul id='posts' do='block' do='posts in site limit 5 paginate p'>
  <li do='each'> ... show Post ...</li>
  <li class='more' do='link' page='next' update='posts' insert='bottom' do='t'>load more...</li>
<r:ajax? do='js'>$$('#posts li.more').first().remove();</r:ajax?>
</ul>

In the last example, we added some javascript to hide the “load more..” link at the bottom of the previous content. In a similar way, you could scroll, make things appear or slide open, etc.

Of course, you can also use remote updates to show content, load forms or any other idea that comes to mind:

<div id='preview' style='display:none' do='ajax?'>
  preview content for: <r:title/>
  <r:img mode='std'/>
  <r:js>new Effect.Appear('preview');</r:js>
</div>
<ul do='images in site'>
  <li do='each' do='link' update='preview'/>
</ul>

Notice how we test Ajax rendering with ‘ajax?’. This simply test for the “s” parameter which is added to all Ajax requests in order to not loose the start node.

dates

When we need to show dates (instances of Time ) in links, these must be serialized in the correct timezone. By default, Zena uses the visitor’s timezone but you can specify something else by setting “tz” to the timezone name (“Asia/Jakarta” for example). Make sure you decode the date parameter with the same timezone:

<r:link tz='Asia/Jakarta' my_date='created_at' update='foo'/>
<div id='foo' do='set' my_date='parse_date(params[:my_date], "Asia/Jakarta")'>
 ...
</div>

A better solution is to set a contextual “tz” value that will be used by “link” and parse_date>

<r:default tz='Asia/Jakarta'>
  <r:link my_date='created_at' update='foo'/>
  ...
  <div id='foo' do='set' my_date='parse_date(params[:my_date], tz)'>
    ...
  </div>
</r:default>

misc

If the text inside the link text is static, it is not used and is considered as sample text to help creating the template. If you want static text, you should use do='t' (translate).

Be careful with the use of the href parameter: it should only be used to display a node and link to another. Using <r:project do='link'/> will render nothing if the project is not found. If you use <r:link href='project'/> you will get a dummy link <a href='#'>...</a> in the same situation.