hobodrymlguide.lyx

#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass hobo
\use_default_options true
\master hobo.lyx
\begin_modules
logicalmkup
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 1
\boxbgcolor #e6e6e6
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Chapter
Chapter 13 
\begin_inset Newline newline
\end_inset

THE HOBO DRYML GUIDE
\end_layout

\begin_layout Section
What is DRYML
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML
\end_layout

\end_inset

?
\end_layout

\begin_layout Standard
DRYML is a template language for Ruby on Rails that you can use in place
 of Rails’ built-in ERB templates.
 It is part of the larger Hobo project, but will eventually be made available
 as a separate plugin.
\end_layout

\begin_layout Standard
DRYML was created in response to the observation that the vast majority
 of Rails development time seems to be spent in the view-layer.
 Rails’ models are beautifully declarative, the controllers can easily be
 made very easily (witness the many and various “result controller” plugins),
 but the views, ah the views…
\end_layout

\begin_layout Standard
Given that so much of the user interaction we encounter on the web is similar
 from one website to another, surely we don’t have to code all this stuff
 up from low-level primitives over and over again? Please, no! 
\end_layout

\begin_layout Standard
Of course what we want is a nice library of ready-to-go user interface component
s, or widgets, which can be quickly added to our project, and easily tailored
 to the specifics of our application.
\end_layout

\begin_layout Standard
If you’ve been at this game for a while you’re probably frowning now.
 Re-use is a very, very thorny problem.
 It’s one of those things that sounds straight-forward and obvious in principle,
 but turns out to be horribly difficult in practice.
 When you come to re-use something, you very often find that your new needs
 differ from the original ones in a way that wasn’t foreseen or catered
 for in the design of the component.
 The more complex the component, the more likely it is that bending the
 thing to your needs will be harder than starting again from scratch.
\end_layout

\begin_layout Standard
The challenge is not in being able to re-use code, it is:
\end_layout

\begin_layout Standard
\begin_inset Flex Strong
status collapsed

\begin_layout Plain Layout
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
Being able to re-use code in ways that were not foreseen.
 
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The reason we created DRYML was to see if this kind of flexibility could
 be built into the language itself.
 DRYML is a tag-based language that makes it trivially easy to give the
 defined tags a great deal of flexibility.
\end_layout

\begin_layout Standard
DRYML is just a means to an end.
 The real goal is to create a library of reusable user-interface components
 that actually succeed in making it very quick and easy to create the view
 layer of a web application.
\end_layout

\begin_layout Standard
That library is also part of Hobo – the 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
Rapid
\end_layout

\end_inset

 tag library.
 You will visit this library later on in the book 
\begin_inset Note Note
status open

\begin_layout Plain Layout
Insert page numbers
\end_layout

\end_inset

.
 Here, we will see how DRYML provides the tools and raw materials that make
 a library like Rapid possible.
\end_layout

\begin_layout Standard
Discussing DRYML before Rapid means that many of the examples are 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
not
\end_layout

\end_inset

 good advice for use of DRYML in a full Hobo app.
 For example, you might see
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<%= h this.name %>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Which in an app that used Rapid would be better written 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view:name/>
\end_layout

\end_inset

 or even just 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<name/>
\end_layout

\end_inset

 (that’s a tag by the way, called 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset

, not some metaprogramming trick that lets you use field names as tags).
 Bear that in mind while you’re reading this chapter.
 The examples are chosen to illustrate the point at hand, they are not necessari
ly something you want to paste right into your application.
\end_layout

\begin_layout Section
Simple page templates and ERB
\end_layout

\begin_layout Standard
In its most basic usage, DRYML can be indistinguishable from a normal Rails
 template.
 That’s because DRYML is (almost) an extension of ERB, so you can still
 insert Ruby snippets using the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<% ...
 %>
\end_layout

\end_inset

 notation.
 For example, a show-page for a blog post might look like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<html>
\end_layout

\begin_layout LyX-Code
  <head>
\end_layout

\begin_layout LyX-Code
    <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
  </head>
\end_layout

\begin_layout LyX-Code
  <body>
\end_layout

\begin_layout LyX-Code
    <h1>My Famous Blog!</h1>
\end_layout

\begin_layout LyX-Code
    <h2><%= @post.title %></h2>
\end_layout

\begin_layout LyX-Code
    <div class="post-body"> 
\end_layout

\begin_layout LyX-Code
      <%= @post.body %>
\end_layout

\begin_layout LyX-Code
    </div>
\end_layout

\begin_layout LyX-Code
  </body>
\end_layout

\begin_layout LyX-Code
</html>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Flex Strong
status collapsed

\begin_layout Plain Layout
No ERB inside tags
\end_layout

\end_inset


\end_layout

\begin_layout Standard
DRYML’s support for ERB is not quite the same as true ERB templates.
 The one thing you can’t do is use ERB snippets inside a tag.
 To have the value of an attribute generated dynamically in ERB, you could
 do:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<a href="<%= my_url %>">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In DRYML you would do:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<a href="#{my_url}">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In rare cases, you might use an ERB snippet to output one or more entire
 attributes:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<form <%= my_attributes %>>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’re jumping ahead here, so just skip this if it doesn’t make sense, but
 to do the equivalent in DRYML, you would need your attributes to be in
 a hash (rather than a string), and do:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<form merge-attrs="&my_attributes">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Finally, in a rare case you could even use an ERB snippet to generate the
 tag name itself:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<<%= my_tag_name %>> ...
 </<%= my_tag_name %>>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To achieve that in DRYML, you could put the angle brackets in the snippet
 too:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<%= "<#{my_tag_name}>" %> ...
 <%= "</#{my_tag_name}>" %>
\end_layout

\end_inset


\end_layout

\begin_layout Section
Where are the layouts?
\end_layout

\begin_layout Standard
Going back to the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag at the start of this section 
\begin_inset Note Note
status open

\begin_layout Plain Layout
Page number
\end_layout

\end_inset

, from a “normal Rails” perspective, you might be wondering why the boilerplate
 stuff like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<html>
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<head>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body>
\end_layout

\end_inset

 are there.
 What happened to layouts
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
layouts
\end_layout

\end_inset

? You don’t tend to use layouts with DRYML, instead you would define your
 own tag, typically 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

, and call that.
 Using tags for layouts is much more flexible, and it moves the choice of
 layout out of the controller and into the view layer, where it should be.
\end_layout

\begin_layout Standard
We’ll see how to define a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag in the next section.
\end_layout

\begin_layout Section
Defining simple tags
\end_layout

\begin_layout Standard
One of the strengths of DRYML is that defining tags is done right in the
 template (or in an imported tag library) using the same XML-like syntax.
 This means that if you’ve got markup you want to re-use, you can simply
 cut-and-paste it into a tag definition.
\end_layout

\begin_layout Standard
Here’s the page from the previous section, defined as a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag simply by wrapping the markup in a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<def>
\end_layout

\end_inset


\end_layout

\end_inset

 tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page">
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
    <head>
\end_layout

\begin_layout LyX-Code
      <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
    </head>
\end_layout

\begin_layout LyX-Code
    <body>
\end_layout

\begin_layout LyX-Code
      <h1>My Famous Blog!</h1> 
\end_layout

\begin_layout LyX-Code
      <h2><%= @post.title %></h2> 
\end_layout

\begin_layout LyX-Code
      <div class="post-body"> 
\end_layout

\begin_layout LyX-Code
        <%= @post.body %> 
\end_layout

\begin_layout LyX-Code
      </div> 
\end_layout

\begin_layout LyX-Code
    </body> 
\end_layout

\begin_layout LyX-Code
  </html> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now we can call that tag just as we would call any other:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you’d like an analogy to “normal” programming, you can think of the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>...</def>
\end_layout

\end_inset

 as defining a method called 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
page
\end_layout

\end_inset

, and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page/>
\end_layout

\end_inset

 as a call to that method.
\end_layout

\begin_layout Standard
\begin_inset Flex Strong
status collapsed

\begin_layout Plain Layout
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
In fact, DRYML is implemented by compiling to Ruby, and that is exactly
 what is happening.
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Parameters
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve illustrated the most basic usage of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

, but our 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag is not very useful.
 Let’s take it a step further to make it into the equivalent of a layout.
 First of all, we clearly need the body of the page to be different each
 time we call it.
\end_layout

\begin_layout Standard
In DRYML we achieve this by adding 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
parameters
\end_layout

\end_inset

 to the definition which is accomplished with the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 attribute.
 Here’s the new definition:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page"> 
\end_layout

\begin_layout LyX-Code
  <html> 
\end_layout

\begin_layout LyX-Code
    <head> 
\end_layout

\begin_layout LyX-Code
      <title>My Blog</title> 
\end_layout

\begin_layout LyX-Code
    </head> 
\end_layout

\begin_layout LyX-Code
    <body param/> 
\end_layout

\begin_layout LyX-Code
  </html> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now, we can call the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag and provide our own body:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
   <body:>
\end_layout

\begin_layout LyX-Code
     <h1>My Famous Blog!</h1> 
\end_layout

\begin_layout LyX-Code
    <h2><%= @post.title %></h2> 
\end_layout

\begin_layout LyX-Code
     <div class="post-body"> 
\end_layout

\begin_layout LyX-Code
      <%= @post.body %>
\end_layout

\begin_layout LyX-Code
     </div> 
\end_layout

\begin_layout LyX-Code
  </body:>
\end_layout

\begin_layout LyX-Code
 </page><def tag="page">
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
    <head>
\end_layout

\begin_layout LyX-Code
      <title>My Blog</title> 
\end_layout

\begin_layout LyX-Code
    </head>
\end_layout

\begin_layout LyX-Code
    <body param/>
\end_layout

\begin_layout LyX-Code
  </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
See how easy that was? We just added 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 to the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body>
\end_layout

\end_inset

 tag which means our page tag now has a parameter called 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

body
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset

.
 In the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<
\begin_inset Quotes erd
\end_inset

page
\begin_inset Quotes erd
\end_inset

>
\end_layout

\end_inset

 call we provide some content for that parameter.
 
\end_layout

\begin_layout Standard
It’s very important to read that call to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 properly.
 In particular, the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 (note the trailing ’:’) is 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
not
\end_layout

\end_inset

 a call to a tag, it is providing a named parameter to the call to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

.
 We call 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 a 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
parameter tag
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!parameter tag
\end_layout

\end_inset


\end_layout

\end_inset

.
 In Ruby terms you could think of the call like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
page(:body => "...my body content...")
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that is not actually what the compiled Ruby looks like in this case,
 but it illustrates the important point that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 is a call to a defined tag, whereas 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 is providing a parameter to that call.
\end_layout

\begin_layout Section
Changing Parameter Names
\end_layout

\begin_layout Standard
To give the parameter a different name, we can provide a value to the param
 attribute:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page">
\end_layout

\begin_layout LyX-Code
   <html>
\end_layout

\begin_layout LyX-Code
     <head>
\end_layout

\begin_layout LyX-Code
       <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
     </head> 
\end_layout

\begin_layout LyX-Code
    <body param="content"/> 
\end_layout

\begin_layout LyX-Code
  </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We would now call the tag like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
  <content:>
\end_layout

\begin_layout LyX-Code
    ...body content goes here...
\end_layout

\begin_layout LyX-Code
  </content:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Section
Multiple Parameters
\end_layout

\begin_layout Standard
As you would expect, we can define many parameters in a single tag.
 For example, here’s a page with a side-bar:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page">
\end_layout

\begin_layout LyX-Code
   <html> 
\end_layout

\begin_layout LyX-Code
    <head>
\end_layout

\begin_layout LyX-Code
       <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
     </head> 
\end_layout

\begin_layout LyX-Code
    <body> 
\end_layout

\begin_layout LyX-Code
      <div param="content"/> 
\end_layout

\begin_layout LyX-Code
      <div param="aside" /> 
\end_layout

\begin_layout LyX-Code
    </body>
\end_layout

\begin_layout LyX-Code
  </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Which we could call like this:
\end_layout

\begin_layout LyX-Code
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
   <content:> ...
 main content here ...
 </content:>
\end_layout

\begin_layout LyX-Code
   <aside:>  ...
 aside content here ...
 </aside:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: When you name a parameter, DRYML automatically adds a CSS class of
 the same name to the output, so the two 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

 tags above will be output as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div class="content">
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div class="aside">
\end_layout

\end_inset

 respectively.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Default Parameter
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Default Parameter
\end_layout

\end_inset

 Content
\end_layout

\begin_layout Standard
In the examples we’ve seen so far, we’ve only put the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 attribute on empty tags.
 However, that’s not required.
 If you declare a non-empty tag as a parameter, the content of that tag
 becomes the default when the call does not provide that parameter.
 This means you can easily add a parameter to any part of the template that
 you think the caller might want to be able to change:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page">
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
     <head> 
\end_layout

\begin_layout LyX-Code
       <title param>My Blog</title>
\end_layout

\begin_layout LyX-Code
     </head> 
\end_layout

\begin_layout LyX-Code
     <body param>
\end_layout

\begin_layout LyX-Code
   </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve made the page title parameterized.
 All existing calls to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page/>
\end_layout

\end_inset

 will continue to work unchanged, but we’ve now got the ability to change
 the title on a per-page basis:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
   <title:>My VERY EXCITING Blog</title:>
\end_layout

\begin_layout LyX-Code
   <body:>
\end_layout

\begin_layout LyX-Code
     ...
 body content
\end_layout

\begin_layout LyX-Code
   </body:> 
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This is a very nice feature of DRYML - whenever you’re writing a tag, and
 you see a part that might be useful to change in some situations, just
 throw the param attribute at it and you’re done.
\end_layout

\begin_layout Subsection*
Nested 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset


\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Nested parameters
\end_layout

\end_inset

 Declarations
\end_layout

\begin_layout Standard
You can nest 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 declarations inside other tags that have 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 on them.
 For example, there’s no need to choose between a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag that provides a single content section and one that provides an aside
 section as well – a single definition can serve both purposes:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page">
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
    <head>
\end_layout

\begin_layout LyX-Code
      <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
    </head>
\end_layout

\begin_layout LyX-Code
    <body param>
\end_layout

\begin_layout LyX-Code
      <div param="content"/>
\end_layout

\begin_layout LyX-Code
      <div param="aside" />
\end_layout

\begin_layout LyX-Code
    </body>
\end_layout

\begin_layout LyX-Code
  </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Here the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body>
\end_layout

\end_inset

 tag is a param, and so are the two 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

 tags inside it.
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag can be called either like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page> 
\end_layout

\begin_layout LyX-Code
  <body:> ...
 page content goes here ...
 </body:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Or like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
   <content:> ...
 main content here ...
 </content:> 
\end_layout

\begin_layout LyX-Code
   <aside:>  ...
 aside content here ...
 </aside:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
An interesting question is, what happens if you give both a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter and say, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<content:>
\end_layout

\end_inset

.
 By providing the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter, you have replaced everything inside the body section, including
 those two parameterized 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

 tags, so the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 you have provided will appear as normal, but the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<content:>
\end_layout

\end_inset

 parameter will be silently ignored.
\end_layout

\begin_layout Section
The Default Parameter
\begin_inset Index idx
status open

\begin_layout Plain Layout
DRYML!The Default Parameter
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In the situation where a tag will usually be given a single parameter when
 called, you can give your tag a more compact XML-like syntax by using the
 special parameter name 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
default
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page"> 
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
     <head>
\end_layout

\begin_layout LyX-Code
       <title>My Blog</title>
\end_layout

\begin_layout LyX-Code
     </head> 
\end_layout

\begin_layout LyX-Code
    <body param="default"/> 
\end_layout

\begin_layout LyX-Code
  </html
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now there is no need to give a parameter tag in the call at all - the content
 directly inside the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag becomes the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
default
\end_layout

\end_inset

 parameter:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
  ...
 body content goes here -- 
\end_layout

\begin_layout LyX-Code
  no need for a parameter tag ...
 
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You might notice that the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag is now indistinguishable from a normal HTML tag.
 Some find this aspect of DRYML disconcerting at first.
 How can you tell what is an HTML tag and what it a defined DRYML tag? The
 answer is – you can’t and that’s quite deliberate.
 This allows you to do nice tricks like define your own smart 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<form>
\end_layout

\end_inset

 tag or 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

 tag (the Rapid library does exactly that).
 Other tag-based template languages (e.g.
 Java’s JSP) like to put everything in XML namespaces.
 The result is very cluttered views that are boring to type and hard to
 read.
 From the start we put a very high priority on making DRYML templates compact
 and elegant.
 When you’re new to DRYML you might have to do a lot of looking things up,
 as you would with any new language or API.
 Things gradually become familiar and then view templates can be read and
 understood very easily.
\end_layout

\begin_layout Section
The Implicit Context
\begin_inset Index idx
status open

\begin_layout Plain Layout
DRYML!Implicit Context
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In addition to the most important goal behind DRYML, creating a template
 language that would encourage re-use in the view layer, a secondary goal
 is for templates to be concise, elegant and readable.
 One aspect of DRYML that helps in this regard is called the 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

implicit context
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
This feature was born of a simple observation that pretty much every page
 in a web app renders some kind of hierarchy of application objects.
 Think about a simple page in a blog - say, the permalink page for an individual
 post.
 The page as a whole can be considered a rendering of a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
BlogPost
\end_layout

\end_inset

 object.
 Then we have sections of the page that display different “pieces” of the
 post – the title, the date, the author’s name, the body.
 Then we have the comments.
 The list of comments as a whole is also a “piece” of the BlogPost.
 Within that we have each of the individual comments, and the whole thing
 starts again: the comment title, date, author… This can be learned on even
 further.
 For example some blogs are set up so that you can comment on comments.
\end_layout

\begin_layout Standard
This structure is incredibly common, perhaps even universal.
 It seems to be intrinsically tied to the way we visually parse information.
 DRYML’s implicit context takes advantage of this fact to make templates
 extremely concise while remaining readable and clear.
 The object that you are rendering in any part of the page is known as the
 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
context
\end_layout

\end_inset

, and every tag has access to this object through the method 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

this
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset

.
 The controller sets up the initial context, and the templates then only
 have to mention where the context needs to 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
change
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
We’ll dive straight into some examples, but first a quick general point
 about this guide.
 If you like to use the full Hobo framework, you will probably always use
 DRYML and the Rapid tag library together.
 DRYML and Rapid have grown up together and the design of each is heavily
 influenced by the other.
 Having said that, this is the DRYML Guide, not the Rapid Guide.
 We won’t be using any Rapid tags in this guide because we want to properly
 document DRYML the language.
 That will possibly be a source of confusion, if you’re used to working
 with Rapid.
 If you keep in mind that we’re not allowed to use any Rapid tags in this
 guide and you’ll be fine.
\end_layout

\begin_layout Standard
In order to clearly see the implicit context, we’ll start by defining a
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view>
\end_layout

\end_inset

 tag, that simply renders the current context with HTML escaping.
 Remember the context is always available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="view"><%= h this.to_s %></def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Next we’ll define a tag for making a link to the current context.
 We’ll assume the object will be recognized by Rails’ polymorphic routing.
 Let’s call the tag 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<l>
\end_layout

\end_inset

 (for link):
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="l">
\end_layout

\begin_layout LyX-Code
  <a href="#{url_for this}" param="default"/>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now,let’s use these tags in a page template.
 We’ll stick with the comfortingly boring blog post example.
 In order to set the initial context, our controller action would need to
 do something like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
def show 
\end_layout

\begin_layout LyX-Code
  @this = @blog_post = BlogPost.find(params[:id])
\end_layout

\begin_layout LyX-Code
end
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The DRYML template handler looks for the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

@this
\end_layout

\end_inset

 instance
\begin_inset Quotes erd
\end_inset

 variable for the initial context.
 It’s quite nice to also set the more conventionally named instance variable
 as we’ve done here.
 Now we’ll create the page.
 Let’s assume we’re using a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag along the lines of those defined above.
 We’ll also assume that the blog post object has these fields: 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
title
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
published_at
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
body
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
belongs_to :author
\end_layout

\end_inset

, and that the author has a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset

 field:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
  <content:>
\end_layout

\begin_layout LyX-Code
    <h2><view:title/></h2> 
\end_layout

\begin_layout LyX-Code
    <div class="details"> 
\end_layout

\begin_layout LyX-Code
      Published by <l:author><view:name/></l>
\end_layout

\begin_layout LyX-Code
      on <view:published-at/>.
\end_layout

\begin_layout LyX-Code
    </div> 
\end_layout

\begin_layout LyX-Code
    <div class="post-body">
\end_layout

\begin_layout LyX-Code
      <view:body/>
\end_layout

\begin_layout LyX-Code
    </div>
\end_layout

\begin_layout LyX-Code
  </content:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
When you see a tag like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view:title/>
\end_layout

\end_inset

, you don’t get any prizes for guessing what will be displayed.
 In terms of what actually happens, you can read this as “change the context
 to be the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
title
\end_layout

\end_inset

 attribute of the current context, then call the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view>
\end_layout

\end_inset

 tag”.
 You might like to think of that change to the context as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this = this.title
\end_layout

\end_inset

 (although in fact 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this
\end_layout

\end_inset

 is not assignable).
 Just think of it as “view the title”.
 Of what? Of whatever is in context, in this case the blog post.
\end_layout

\begin_layout Standard
Be careful with the two different uses of colon in DRYML.
 A trailing colon as in 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<foo:>
\end_layout

\end_inset

 indicates a parameter tag, whereas a colon joining two names as in 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view:title/>
\end_layout

\end_inset

 indicates a change of context.
\end_layout

\begin_layout Standard
When the tag ends, the context is set back to what it was before.
 In the case of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view/>
\end_layout

\end_inset

 which is a self-closing tag familiar from XML that happens immediately.
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<l:author>
\end_layout

\end_inset

 tag is more interesting.
 We set the context to be the author, so that the link goes to the right
 place.
 Inside the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<l:author>
\end_layout

\end_inset

 that context remains in place, so we just need 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view:name/>
\end_layout

\end_inset

 in order to display the author’s name.
\end_layout

\begin_layout Subsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with
\end_layout

\end_inset


\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!with attribute
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field
\end_layout

\end_inset

 attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!field attribute
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with
\end_layout

\end_inset

 attribute is a special DRYML attribute that sets the context to be the
 result of any Ruby expression before the tag is called.
 In DRYML any attribute value that starts with ’&’ is interpreted as a Ruby
 expression.
 Here’s the same example as above, but using only the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with
\end_layout

\end_inset

 attribute:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
   <content:>
\end_layout

\begin_layout LyX-Code
     <h2><view with="&@blog_post.title"/></h2>
\end_layout

\begin_layout LyX-Code
     <div class="details">
\end_layout

\begin_layout LyX-Code
       Published by <l
\end_layout

\begin_layout LyX-Code
         with="&@blog_post.author">
\end_layout

\begin_layout LyX-Code
         <view with="&this.name"/></l>
\end_layout

\begin_layout LyX-Code
       on <view with="&@blog_post.published-at"/>.
\end_layout

\begin_layout LyX-Code
     </div>
\end_layout

\begin_layout LyX-Code
     <div class="post-body">
\end_layout

\begin_layout LyX-Code
       <view with="&@blog_post.body"/> 
\end_layout

\begin_layout LyX-Code
     </div>
\end_layout

\begin_layout LyX-Code
   </content:>
\end_layout

\begin_layout LyX-Code
 </page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: We could have used 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&this.title
\end_layout

\end_inset

 instead of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&@blog_post.title
\end_layout

\end_inset

.
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field
\end_layout

\end_inset

 attribute makes things more concise by taking advantage of a common pattern.
 When changing the context, we very often want to change to some attribute
 of the current context.
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field="x"
\end_layout

\end_inset

 is a shorthand for 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with="&this.x"
\end_layout

\end_inset

 (actually it’s not quite the same, using the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field
\end_layout

\end_inset

 version also sets 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_parent
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_field
\end_layout

\end_inset

, whereas 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with
\end_layout

\end_inset

 does not.
 This is discussed later in more detail).
\begin_inset Note Note
status open

\begin_layout Plain Layout
Insert page numbers
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The same template again, this time using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

field
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page>
\end_layout

\begin_layout LyX-Code
  <content:> 
\end_layout

\begin_layout LyX-Code
    <h2><view field="title"/></h2>
\end_layout

\begin_layout LyX-Code
    <div class="details"> 
\end_layout

\begin_layout LyX-Code
      Published by <l field="author">
\end_layout

\begin_layout LyX-Code
      <view field="name"/></l>
\end_layout

\begin_layout LyX-Code
      on <view field="published-at"/>.
\end_layout

\begin_layout LyX-Code
    </div> 
\end_layout

\begin_layout LyX-Code
    <div class="post-body"> 
\end_layout

\begin_layout LyX-Code
      <view field="body"/>
\end_layout

\begin_layout LyX-Code
    </div>
\end_layout

\begin_layout LyX-Code
  </content:>
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you compare that example to the first one, you should notice that the
 
\begin_inset Quotes eld
\end_inset

:
\begin_inset Quotes erd
\end_inset

 syntax is just a shorthand for the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field
\end_layout

\end_inset

 attribute; i.e., 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view field="name">
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<view:name>
\end_layout

\end_inset

 are equivalent.
\end_layout

\begin_layout Section
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Field chains
\end_layout

\end_inset

Field chains
\end_layout

\begin_layout Standard
Sometimes you want to drill down through several fields at a time.
 Both the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field
\end_layout

\end_inset

 attribute and the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

:
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset

 shorthand support this.
 For example:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<view:category.name/> 
\end_layout

\begin_layout LyX-Code
<view field="category.name"/>
\end_layout

\end_inset


\end_layout

\begin_layout Subsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_field
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
this_field
\end_layout

\end_inset


\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_parent
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
this_parent
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
When you change the context using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
field="my-field"
\end_layout

\end_inset

 (or the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<tag:my-field>
\end_layout

\end_inset

 shorthand), the previous context is available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_parent
\end_layout

\end_inset

, and the name of the field is available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_field
\end_layout

\end_inset

.
 If you set the context using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

with="...,"
\end_layout

\end_inset

 these values are not available.
 That means the following apparently identical tag calls are not quite the
 same:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<my-tag with="&@post.title"/> 
\end_layout

\begin_layout LyX-Code
<my-tag with="&@post" field="title"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If the tag requires 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_parent
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_field
\end_layout

\end_inset

, and in Rapid, for example, some do, then it must be called using the second
 style.
\end_layout

\begin_layout Subsubsection*
Numeric field indices
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Numeric field indices
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If your current context is a collection, you can use the field attribute
 to change the context to a single item.
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<my-tag field="7" /> 
\end_layout

\begin_layout LyX-Code
  <% i=97 %> 
\end_layout

\begin_layout LyX-Code
<my-tag field="&i" />
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<repeat>
\end_layout

\end_inset

 tag sets 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_field
\end_layout

\end_inset

 to the current index into the collection.
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<repeat:foos> 
\end_layout

\begin_layout LyX-Code
  <td><%= this_field %></td> 
\end_layout

\begin_layout LyX-Code
  <td><view /></td> 
\end_layout

\begin_layout LyX-Code
</repeat>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Forms
\end_layout

\begin_layout Standard
When rendering the Rapid library’s 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<form>
\end_layout

\end_inset

 tag, DRYML keeps track of even more metadata in order to add 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset

 attributes to form fields automatically.
 This mechanism does not work if you set the context using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
with=
\end_layout

\end_inset

.
\end_layout

\begin_layout Section
Tag attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Tag attributes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As we’ve seen, DRYML provides parameters as a mechanism for Customizing
 the markup that is output by a tag.
 Sometimes we want to provide other kinds of values to control the behavior
 of a tag: URLs, filenames or even Ruby values like hashes and arrays.
 For this situation, DRYML lets you define tag attributes.
\end_layout

\begin_layout Standard
As a simple example, say your application has a bunch of help files in 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
public/help
\end_layout

\end_inset

, and you have links to them scattered around your views.
 Here’s a tag you could define:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="help-link" attrs="file"> 
\end_layout

\begin_layout LyX-Code
  <a class="help"
\end_layout

\begin_layout LyX-Code
     href="#{base_url}/help/#{file}.html"
\end_layout

\begin_layout LyX-Code
     param="default"/> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

 takes a special attribute 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attrs
\end_layout

\end_inset

.
 Use this to declare a list (separated by commas) of attributes, much as
 you would declare arguments to a method in Ruby.
 Here we’ve defined one attribute, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
file
\end_layout

\end_inset

, and just like arguments in Ruby, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
file
\end_layout

\end_inset

 becomes a local variable inside the tag definition.
 In this definition we construct the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
href
\end_layout

\end_inset

 attribute from the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
base_url
\end_layout

\end_inset

 helper and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
file
\end_layout

\end_inset

, using Ruby string interpolation syntax (
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
#{....}
\end_layout

\end_inset

).
 Remember that you can use that syntax when providing a value for any attribute
 in DRYML.
\end_layout

\begin_layout Standard
The call to this tag would look like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<help-link file="intro">Introductory Help</help-link>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Using regular XML-like attribute syntax – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
file="intro"
\end_layout

\end_inset

 – passes “intro” as a string value to the attribute.
 DRYML also allows you to pass any Ruby value.
 When the attribute value starts with 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&
\end_layout

\end_inset

, the rest of the attribute is interpreted as a Ruby expression.
 For example you could use this syntax to pass 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
true
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
false
\end_layout

\end_inset

 values:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<help-link file="intro" new-window="&true">
\end_layout

\begin_layout LyX-Code
  Introductory Help
\end_layout

\begin_layout LyX-Code
</help-link>
\end_layout

\begin_layout LyX-Code
<help-link file="intro" new-window="&false">
\end_layout

\begin_layout LyX-Code
  Introductory Help
\end_layout

\begin_layout LyX-Code
</help-link>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
And we could add that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
new-window
\end_layout

\end_inset

 attribute to the definition like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="help-link" attrs="file, new-window"> 
\end_layout

\begin_layout LyX-Code
  <a class="help" 
\end_layout

\begin_layout LyX-Code
     href="#{base_url}/help/#{file}.html"
\end_layout

\begin_layout LyX-Code
     target="#{new_window ? '_blank' : '_self' }"
\end_layout

\begin_layout LyX-Code
     param="default"/> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
An important point to notice there is that the markup-friendly dash in the
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
new-window
\end_layout

\end_inset

 attribute became a Ruby-friendly underscore (
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
new_window
\end_layout

\end_inset

) in the local variable inside the tag definition.
 Using the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&
\end_layout

\end_inset

, you can pass any value you like – arrays, hashes, active-record objects…
 In the case of boolean values like the one used in the above example, there
 is a nicer syntax that can be used in the call…
\end_layout

\begin_layout Section
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Flag attributes
\end_layout

\end_inset

Flag attributes
\end_layout

\begin_layout Standard
That 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
new-window
\end_layout

\end_inset

 attribute shown in the previous section is simple switch - on or off.
 DRYML lets you omit the value of the attribute, giving a flag-like syntax:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<help-link file="intro" new-window>
\end_layout

\begin_layout LyX-Code
  Introductory Help
\end_layout

\begin_layout LyX-Code
</help-link> 
\end_layout

\begin_layout LyX-Code
<help-link file="intro">
\end_layout

\begin_layout LyX-Code
  Introductory Help
\end_layout

\begin_layout LyX-Code
</help-link>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Omitting the attribute value is equivalent to giving 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
"&true"
\end_layout

\end_inset

 as the value.
 In the second example the attribute is omitted entirely, meaning the value
 will be 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
nil
\end_layout

\end_inset

 which evaluates to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
false
\end_layout

\end_inset

 in Ruby and so works as expected.
\end_layout

\begin_layout Subsubsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!attributes local variable
\end_layout

\end_inset


\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!all_attributes local variable
\end_layout

\end_inset


\end_layout

\end_inset

 locals
\end_layout

\begin_layout Standard
Inside a tag definition two hashes are available in local variables: 
\end_layout

\begin_layout Itemize
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 contains all the attributes that 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
were not declared
\end_layout

\end_inset

 in the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attrs
\end_layout

\end_inset

 list of the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
def
\end_layout

\end_inset

 but that were provided in the call to the tag.
 
\end_layout

\begin_layout Itemize
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_attributes
\end_layout

\end_inset

 contains every attribute, including the declared ones.
\end_layout

\begin_layout Section
Merging Attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Merging Attributes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In a tag definition, you can use the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 attribute to take any ‘extra’ attributes that the caller passed in, and
 add them to a tag of your choosing inside your definition.
 Let’s backtrack a bit and see why you might want to do that.
\end_layout

\begin_layout Standard
Here’s a simple definition for a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<markdown-help>
\end_layout

\end_inset

 tag--it’s similar to a tag defined in the Hobo Cookbook app:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="markdown-help"> 
\end_layout

\begin_layout LyX-Code
  <a href="http://daringfireball.net/..." 
\end_layout

\begin_layout LyX-Code
     param="default"/> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You would use it like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
Add formatting using
\end_layout

\begin_layout LyX-Code
<markdown-help>markdown</markdown-help>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Suppose you wanted to give the caller the ability to choose the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
target
\end_layout

\end_inset

 for the link.
 You could extend the definition like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="markdown-help" attrs="target"> 
\end_layout

\begin_layout LyX-Code
  <a href="http://daringfireball.net/..."
\end_layout

\begin_layout LyX-Code
     target="&target" param="default"/> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now we can call the tag like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
Add formatting using 
\end_layout

\begin_layout LyX-Code
<markdown-help target="_blank">markdown</markdown-help>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
OK, but maybe the caller wants to add a CSS class, or a javascript 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
onclick
\end_layout

\end_inset

 attribute, or any one of a dozen potential HTML attributes.
 This approach is not going to scale.
 That’s where 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!merge-attrs
\end_layout

\end_inset


\end_layout

\end_inset

 comes in.
 As mentioned above, DRYML keeps track of all the attributes that were passed
 to a tag, even if they were not declared in the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attrs
\end_layout

\end_inset

 list of the tag definition.
 They are available in two hashes: 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 (that has only undeclared attributes) and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_attributes
\end_layout

\end_inset

 (that has all of them), but in normal usage you don’t need to access those
 variables directly.
 To add all of the undeclared attributes to a tag inside your definition,
 just add the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 attribute, like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="markdown-help">
\end_layout

\begin_layout LyX-Code
  <a href="http://daringfireball.net/..." 
\end_layout

\begin_layout LyX-Code
     merge-attrs param="default"/> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: The 
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!merge attribute
\end_layout

\end_inset


\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge
\end_layout

\end_inset

 attribute is another way of merging attributes.
 Declaring 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge
\end_layout

\end_inset

 is a shorthand for declaring both 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-params
\end_layout

\end_inset

 (which we’ll cover later).
\end_layout

\end_inset


\end_layout

\begin_layout Section
Merging selected attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Merging selected attributes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 can be given a value - either a hash containing attribute names and values,
 or a list of attribute names (comma separated), to be merged from the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_attributes
\end_layout

\end_inset

 variable.
 Examples:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<a merge-attrs="href, name"> 
\end_layout

\begin_layout LyX-Code
<a merge-attrs="&my_attribute_hash">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A requirement that crops up from time to time is to forward to a tag all
 the attributes that it understands (i.e.
 the attributes from that tag’s 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attrs
\end_layout

\end_inset

 list), and to forward some or all the other attributes to tags called within
 that tag.
 Say for example, we are declaring a tag that renders a section of content,
 with some navigation at the top.
 We want to be able to add CSS classes and so on to the main 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

 that will be output, but the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 tag also defines some special attributes, and these need to be forwarded
 to it.
\end_layout

\begin_layout Standard
To achieve this we take advantage of a helper method 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attrs_for
\end_layout

\end_inset

.
 Given the name of a tag, it returns the list of attributes declared by
 that tag.
\end_layout

\begin_layout Standard
Here’s the definition:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="section-with-nav"> 
\end_layout

\begin_layout LyX-Code
  <div class="section" 
\end_layout

\begin_layout LyX-Code
      merge-attrs="&attributes -
\end_layout

\begin_layout LyX-Code
        attrs_for(:navigation)">
\end_layout

\begin_layout LyX-Code
    <navigation 
\end_layout

\begin_layout LyX-Code
      merge-attrs="&attributes &
\end_layout

\begin_layout LyX-Code
        attrs_for(:navigation)"/>
\end_layout

\begin_layout LyX-Code
    <do param="default"/>
\end_layout

\begin_layout LyX-Code
  </div>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that:
\end_layout

\begin_layout Itemize
The expression 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes - attrs_for(:navigation)
\end_layout

\end_inset

 returns a hash of only those attributes from the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 hash that are 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
not
\end_layout

\end_inset

 declared by 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 (The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
-
\end_layout

\end_inset

 operator on 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Hash
\end_layout

\end_inset

 comes from HoboSupport)
\end_layout

\begin_layout Itemize
The expression 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes & attrs_for(:navigation)
\end_layout

\end_inset

 returns a hash of only those 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 from the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 hash that are declared by 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 (The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&
\end_layout

\end_inset

 operator on 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Hash
\end_layout

\end_inset

 comes from HoboSupport)
\end_layout

\begin_layout Itemize
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<do>
\end_layout

\end_inset

 tag is a “do nothing” tag, defined by the core DRYML taglib, which is always
 included.
\end_layout

\begin_layout Subsubsection*
The class attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!The class attribute
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you have the following definition:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="foo"> 
\end_layout

\begin_layout LyX-Code
  <div id="foo" class="bar" merge-attrs /> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
and the user invokes it with:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<foo id="baz" class="bop" />
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The following content will result:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<foo id="baz" class="bar bop" />
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
class
\end_layout

\end_inset

 attribute receives special behavior when merging.
 All other attributes are overridden with the user specified values.
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
class
\end_layout

\end_inset

 attribute takes on the values from both the tag definition and invocation.
\end_layout

\begin_layout Section
Repeated and optional content
\end_layout

\begin_layout Standard
As you would expect from any template language, DRYML has the facility to
 repeat sections of content, and to optionally render or not render given
 sections according to your application’s data.
 DRYML provides two alternative syntaxes, much as Ruby does (e.g.
 Ruby has the block 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

 and the one-line suffix version of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

).
\end_layout

\begin_layout Subsubsection*
Conditionals
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Conditionals
\end_layout

\end_inset

 - 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
unless
\end_layout

\end_inset


\end_layout

\begin_layout Standard
DRYML provides 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
unless
\end_layout

\end_inset

 both as tags, which come from the core tag library, and are just ordinary
 tag definitions, and as attributes, which are part of the language:
\end_layout

\begin_layout Standard
The tag version:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<if test="&logged_in?"><p>Welcome back</p></if>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The attribute version:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<p if="&logged_in?">Welcome back</p>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Important note! The test is performed (in Ruby terms) like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
if (...your test expression...).blank?
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Got that? Blankiness not truthiness (
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
blank?
\end_layout

\end_inset

 comes from ActiveSupport by the way – Rails’ mixed bag of core-Ruby extensions).
 So for example, in DRYML:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<if test="&current_user.comments">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
is a test to see if there are any comments – empty collections are considered
 blank.
 We are of the opinion that Matz made a fantastic choice for Ruby when he
 followed the Lisp / Smalltalk approach to truth values, but that view templates
 are a special case, and testing for blankness is more often what you want.
\end_layout

\begin_layout Standard
Can we skip 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<unless>
\end_layout

\end_inset

? It’s like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<if>
\end_layout

\end_inset

 with the nest negated.
 You get the picture, right?
\end_layout

\begin_layout Subsubsection*
Repetition
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Repetition
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For repeating sections of content, DRYML has the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<repeat>
\end_layout

\end_inset

 tag (from the core tag library) and the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
repeat
\end_layout

\end_inset

 attribute.
\end_layout

\begin_layout Standard
The tag version:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<repeat with="&current_user.new_messages">
\end_layout

\begin_layout LyX-Code
  <h3><%= h this.subject %></h3>
\end_layout

\begin_layout LyX-Code
</repeat>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The attribute version:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h3 repeat="&current_user.new_messages">
\end_layout

\begin_layout LyX-Code
  <%= h this.subject %>
\end_layout

\begin_layout LyX-Code
</h3>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Notice that as well as the content being repeated, the implicit context
 is set to each item in the collection in turn.
\end_layout

\begin_layout Section
Even/odd classes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Even/odd classes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It’s a common need to want alternating styles for items in a collection
 - e.g.
 striped table rows.
 Both the repeat attribute and the repeat tag set a scoped variable 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
scope.even_odd
\end_layout

\end_inset

 which will be alternately ‘even’ then ‘odd’, so you could do:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h3 repeat="&new_messages" class="#{scope.even_odd}">
\end_layout

\begin_layout LyX-Code
  <%= h this.subject %>
\end_layout

\begin_layout LyX-Code
</h3>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
That example illustrates another important point – any Ruby code in attributes
 is evaluated 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
inside
\end_layout

\end_inset

 the repeat.
 In other words, the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
repeat
\end_layout

\end_inset

 attribute behaves the same as wrapping the tag in a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<repeat>
\end_layout

\end_inset

 tag.
\end_layout

\begin_layout Subsubsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
first_item?
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!first_item?
\end_layout

\end_inset


\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
last_item?
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!last_item?
\end_layout

\end_inset


\end_layout

\end_inset

 helpers
\end_layout

\begin_layout Standard
Another common need is to give special treatment to the first and last items
 in a collection.
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
first_item?
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
last_item?
\end_layout

\end_inset

 helpers can be used to find out when these items come up; e.g., we could
 use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
first_item?
\end_layout

\end_inset

 to capitalise the first item:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h3 repeat="&new_messages">
\end_layout

\begin_layout LyX-Code
  <%= h(first_item? ? 
\end_layout

\begin_layout LyX-Code
        this.subject.upcase : 
\end_layout

\begin_layout LyX-Code
        this.subject) %>
\end_layout

\begin_layout LyX-Code
</h3>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Repeating over hashes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Repeating over hashes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you give a hash as the value to repeat over, DRYML will iterate over
 each key/value pair, with the value available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this
\end_layout

\end_inset

 (i.e.
 the implicit context) and the key available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this_key
\end_layout

\end_inset

.
 This is particularly useful for grouping things in combination with the
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
group_by
\end_layout

\end_inset

 method:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<div repeat="&current_user.new_messages.group_by(&:sender)"> 
\end_layout

\begin_layout Code
  <h2>Messages from <%= h this_key %></h2> 
\end_layout

\begin_layout Code
    <ul> 
\end_layout

\begin_layout Code
      <li repeat><%= h this.subject %></li> 
\end_layout

\begin_layout Code
    </ul> 
\end_layout

\begin_layout Code
  </h2> 
\end_layout

\begin_layout Code
</div>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
That example has given a sneak preview of another point - using if/unless/repeat
 with the implicit context.
 We’ll get to that in a minute.
\end_layout

\begin_layout Section
Using the implicit context
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!implicit context
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you don’t specify the test of a conditional, or the collection to repeat
 over, the implicit context is used.
 This allows for a few nice shorthands.
 For example, this is a common pattern for rendering collections:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<if:comments> 
\end_layout

\begin_layout Code
  <h3>Comments</h3> 
\end_layout

\begin_layout Code
  <ul> 
\end_layout

\begin_layout Code
    <li repeat> ...
 </li> 
\end_layout

\begin_layout Code
  </ul> 
\end_layout

\begin_layout Code
</if>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’re switching the context on the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<if>
\end_layout

\end_inset

 tag to be 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this.comments
\end_layout

\end_inset

, which has two effects.
 Firstly the comments collection is used as the test for the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

, so the whole section including the heading will be omitted if the collection
 is empty (remember that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

 tests for blankness, and empty collections are considered blank).
 Secondly, the context is switched to be the comments collection, so that
 when we come to repeat the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<li>
\end_layout

\end_inset

 tag, all we need to say is 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
repeat
\end_layout

\end_inset

.
\end_layout

\begin_layout Subsubsection*
One last shorthand - attributes of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The attribute versions of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if/unless
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
repeat
\end_layout

\end_inset

 support a useful shortcut for accessing attributes or methods of the implicit
 context.
 If you give a literal string attribute–that is, an attribute that does
 not start with 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
&
\end_layout

\end_inset

–this is interpreted as the name of a method on 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this
\end_layout

\end_inset

.
 For example:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<li repeat="comments"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
is equivalent to
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<li repeat="&this.comments"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Similarly
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<p if="sticky?">This post has been marked 'sticky'</p>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
is equivalent to
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<p if="&this.sticky?">This post has been marked 'sticky'</p>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It is a bit inconsistent that these shortcuts do not work with the tag versions
 of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<if>
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<unless>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<repeat>
\end_layout

\end_inset

.
 This may be remedied in a future version of DRYML.
\end_layout

\begin_layout Subsubsection*
Content tags only
\end_layout

\begin_layout Standard
The attributes introduced in this section – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
repeat
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
if
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
unless
\end_layout

\end_inset

, can only be used on content tags, i.e.
 static HTML tags and defined tags.
 They cannot be used on tags like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<extend>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<include>
\end_layout

\end_inset

.
\end_layout

\begin_layout Section
Pseudo parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Pseudo parameters
\end_layout

\end_inset

 - 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
before
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
after
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
append
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
prepend
\end_layout

\end_inset

, and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
replace
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For every parameter you define in a tag, there are five “pseudo parameters”
 created as well.
 Four allow you to insert extra content without replacing existing content,
 and one lets you replace or remove a parameter entirely.
\end_layout

\begin_layout Standard
To help illustrate these, here’s a very simple 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="page"> 
\end_layout

\begin_layout LyX-Code
  <body> 
\end_layout

\begin_layout LyX-Code
    <h1 param="heading"><%= h @this.to_s %></h1> 
\end_layout

\begin_layout LyX-Code
    <div param="content"></div> 
\end_layout

\begin_layout LyX-Code
  </body> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve assumed that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
@this.to_s
\end_layout

\end_inset

 will give us the name of the object that this page is presenting.
\end_layout

\begin_layout Subsubsection*
Inserting extra content
\end_layout

\begin_layout Standard
The output of the heading would look something like:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h1 class="heading">Welcome to my new blog</h1>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Pseudo parameters give us the ability to insert extra context in four places,
 marked here as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
(A)
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
(B)
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
(C)
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
(D)
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
(A)<h1 class="heading">(B)Welcome to my new blog(C)</h1>(D)
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The parameters are: 
\end_layout

\begin_layout Itemize
(A) – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<before-heading:>
\end_layout

\end_inset

 
\end_layout

\begin_layout Itemize
(B) – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<prepend-heading:>
\end_layout

\end_inset

 
\end_layout

\begin_layout Itemize
(C) – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<append-heading:>
\end_layout

\end_inset

 
\end_layout

\begin_layout Itemize
(D) – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<after-heading:>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
So, for example, suppose we want to add the name of the blog to the heading:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<h1 class="heading">
\end_layout

\begin_layout Code
  Welcome to my new blog -- The Hobo Blog
\end_layout

\begin_layout Code
</h1>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To achieve that on one page, we could call the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<page>
\end_layout

\end_inset

 tag like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page> 
\end_layout

\begin_layout LyX-Code
  <append-heading:>
\end_layout

\begin_layout LyX-Code
    -- The Hobo Blog
\end_layout

\begin_layout LyX-Code
  </append-heading:> 
\end_layout

\begin_layout LyX-Code
  <body:> ...
 </body> 
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Or we could go a step further and create a new page tag that added that
 suffix automatically.
 We could then use that new page tag for an entire section of our site:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="blog-page"> 
\end_layout

\begin_layout LyX-Code
  <page> 
\end_layout

\begin_layout LyX-Code
    <append-heading:> -- The Hobo Blog</append-heading:> 
\end_layout

\begin_layout LyX-Code
    <body: param></body> 
\end_layout

\begin_layout LyX-Code
  </page> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: We have explicitly made sure that the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter is still available.
 There is a better way of achieving this using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-params
\end_layout

\end_inset

 or 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge
\end_layout

\end_inset

, which are covered later.)
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
The default parameter supports 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
append
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
prepend
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As we’ve seen, the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<append-...:>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<prepend-...:>
\end_layout

\end_inset

 parameters insert content at the beginning and end of a tag’s content.
 But in the case of a defined tag that may output all sorts of other tags
 and may itself define many parameters, what exactly 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
is
\end_layout

\end_inset

 the tag’s “content”? It is whatever is contained in the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
default
\end_layout

\end_inset

 parameter tag.
 So 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<append-...:>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<prepend-...:>
\end_layout

\end_inset

 only work on tags that define a default parameter.
\end_layout

\begin_layout Standard
For this reason, you will often see tag definitions include a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
default
\end_layout

\end_inset

 parameter, even though it would be rare to use it directly.
 It is there so that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<append-...:>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<prepend-...:>
\end_layout

\end_inset

 work as expected.
\end_layout

\begin_layout Subsubsection*
Replacing a parameter entirely
\end_layout

\begin_layout Standard
So far, we’ve seen how the parameter mechanism allows us to change the attribute
s and content of a tag, but what if we want to remove the tag entirely?
 We might want a page that has no 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h1>
\end_layout

\end_inset

 tag at all, or has 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h2>
\end_layout

\end_inset

 instead.
 For that situation we can use “replace parameters”.
 Here’s a page with an 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h2>
\end_layout

\end_inset

 instead of an 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h1>
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page> 
\end_layout

\begin_layout LyX-Code
  <heading: replace><h2>My Awesome Page</h2></heading:> 
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
And here’s one with no heading at all:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page> 
\end_layout

\begin_layout LyX-Code
  <heading: replace/> 
\end_layout

\begin_layout LyX-Code
</page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
There is a nice shorthand for the second case.
 For every parameter, the enclosing tag also supports a special 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
without
\end_layout

\end_inset

 attribute.
 This is exactly equivalent to the previous example, but much more readable:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<page without-heading/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: To make things more consistent, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<heading: replace>
\end_layout

\end_inset

 may become 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<replace-heading:>
\end_layout

\end_inset

 in the future.
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Current limitation
\end_layout

\begin_layout Standard
Due to a limitation of the current DRYML implementation, you cannot use
 both 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
before
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
after
\end_layout

\end_inset

 on the same parameter.
 You can achieve the same effect as follows (this technique is covered properly
 later in the section on wrapping content):
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<heading: replace>
\end_layout

\begin_layout LyX-Code
  ...
 before content ...
 
\end_layout

\begin_layout LyX-Code
  <heading restore> 
\end_layout

\begin_layout LyX-Code
  ...
 after content ...
 
\end_layout

\begin_layout LyX-Code
</heading:>
\end_layout

\end_inset


\end_layout

\begin_layout Section
Nested parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Nested parameters
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As we’ve discussed at the start of this guide, one of the main motivations
 for the creation of DRYML was to deliver a higher degree of 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
re-use
\end_layout

\end_inset

 in the view layer.
 One of the great challenges of re-use is managing the constant tension
 between re-use and flexibility: the greater the need for flexibility, the
 harder it is to re-use existing code.
 This has a very direct effect on the 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
size
\end_layout

\end_inset

 of things that we can successfully re-use.
 Take the humble hypertext link for example.
 A link is a link is a link – there’s only so much you could really want
 to change, so it’s not surprising that long ago we stopped having to assemble
 links from fragments of HTML text.
 Rails has its 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
link_to
\end_layout

\end_inset

 helper, and Hobo Rapid has its 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

 tag.
 At the other extreme, reusing an entire photo gallery or interactive calendar
 is extremely difficult.
 Again no surprise–these things have been built from scratch over and over
 again, because each time something slightly (or very) different is needed.
 A single calendar component that is flexible enough to cover every eventuality
 would be so complicated that configuring it would be more effort than starting
 over.
\end_layout

\begin_layout Standard
This tension between re-use and flexibility will probably never go away;
 life is just like that.
 As components get larger they will inevitably get either harder to work
 with or less flexible.
 What we can do though, through technologies like DRYML, is slow down the
 onset of these problems.
 By thinking about the fundamental challenges to re-use, we have tried to
 create a language in which, as components grow larger, simplicity and flexibili
ty can be retained longer.
\end_layout

\begin_layout Standard
One of the most important features that DRYML brings to the re-use party
 is 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
nested parameters
\end_layout

\end_inset

.
 
\end_layout

\begin_layout Standard
They are born of the following observations:
\end_layout

\begin_layout Itemize
As components get larger, they are not really single components at all,
 but compositions of many smaller sub-components.
 
\end_layout

\begin_layout Itemize
Often, the Customization we wish to make is not to the “super-component”
 but to one of the sub-components.
 
\end_layout

\begin_layout Itemize
What is needed, then, is a means to pass parameters and attributes not just
 to the tag you are calling, but to the tag called within the tag, or the
 tag called within the tag called within the tag, and so on.
\end_layout

\begin_layout Standard
DRYML’s nested parameter mechanism does exactly that.
 After you’ve been using DRYML for some time, you may notice that you don’t
 use this feature very often.
 But when you do use it, it can make the difference between sticking with
 your nice high-level components or throwing them away and rebuilding from
 scratch.
 A little use of nested parameters goes a long way.
\end_layout

\begin_layout Subsubsection*
An example
\end_layout

\begin_layout Standard
To illustrate the mechanism, we’ll build up a small example using ideas
 that are familiar from Rapid.
 This is not a Rapid guide though, so we’ll define these tags from scratch.
 First off, the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 tag.
 This captures the very common pattern of web pages displaying collections
 of some kind of object as small “cards”: comments, friends, discussion
 threads, etc.
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="card">
\end_layout

\begin_layout LyX-Code
  <div class="card" merge-attrs>
\end_layout

\begin_layout LyX-Code
     <h3 param="heading"><%= h this.to_s %></h3>
\end_layout

\begin_layout LyX-Code
     <div param="body"></div>
\end_layout

\begin_layout LyX-Code
   </div>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve defined a very simple 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 that uses the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
to_s
\end_layout

\end_inset

 method to give a default heading, and provides a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter that is blank by default.
 Here’s how we might use it:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h2>Discussions</h2>
\end_layout

\begin_layout LyX-Code
 <ul>
\end_layout

\begin_layout LyX-Code
   <li repeat="@discussions"> 
\end_layout

\begin_layout LyX-Code
    <card> 
\end_layout

\begin_layout LyX-Code
      <body:>
\end_layout

\begin_layout LyX-Code
        <%= this.posts.length %> posts
\end_layout

\begin_layout LyX-Code
     </body:>
\end_layout

\begin_layout LyX-Code
     </card> 
\end_layout

\begin_layout LyX-Code
    </li>
\end_layout

\begin_layout LyX-Code
 </ul>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This example (specifically, the collection created in the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<li repeat="@discussions">
\end_layout

\end_inset

 section) demonstrates that as soon as we have the concept of a card, we
 very often find ourselves wanting to render a collection of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 tags.
 The obvious next step is to capture that collection-of-cards idea as a
 reusable tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="collection"> 
\end_layout

\begin_layout LyX-Code
  <h2 param="heading"></h2>
\end_layout

\begin_layout LyX-Code
  <ul>
\end_layout

\begin_layout LyX-Code
    <li repeat>
\end_layout

\begin_layout LyX-Code
      <card param>
\end_layout

\begin_layout LyX-Code
    </li>
\end_layout

\begin_layout LyX-Code
  </ul>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection>
\end_layout

\end_inset

 tag has a straightforward 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<heading:>
\end_layout

\end_inset

 parameter, but notice that the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 tag is also declared as a parameter.
 Whenever you add 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 to a tag that itself also has parameters, you give your “super-tag” (
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection>
\end_layout

\end_inset

 in this case) the ability to customize the “sub-tag” (
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 in this case) using 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
nested parameters
\end_layout

\end_inset

.
 Here’s how we can use the nested parameters in the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection>
\end_layout

\end_inset

 tag to get the same output as the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<li repeat="@discussions">
\end_layout

\end_inset

 section in the previous example:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<collection>
\end_layout

\begin_layout LyX-Code
  <heading:>Discussions</heading>
\end_layout

\begin_layout LyX-Code
  <card:>
\end_layout

\begin_layout LyX-Code
    <body:><%= this.posts.length %>posts</body:>
\end_layout

\begin_layout LyX-Code
  </card:>
\end_layout

\begin_layout LyX-Code
</collection>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This nesting works to any depth.
 To show this, if we define an 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<index-page>
\end_layout

\end_inset

 tag that uses 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection>
\end_layout

\end_inset

 and declares it as a parameter:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="index-page">
\end_layout

\begin_layout LyX-Code
  <html>
\end_layout

\begin_layout LyX-Code
    <head> ...
 </head>
\end_layout

\begin_layout LyX-Code
    <body>
\end_layout

\begin_layout LyX-Code
      <h1 param="heading"></h1>
\end_layout

\begin_layout LyX-Code
      ...
\end_layout

\begin_layout LyX-Code
      <collection param>
\end_layout

\begin_layout LyX-Code
      ...
\end_layout

\begin_layout LyX-Code
    </body> 
\end_layout

\begin_layout LyX-Code
  </html>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
we can still access the card inside the collection inside the page:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<index-page>
\end_layout

\begin_layout LyX-Code
  <heading:>Welcome to our forum</heading:>
\end_layout

\begin_layout LyX-Code
  <collection:>
\end_layout

\begin_layout LyX-Code
    <heading:>Discussions</heading>
\end_layout

\begin_layout LyX-Code
    <card:><body:>
\end_layout

\begin_layout LyX-Code
      <%= this.posts.length %> posts
\end_layout

\begin_layout LyX-Code
    </body:></card:>
\end_layout

\begin_layout LyX-Code
  </collection:>
\end_layout

\begin_layout LyX-Code
</index-page>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Pay careful attention to the use of the trailing ’
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
:
\end_layout

\end_inset

’.
 The definition of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<index-page>
\end_layout

\end_inset

 contains a call the collection tag, written 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection>
\end_layout

\end_inset

 (no ’
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
:
\end_layout

\end_inset

’).
 By contrast, the above call to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<index-page>
\end_layout

\end_inset

 customizes the call to the collection tag that is already present inside
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<index-page>
\end_layout

\end_inset

, so we write 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<collection:>
\end_layout

\end_inset

 (with a ’
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
:
\end_layout

\end_inset

’).
 Remember:
\end_layout

\begin_layout Itemize
Without ’:’ – call a tag 
\end_layout

\begin_layout Itemize
With ’:’ – customize an existing call inside the definition
\end_layout

\begin_layout Section
Customizing and extending tags
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!extending tags
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As we’ve seen, DRYML makes it easy to define tags that are highly customizable.
 By adding 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
params
\end_layout

\end_inset

 to the tags inside your definition, the caller can insert, replace and
 tweak to their heart’s content.
 Sometimes the changes you make to a tag’s output are needed not once, but
 many times throughout the site.
 In other words, you want to define a new tag in terms of an existing tag.
\end_layout

\begin_layout Subsubsection*
New tags from old
\end_layout

\begin_layout Standard
As an example, let’s bring back our card tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="card">
\end_layout

\begin_layout LyX-Code
  <div class="card" merge-attrs>
\end_layout

\begin_layout LyX-Code
    <h3 param="heading"><%= h this.to_s %></h3>
\end_layout

\begin_layout LyX-Code
    <div param="body"></div>
\end_layout

\begin_layout LyX-Code
  </div>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now let’s say we want a new kind of card, one that has a link to the resource
 that it represents.
 Rather than redefine the whole thing from scratch, we can define the new
 card, say, “linked-card”, like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="linked-card"> 
\end_layout

\begin_layout LyX-Code
  <card>
\end_layout

\begin_layout LyX-Code
    <heading: param>
\end_layout

\begin_layout LyX-Code
      <a href="&object_url this">
\end_layout

\begin_layout LyX-Code
        <%= h this.to_s %>
\end_layout

\begin_layout LyX-Code
      </a>
\end_layout

\begin_layout LyX-Code
    </heading:>
\end_layout

\begin_layout LyX-Code
  </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
That’s all well and good but there are a couple of problems:
\end_layout

\begin_layout Itemize
The original card used 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 so that we could add arbitrary HTML attributes to the final 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

.
 Our new card has lost that feature 
\end_layout

\begin_layout Itemize
Worse than that, the new card is in fact useless, as there’s no way to pass
 it the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
body
\end_layout

\end_inset

 parameter
\end_layout

\begin_layout Standard
Let’s solve those problems in turn.
 First the attributes.
\end_layout

\begin_layout Subsubsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 again
\end_layout

\begin_layout Standard
In fact 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 works just the same on defined tags as it does on HTML tags that are output,
 so we can simply add it to the call to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

, like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="linked-card">
\end_layout

\begin_layout LyX-Code
  <card merge-attrs>
\end_layout

\begin_layout LyX-Code
    <heading: param>
\end_layout

\begin_layout LyX-Code
      <a href="&object_url this">
\end_layout

\begin_layout LyX-Code
        <%= h this.to_s %>
\end_layout

\begin_layout LyX-Code
      </a>
\end_layout

\begin_layout LyX-Code
    </heading:>
\end_layout

\begin_layout LyX-Code
  </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Now we can do things like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card class="emphasised">
\end_layout

\end_inset

, and the attribute will be passed from 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

, to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

, to the rendered 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<div>
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
Now we’ll fix the parameters, it’s going to look somewhat similar…
\end_layout

\begin_layout Subsubsection*
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-params
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!merge-params
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ll introduce 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-params
\end_layout

\end_inset

 the same way we introduced 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 – by showing how you would get by without it.
 The problem with our 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

 tag is that we’ve lost the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter.
 We could bring it back like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="linked-card">
\end_layout

\begin_layout LyX-Code
  <card merge-attrs> 
\end_layout

\begin_layout LyX-Code
    <heading: param>
\end_layout

\begin_layout LyX-Code
      <a href="&object_url this">
\end_layout

\begin_layout LyX-Code
        <%= h this.to_s %>
\end_layout

\begin_layout LyX-Code
      </a>
\end_layout

\begin_layout LyX-Code
    </heading:>
\end_layout

\begin_layout LyX-Code
    <body: param/>
\end_layout

\begin_layout LyX-Code
  </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In other words, we use the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 declaration to give 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

 a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<body:>
\end_layout

\end_inset

 parameter, which is forwarded to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

.
 But what if 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 had several parameters? We would have to list them all out.
 And what if we add a new parameter to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 later? We would have to remember to update 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

 and any other customized cards we had defined.
 Instead we use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-prams
\end_layout

\end_inset

, much as we use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="linked-card"> 
\end_layout

\begin_layout LyX-Code
  <card merge-attrs merge-params>
\end_layout

\begin_layout LyX-Code
    <heading: param>
\end_layout

\begin_layout LyX-Code
      <a href="&object_url this">
\end_layout

\begin_layout LyX-Code
        <%= h this.to_s %>
\end_layout

\begin_layout LyX-Code
      </a>
\end_layout

\begin_layout LyX-Code
    </heading:>
\end_layout

\begin_layout LyX-Code
  </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You can read 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-prams
\end_layout

\end_inset

 as: take any “extra” parameters passed to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

 and forward them all to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

.
 By “extra” parameters, we mean any that are not declared as parameters
 (via the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
param
\end_layout

\end_inset

 attribute) inside the definition of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
There are two local variables inside the tag definition that mirror the
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
attributes
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_attributes
\end_layout

\end_inset

 variables described previously:
\end_layout

\begin_layout Itemize
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!parameters local variable
\end_layout

\end_inset


\end_layout

\end_inset

 a hash containing all the “extra” parameters (those that do not match a
 declared parameter name) 
\end_layout

\begin_layout Itemize
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!all_parameters local variable
\end_layout

\end_inset


\end_layout

\end_inset

 a hash containing all the parameters passed to the tag
\end_layout

\begin_layout Standard
The values in these hashes are Ruby 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
procs
\end_layout

\end_inset

.
 One common use of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_parameters
\end_layout

\end_inset

 is to test if a certain parameter was passed or not:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<if test="&all_parameters[:body]">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In fact, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_parameters
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
parameters
\end_layout

\end_inset

 are not regular hashes, they are instances of a subclass of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Hash
\end_layout

\end_inset

 – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Hobo::Dryml::TagParameters
\end_layout

\end_inset

.
 This subclass allows parameters to be called as if they were methods on
 the hash object, e.g.:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
parameters.default
\end_layout

\end_inset


\end_layout

\begin_layout Standard
That’s not something you’ll use often.
\end_layout

\begin_layout Subsubsection*
Merge
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Merge
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As it’s very common to want both 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-prams
\end_layout

\end_inset

 on the same tag, there is a shorthand for this: 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge
\end_layout

\end_inset

.
 So the final, preferred definition of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<linked-card>
\end_layout

\end_inset

 is:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="linked-card"> 
\end_layout

\begin_layout LyX-Code
  <card merge>
\end_layout

\begin_layout LyX-Code
    <heading: param>
\end_layout

\begin_layout LyX-Code
      <a href="&object_url this">
\end_layout

\begin_layout LyX-Code
        <%= h this.to_s %>
\end_layout

\begin_layout LyX-Code
      </a>
\end_layout

\begin_layout LyX-Code
    </heading:>
\end_layout

\begin_layout LyX-Code
  </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Merging selected parameters
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Selectively merging parameters
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Just as with 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-attrs
\end_layout

\end_inset

, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge-prams
\end_layout

\end_inset

 can be given a value - either a hash containing the parameters you wish
 to merge, or a list of parameter names (comma separated), to be merged
 from the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
all_parameters
\end_layout

\end_inset

 variable.
\end_layout

\begin_layout Standard
Examples:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<card merge-params="heading, body"> 
\end_layout

\begin_layout LyX-Code
<card merge-params="&my_parameter_hash">
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Extending a tag
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Extending a tag
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve now seen how to easily create a new tag from an existing tag.
 But what if we don’t actually want a new tag, but rather we want to change
 the behavior of an existing tag in some way, and keep the tag name the
 same.
 What we can’t do is simply use the existing name in the definition:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<!-- DOESN'T WORK! -->
\end_layout

\begin_layout Code
<def tag="card"> 
\end_layout

\begin_layout Code
  <card merge>
\end_layout

\begin_layout Code
    <heading: param>
\end_layout

\begin_layout Code
      <a href="&object_url this"><%= h this.to_s %></a>
\end_layout

\begin_layout Code
    </heading:>
\end_layout

\begin_layout Code
  </card>
\end_layout

\begin_layout Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
All we’ve done there is created a nice stack overflow when the card calls
 itself over and over.
 Fortunately, DRYML has support for extending tags.
 Use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<extend>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<extend>
\end_layout

\end_inset


\end_layout

\end_inset

 instead of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<extend tag="card">
\end_layout

\begin_layout Code
  <old-card merge>
\end_layout

\begin_layout Code
    <heading: param>
\end_layout

\begin_layout Code
      <a href="&object_url this"><%= h this.to_s %></a>
\end_layout

\begin_layout Code
    </heading:>
\end_layout

\begin_layout Code
  </old-card>
\end_layout

\begin_layout Code
</extend>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The one thing to notice there is that the “old” version of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

, i.e.
 the one that was active before you’re extension, is available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<old-card>
\end_layout

\end_inset

.
 That’s about all there is to it.
 Here’s another example where we add a footer to every page in our application.
 It’s very common to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<extend tag="page">
\end_layout

\end_inset

 in your 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
application.dryml
\end_layout

\end_inset

, in order to make changes that should appear on every page:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<extend tag="page">
\end_layout

\begin_layout LyX-Code
   <old-page merge>
\end_layout

\begin_layout LyX-Code
     <footer: param> 
\end_layout

\begin_layout LyX-Code
      ...
 
\end_layout

\begin_layout LyX-Code
       your custom footer here
\end_layout

\begin_layout LyX-Code
       ...
 
\end_layout

\begin_layout LyX-Code
    </footer:>
\end_layout

\begin_layout LyX-Code
   </old-page>
\end_layout

\begin_layout LyX-Code
</extend>
\end_layout

\end_inset


\end_layout

\begin_layout Section
Aliasing tags
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Aliasing tags
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Welcome to the shortest section of The DRYML Guide…
\end_layout

\begin_layout Standard
If you want to create an alias of a tag; i.e., an identical tag with a different
 name:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="my-card" alias-of="card"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that it is a self-closing tag–there is no body to the definition.
\end_layout

\begin_layout Standard
So… that’s aliasing tags then…
\end_layout

\begin_layout Section
Polymorphic tags
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Polymorphic tags
\end_layout

\end_inset


\end_layout

\begin_layout Standard
DRYML allows you to define a whole collection of tags that share the same
 name, where each definition is appropriate for a particular type of object
 being rendered.
 When you call the tag, the type (i.e.
 class) of the context is used to determine which definition to call.
 These are called polymorphic tags.
\end_layout

\begin_layout Standard
To illustrate how these work, let’s bring back our simple 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 tag once more:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="card" polymorphic>
\end_layout

\begin_layout LyX-Code
  <div class="card" merge-attrs>
\end_layout

\begin_layout LyX-Code
    <h3 param="heading"><%= h this.to_s %></h3> 
\end_layout

\begin_layout LyX-Code
    <div param="body">
\end_layout

\begin_layout LyX-Code
    </div>
\end_layout

\begin_layout LyX-Code
  </div>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We’ve added the polymorphic attribute to the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

.
 This tells DRYML that 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 can have many definitions, each for a particular type.
 The definition we’ve given here is called the “base” definition or the
 “base card”.
 The base definition serves two purposes:
\end_layout

\begin_layout Itemize
It is the fallback if we call 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 and no definition is found for the current type.
 
\end_layout

\begin_layout Itemize
The type-specific definition can use the base definition as a starting point
 to be further customized.
\end_layout

\begin_layout Standard
To add a type-specific 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

, we use the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
for
\end_layout

\end_inset

 attribute on the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<def>
\end_layout

\end_inset

.
 For example, a card for a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Product
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="card" for="Product"> ...
 </def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Description
Note: If the name in the for attribute starts with an uppercase letter,
 it is taken to be a class name.
 Otherwise it is taken to be an abbreviated name registered with HoboFields;
 e.g.:
\end_layout

\begin_layout Plain Layout
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="input" for="email_address">
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
For the product card, lets make the heading be a link to the product, and
 put the price of the product in the body area:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<def tag="card" for="Product">
\end_layout

\begin_layout Code
   <card merge>
\end_layout

\begin_layout Code
     <heading: param>
\end_layout

\begin_layout Code
       <a href="#{object_url this}"><%= h this.to_s %></a>
\end_layout

\begin_layout Code
     </heading:>
\end_layout

\begin_layout Code
     <body: param="price">$<%= this.price %></body:>
\end_layout

\begin_layout Code
   </card>
\end_layout

\begin_layout Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
We call this a type-specific definition.
 Some points to notice:
\end_layout

\begin_layout Itemize
The callback to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<card>
\end_layout

\end_inset

 is not a recursive loop, but a call to the base definition.
 
\end_layout

\begin_layout Itemize
We’re using the normal technique for customizing / extending an existing
 card; i.e., we’re using 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
merge
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
It is not required for the type-specific definition to call the base definition,
 it’s just often convenient.
 In fact the base definition is not required.
 It is valid to declare a polymorphic tag with no content:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="my-tag" polymorphic/>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Type hierarchy
\end_layout

\begin_layout Standard
If, for a given call, no type-specific definition is available for 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this.class
\end_layout

\end_inset

, the search continues with 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this.class.superclass
\end_layout

\end_inset

 and so on up the superclass chain.
 If the search reaches either 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
ActiveRecord::Base
\end_layout

\end_inset

 or 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
Object
\end_layout

\end_inset

, the base definition is used.
\end_layout

\begin_layout Subsubsection*
Specifying the type explicitly
\end_layout

\begin_layout Standard
Sometimes it is useful to give the type explicitly for the call explicitly
 (i.e., to override the use of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
this.class
\end_layout

\end_inset

).
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
for-type
\end_layout

\end_inset

 attribute (on the call) provides this facility.
 For example, you might want to implement one type-specific definition in
 terms of another:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="card" for="SpecialProduct">
\end_layout

\begin_layout LyX-Code
   <card for-type="Product">
\end_layout

\begin_layout LyX-Code
     <append-price:>Today Only!)</append-price:>
\end_layout

\begin_layout LyX-Code
   </card>
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Extending polymorphic tags
\end_layout

\begin_layout Standard
Type-specific definitions can be extended just like any other tag using
 the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<extend>
\end_layout

\end_inset

 tag.
 For example, here we simply remove the price:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<extend tag="card" for="Product"> 
\end_layout

\begin_layout LyX-Code
  <old-card merge without-price/> 
\end_layout

\begin_layout LyX-Code
</extend>
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Wrapping content
\end_layout

\end_inset

Wrapping content
\end_layout

\begin_layout Standard
DRYML provides two mechanisms for wrapping existing content inside new tags.
\end_layout

\begin_layout Subsubsection*
Wrapping 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
inside
\end_layout

\end_inset

 a parameter
\end_layout

\begin_layout Standard
Once or twice in the previous examples, we have extended our card tag definition
, replacing the plain heading with a hyperlink heading.
 Here is an example call to our extended card tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<card> 
\end_layout

\begin_layout LyX-Code
  <heading:>
\end_layout

\begin_layout LyX-Code
    <a href="#{object_url this}"><%= h this.to_s %></a>
\end_layout

\begin_layout LyX-Code
  </heading:> 
\end_layout

\begin_layout LyX-Code
</card>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
There’s a bit of repetition there – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<%= h this.to_s %>
\end_layout

\end_inset

 was already present in the original definition.
 All we really wanted to do was wrap the existing heading in an 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

.
 In this case there wasn’t much markup to repeat, so it wasn’t a big deal,
 but in other cases there might be much more.
\end_layout

\begin_layout Standard
We can’t use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<prepend-heading:><a></prepend-heading:>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<append-heading:></a></append-heading:>
\end_layout

\end_inset

 because that’s not well formed markup (and is very messy besides).
 Instead, DRYML has a specific feature for this situation.
 The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<param-content>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<param-content>
\end_layout

\end_inset


\end_layout

\end_inset

 tag is a special tag that brings back the default content for a parameter.
\end_layout

\begin_layout Standard
Here’s how it works:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<card> 
\end_layout

\begin_layout LyX-Code
  <heading:> 
\end_layout

\begin_layout LyX-Code
    <a href="#{object_url this}">
\end_layout

\begin_layout LyX-Code
      <param-content for="heading"/>
\end_layout

\begin_layout LyX-Code
    </a> 
\end_layout

\begin_layout LyX-Code
  </heading:> 
\end_layout

\begin_layout LyX-Code
</card>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
That’s the correct way to wrap inside the parameter, so in this case the
 output is:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<h3><a href="...">Fried Bananas</a></h3>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
What if we wanted to wrap the entire 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<heading:>
\end_layout

\end_inset

 parameter, including the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h3>
\end_layout

\end_inset

 tags?
\end_layout

\begin_layout Subsubsection*
Wrapping 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
outside
\end_layout

\end_inset

 a parameter
\end_layout

\begin_layout Standard
For example, we might want to give the card a new ‘header’ section, that
 contained the heading, and the time the record was created, like this:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<div class="header"> 
\end_layout

\begin_layout LyX-Code
  <h3>Fried Bananas</h3> 
\end_layout

\begin_layout LyX-Code
  <p>Created: ....</p> 
\end_layout

\begin_layout LyX-Code
</div>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To use DRYML terminology, what we’ve done there is 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
replaced
\end_layout

\end_inset

 the entire heading with some new content, and the new content happens to
 contain the original heading.
 So we replaced the heading, and then restored it again, which in DRYML
 is written:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<card>
\end_layout

\begin_layout LyX-Code
  <heading: replace> 
\end_layout

\begin_layout LyX-Code
    <div class="header">
\end_layout

\begin_layout LyX-Code
      <heading: restore/> 
\end_layout

\begin_layout LyX-Code
      <p>Created: <%= this.created_at.to_s(:short) %></p>
\end_layout

\begin_layout LyX-Code
    </div>
\end_layout

\begin_layout LyX-Code
  </heading:>
\end_layout

\begin_layout LyX-Code
</card>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To summarize: 
\end_layout

\begin_layout Itemize
To wrap content inside a parameter, use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<param-content/>
\end_layout

\end_inset

 
\end_layout

\begin_layout Itemize
To wrap an entire parameter, including the parameterized tag itself (the
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<h3>
\end_layout

\end_inset

 in our examples), use the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
replace
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
restore
\end_layout

\end_inset

 attributes.
\end_layout

\begin_layout Section
Local and scoped variables
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!scoped variables
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
DRYML provides two tags for setting variables: 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<set>
\end_layout

\end_inset


\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set-scoped>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<set-scoped>
\end_layout

\end_inset


\end_layout

\end_inset

.
\end_layout

\begin_layout Subsubsection*
Setting local variables with 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Sometimes it’s useful to define a local variable inside a template or a
 tag definition.
 It’s worth avoiding if you can, as we don’t really want our view layer
 to contain lots of low-level code, but sometimes it’s unavoidable.
 Because DRYML extends ERB, you can simply write:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<% total = price_of_fish * number_of_fish %>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For purely aesthetic reasons, DRYML provides a tag that does the same thing:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<set total="&price_of_fish * number_of_fish"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that you can put as many attribute/value pairs as you like on the same
 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set>
\end_layout

\end_inset

 tag, but the order of evaluation is not defined.
\end_layout

\begin_layout Subsubsection*
Scoped variables – 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set-scoped>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Scoped variables (which is not a great name, we realize as we come to document
 them properly) are kind of like global variables with a limited lifespan.
 We all know the pitfalls of global variables, and DRYML’s scoped variables
 should indeed be used as sparingly as possible, but you can pull off some
 very useful tricks with them.
\end_layout

\begin_layout Standard
The 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set-scoped>
\end_layout

\end_inset

 tag is very much like 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set>
\end_layout

\end_inset

 except you open it up and put DRYML inside it:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<set-scoped xyz="&..."> ...
 </set-scoped>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The value is available as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
scope.xyz
\end_layout

\end_inset

 anywhere inside the tag 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
and in any tags that are called inside that tag
\end_layout

\end_inset

.
 That’s the difference between 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set-scoped>
\end_layout

\end_inset

.
 
\end_layout

\begin_layout Standard
They are like 
\begin_inset Flex Emph
status collapsed

\begin_layout Plain Layout
dynamic variables
\end_layout

\end_inset

 from LISP.
 To repeat the point, they are like global variables that exist from the
 time the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<set-scope>
\end_layout

\end_inset

 tag is evaluated, and for the duration of the evaluation of the body of
 the tag, and are then removed.
\end_layout

\begin_layout Standard
As an example of their use, let’s define a simple tag for rendering navigation
 links.
 The output should be a list of 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

 tags, and the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

 that represents the “current” page should have a CSS class “current”, so
 it can be highlighted in some way by the stylesheet.
 (In fact, the need to create a reusable tag like this is where the feature
 originally came from).
\end_layout

\begin_layout Standard
On our pages, we’d like to simply call, say:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<main-nav current="Home">
\end_layout

\end_inset


\end_layout

\begin_layout Standard
And we’d like it to be easy to define our own 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<main-nav>
\end_layout

\end_inset

 tag in our applications: 
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="main-nav"> 
\end_layout

\begin_layout LyX-Code
  <navigation merge-attrs> 
\end_layout

\begin_layout LyX-Code
    <nav-item href="...">Home</nav-item>
\end_layout

\begin_layout LyX-Code
    <nav-item href="...">News</nav-item>
\end_layout

\begin_layout LyX-Code
    <nav-item href="...">Offers</nav-item>
\end_layout

\begin_layout LyX-Code
  </navigation> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Here’s the definition for the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="navigation" attrs="current">
\end_layout

\begin_layout LyX-Code
  <set-scoped current-nav-item="current"> 
\end_layout

\begin_layout LyX-Code
    <ul merge-attrs param="default"/>
\end_layout

\begin_layout LyX-Code
  </set-scoped> 
\end_layout

\begin_layout LyX-Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
All 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 does is set a scoped-variable to whatever was given as current and output
 the body wrapped in a 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<ul>
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
Here’s the definition for the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<nav-item>
\end_layout

\end_inset

 tag:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Code
<def tag="nav-item"> 
\end_layout

\begin_layout Code
  <set body="&parameters.default"/> 
\end_layout

\begin_layout Code
  <li class="#{'current' if scope.current_nav_item == body}"> 
\end_layout

\begin_layout Code
    <a merge-attrs><%= body %></a>
\end_layout

\begin_layout Code
  </li> 
\end_layout

\begin_layout Code
</def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The content inside the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<nav-item>
\end_layout

\end_inset

 is compared to 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
scope.current_nav_item
\end_layout

\end_inset

.
 If they are the same, the “current” class is added.
 Also note the way 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
parameters.default
\end_layout

\end_inset

 is evaluated and the result stored in the local variable 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
body
\end_layout

\end_inset

, in order to avoid evaluating the body twice.
\end_layout

\begin_layout Subsubsection*
Nested scopes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Nested scoped variables
\end_layout

\end_inset


\end_layout

\begin_layout Standard
One of the strengths of scoped variables is that scopes can be nested, and
 where there are name clashes, the parent scope variable is temporarily
 hidden, rather than overwritten.
 With a bit of tweaking, we could use this fact to extend our 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 tag to support a sub-menu of links within a top level section.
 The sub-menu could also use 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<navigation>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<nav-item>
\end_layout

\end_inset

 and the two 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
scope.current_nav_item
\end_layout

\end_inset

 variables would not conflict with each other.
\end_layout

\begin_layout Section
Taglibs
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DRYML!Taglibs
\end_layout

\end_inset


\end_layout

\begin_layout Standard
DRYML provides the 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<include>
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tags!<include>
\end_layout

\end_inset


\end_layout

\end_inset

 tag to support breaking up lots of tag definitions into separate “tag libraries
”, known as taglibs.
 You can call 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<include>
\end_layout

\end_inset

 with several different formats:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<include src="foo"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Load foo.dryml from the same directory as the current template or taglib.
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<include src="path/to/foo"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Load 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
app/views/path/to/foo.dryml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<include src="foo" plugin="path/to/plugin"/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Load 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
vendor/plugins/path/to/plugin/taglibs/foo.dryml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
When running in development mode, all of these libraries are automatically
 reloaded on every request.
\end_layout

\begin_layout Section
Divergences from XML and HTML
\end_layout

\begin_layout Subsubsection*
Self-closing tags
\end_layout

\begin_layout Standard
In DRYML, 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<foo:/>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<foo:></foo:>
\end_layout

\end_inset

 have two slightly different meanings.
 The second form replaces the parameter’s default inner content with the
 specified content: nothing in this case.
\end_layout

\begin_layout Standard
The first form uses the parameters default inner content unchanged.
\end_layout

\begin_layout Standard
This is very useful if you wish to add an attribute to a parameter but leave
 the inner content unchanged.
 In this example:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<def tag="bar"> 
\end_layout

\begin_layout LyX-Code
  <div class="container" merge-attrs> 
\end_layout

\begin_layout LyX-Code
    <p class="content" param> Hello </p> 
\end_layout

\begin_layout LyX-Code
  </div> 
\end_layout

\begin_layout LyX-Code
<def>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Then:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<bar><foo: class="my-foo"/></bar> 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Gives:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<div class="container"> 
\end_layout

\begin_layout LyX-Code
  <p class="content my-foo"> Hello </p> 
\end_layout

\begin_layout LyX-Code
</div>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you used:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<bar><foo: class="my-foo"></foo:></bar>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You would get:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<div class="container"><p class="content my-foo"></p></div>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Colons in tag names
\end_layout

\begin_layout Standard
In XML, colons are valid inside tag and attribute names.
 However they are reserved for “experiments for namespaces”.
 So it’s possible that we may be non-compliant with the not-yet-existent
 XML 2.0.
\end_layout

\begin_layout Subsubsection*
Close tag shortcuts
\end_layout

\begin_layout Standard
In DRYML, you’re allowed to close tags with everything preceding the colon:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<view:name> Hello </view>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
XML requires the full tag to be specified:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<view:name> Hello </view:name>
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection*
Null end tags
\end_layout

\begin_layout Standard
Self-closing tags are 
\begin_inset CommandInset href
LatexCommand href
name "technically illegal"
target "http://www.w3.org/TR/html401/intro/sgmltut.html#h-3.2.1"

\end_inset

 in HTML.
 So 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<br />
\end_layout

\end_inset

 is technically not valid HTML.
 However, browsers do parse it as you expect.
 It is valid XHTML, though.
\end_layout

\begin_layout Standard
However, browsers only do this for empty elements.
 So tags such as 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<script>
\end_layout

\end_inset

 and 
\begin_inset Flex Code
status collapsed

\begin_layout Plain Layout
<a>
\end_layout

\end_inset

 require a separate closing tag in HTML.
 This behavior has surprised many people: 
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<script src="foobar.js" />
\end_layout

\end_inset


\end_layout

\begin_layout Standard
…is not recognized in many web browsers for this reason.
 You must use:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<script src="foorbar.js"></script>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
…in HTML instead.
\end_layout

\begin_layout Standard
DRYML follows the XML conventions:
\end_layout

\begin_layout Standard
\begin_inset Box Shadowbox
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout LyX-Code
<a/>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
…is valid DRYML.
\end_layout

\begin_layout Standard

\end_layout

\end_body
\end_document