MasterView template processing directives are encoded in an (x)html template using attribute markup. A MasterView directive is an element attribute in the mv: namespace. By convention, Masterview directive attribute names use lower-case letters with underscore as a separator, e.g., mv:generate, mv:link_to.
Note: use of the mv: namespace used for MasterView directives in an (x)html template can be modified by a configuration setting. See the MasterView Configuration Guide for details. However, we recommend that you do not change this namespace convention unless truly necessary - it's easier to understand your templates when they follow the standard markup convention.
MasterView provides a number of built-in directives for general use. You can also create your own custom directives to extend the power of the MasterView template processing with markup notation and processing directives that support standard uses for your particular application.
MasterView supports several standard keywords derived from information about the template file being processed that can be used in attribute values for the mv:generate and mv:gen_partial directives.
{template_path} == use original masterview template path with default output extension (one/foo/bar.rhtml)
{template_path}.ext == use original masterview template path with the specified extension (one/foo/bar.ext)
{template_dir_path} == direct_parent_dirname (one/foo)
{template_basename} == base filename (bar)
{extension} == filename extension (.html)
A typical use would be to specify the generated output for the main content
of a template one/two/foo.html with the directive
mv:generate="{template_path}".
This keyword notation avoids the need to replicate the template's own file name or
it's relative path within the Rails app/views directory in the
directive markup in the template.
Typically MasterView template files will contain mv:generate or mv:gen_partial directives to tell MasterView where to output the rendered rhtml. However if none are found in the template file, MasterView will automatically add in a mv:generate="{template_path}" to the body tag if found otherwise the root element. Additionally if MasterView was adding this to the body tag, it will add in a mv:omit_tag="" which will prevent the body tag from being included in the generated output. If you wish to disable this default generate mechanism, set the config.default_parser_options[:default_generate] = false in your masterview settings or environments files.
| Template Processing Directives | |
| mv:generate | Generate output containing this element and its children |
| mv:import | Design-time directive to mark a snapshot of generated code |
| mv:gen_partial | Generate a Rails partial |
| mv:import_render | Design-time directive to mark a snapshot of generated partial code |
| mv:gen_replace | Used with mv:generate to replace the content of this element in the generated output with the value of the attribute |
| General Processing Directives | |
| mv:attr | Replaces attribute value(s) on this element with the value of an expression |
| mv:content | Replaces the content of this element with the value of the expression |
| mv:omit_tag | Omits this element from the generated output if the value is empty or evaluates to true |
| mv:replace | Replaces this element and its content with the value of the expression |
| Erb and Control Flow Directives | |
| mv:block | Expands to the equivalent rhtml (erb) block code around this element |
| mv:eval | Inserts an rhtml evaluation expression for the attribute value prior to this element |
| mv:if | Wraps this element with an if... end block using the attribute contents for the condition |
| mv:elsif | Used in conjunction with the mv:if directive to allow you to create if... elsif... end blocks |
| mv:else | Used in conjunction with the mv:if and mv:elsif directives to allow you to create if... elsif... else... end blocks |
| Inline Erb substitutions | Inline substitution notation for Erb expressions |
| Rails Asset and Link Helper Directives | |
| mv:image_tag | Replaces this element using the Rails image_tag helper.
(
Used on <img> elements
)
|
| mv:javascript_include | Replaces this element using the Rails javascript_include_tag helper.
(
Used on <script> element in html header section
)
|
| mv:link_to | Replaces this element using the Rails link_to helper.
(
Used on <a> link elements
)
|
| mv:link_to_function | Replaces this element using the Rails link_to_function helper which creates a link which calls a JavaScript function.
(
Used on <a> link elements
)
|
| mv:link_to_if | Replaces this element using the Rails link_to_if helper
(
Used on <a> link elements
)
|
| mv:link_to_remote | Replaces this element using the Rails link_to_remote helper
(
Used on <a> link elements
)
|
| mv:stylesheet_link | Replaces this element using the Rails stylesheet_link_tag helper
(
Used on stylesheet <link> elements in html header section
)
|
| Rails Form Helper Directives | |
| mv:check_box | Replaces this element with a Rails check_box helper |
| mv:collection_select | Replaces this element with a Rails collection_select helper.
(
Used on <select> form elements
)
|
| mv:form | Replaces the start and end tags of this element using the Rails form_tag helper and closing form tag |
| mv:form_remote | Replaces the start and end tags of this element using the Rails form_remote_tag helper and a closing form tag for Ajax-enabled form submission using the Prototype library |
| mv:hidden_field | Replaces this element with a hidden input element using the Rails hidden_tag helper.
(
Used on <input> form elements
)
|
| mv:password_field | Replaces this element with a password input element using the Rails password_field helper.
(
Used on <input> form elements
)
|
| mv:radio_button | Replaces this element with a Rails radio_button helper.
(
Used on <input> form elements
)
|
| mv:select | Replaces this element with a Rails select helper.
(
Used on <select> form elements
)
|
| mv:submit | Replaces this element with a submit input element using the Rails submit_tag helper.
(
Used on <input> form elements
)
|
| mv:text_area | Replaces this element with a textarea input element using the Rails text_area helper.
(
Used on <textarea> form elements
)
|
| mv:text_field | Replaces this element with a text input element using the Rails text_field helper.
(
Used on <input> form elements
)
|
Directives Index (alphabetical)
mv:generate="layouts/product.rhtml"
When the generate directive is encountered it creates a new output rhtml file where this element and its
children will be rendered. It also will suspend outputting to any previous output file until it is done with this
one (nested). MasterView will not output any rhtml files unless it encouters one of these or mv:gen_partial directive
below. Typically you will have one of these in the very top html element to generate the layout, and you will have
additional directives further inside to output different view partials and forms. MasterView takes this one html
file and generates all the other layout, forms, and partials that you would do manually. for example...
<html mv:generate="layouts/product.rhtml">
<title>Hello</title>
<body>
<div mv:replace="@content_for_layout">
<div mv:generate="product/new.rhtml">
<form></form>
</div>
</div>
</body>
</html>
outputs to two files
app/views/layouts/product.rhtml
<html>
<title>Hello</title>
<body>
<%= @content_for_layout %>
</body>
</html>
app/views/product/new.rhtml
<div>
<form></form>
</div>
mv:import="layouts/product.rhtml"
When the import directive is used, it is a mirror image of the generate directive, except that this directive
doesn't generate any output, it is only used for design time editing. The code inside this tag represents a point
in time capture of the real generated code and if it ever gets out of sync it can easily be sync'd back up by
visiting the MasterView admin page or using rake mv:rebuild_all
mv:gen_partial=":partial => ‘product/form’"
This directive does two things it creates a partial and it outputs the appropriate code to render this
partial in the parent output file before beginning output of the partial. It calculates the file name from the
:partial value and appends .rhtml for example...
<html mv:generate="layouts/product.rhtml">
<body>
<div mv:gen_partial=":partial => 'product/show'">
Name: <span class="static" mv:content="h @product.send(:name)">product Name dummy text</span>
Description: <span class="static" mv:content="h @product.send(:description)">product description dummy text</span>
</div>
</body>
</html>
outputs two files
app/views/layouts/product.rhtml
<html>
<body>
<%= render :partial => 'product/show' %>
</body>
</html>
app/views/product/_show.rhtml
<div>
Name: <span class="static"><%= h @product.send(:name) %></span>
Description: <span class="static"><%= h @product.send(:description) %></span>
</div>
You can also use collections with your partials like
<div mv:gen_partial=":partial => 'shared/product', :collection => @products">
which will create the partial shared/_product.rhtml and will render this partial over a collection
mv:import_render="partial => ‘product/form’"
Similar to how import directive is a mirror to generate, import_render is a mirror to gen_partial. This directive
generates the appropriate render partial helper, but doesn't generate any additional output, it is only used for
design time editing and can be easily sync'd up if it ever gets out of sync with the original code.
mv:gen_replace="whatToLeave"
When used in conjunction with mv:generate directive it causes the value of the attribute to be erb
executed output in the parent file before transferring to the child (nested) output file. for example...
<html mv:generate="layouts/product.rhtml">
<title>Hello</title>
<body>
<div mv:generate="product/new.rhtml" mv:gen_replace="@content_for_layout>
<form></form>
</div>
</body>
</html>
outputs two files
app/views/layouts/product.rhtml
<html>
<title>Hello</title>
<body>
<%= @content_for_layout %>
</body>
</html>
app/views/product/new.rhtml
<div>
<form></form>
</div>
mv:attr=":foo => ‘bar’, :cat => #{h product.name}"
At runtime this sets attribute values on the element this directive is defined on, for example...
<div mv:attr=":foo => 'bar', :hi => 'cat'">hello</div>
becomes
<div foo="bar" hi="cat">hello</div>
You can put erb evaluated code in #{ } like in this example
<div mv:attr=":foo => #{h product.name}, :hi => 'cat'">hello</div>
becomes
<div foo="<%= h product.name %>" hi="cat">hello</div>
mv:content="foo"
Replaces the content of the tag with the erb output of foo, for example...
<div mv:content="foo">some dummy html here</div>
becomes
<div><%= foo %></div>
mv:omit_tag="evalString"
Omit the element tag if the evalString is empty or evaluates to true. For example...
<span mv:omit_tag="">hello</span>
becomes
hello
<span mv:omit_tag="@test">hello</span>
becomes
<% if @test %><span><% end %>hello<% if @test %></span><% end %>
mv:replace="foo bar"
Replaces the tag and contents with the erb executed output of the attribute. If the attribute
value is an empty string then the tag is simply removed and nothing is output, for example...
<span mv:replace="h product.name">dummy product name</span>
becomes
<%= h product.name %>
and similarly, you can use this to remove dummy html which was there for prototyping/demoing
<table>
other rows here
<tr mv:replace="">
<td>foo</td>
<td>bar</td>
</tr>
</table>
becomes
<table>
other rows here
</table>
Passing in an empty attribute simply eliminated the tag, children, and contents
mv:block="rubyBlockCodeHere"
At runtime this expands to the equivalent rhtml (erb) block code around this element, for example...
<div mv:block="products.each do |product|">foobar</div>
becomes
<% products.each do |product| %>
<div>foobar</div>
<% end %>
Note how MasterView automatically put in the 'end' after the closing tag.
Another example using the brace form of a block
<div mv:block="products.each { |product|">foobar</div>
becomes
<% products.each { |product| %>
<div>foobar</div>
<% } %>
Its all based on the ruby and rails syntax while keeping things xhtml and designer friendly.
mv:eval="rubyExpression"
At runtime this causes an rhtml evaluation expression for the attribute value
to be inserted into the output preceding this element, for example...
<table mv:eval="num_alerts = 0">
... some table content here ...
</table>
becomes
<% num_alerts = 0 %>
<table>
... some table content here ...
</table>
mv:if="yourIfConditionHere"
Wraps the tag with an if block using the attribute contents for the condition, for example...
<div mv:if="@flash[:notice]">foo</div>
becomes
<% if @flash[:notice] %>
<div>foo</div>
<% end %>
And combining if and content directives we can do the following
<div mv:if="@flash[:notice]" mv:content="@flash[:notice]" class="messages">
dummy notice message here
</div>
becomes
<% if @flash[:notice] %>
<div>
<%= @flash[:notice] %>
</div>
<% end %>
mv:elsif="yourElseConditionHere"
Used in conjunction with an if directive allows you to create if, elsif blocks, for example...
<div mv:if="foo()">
hello
</div>
<div mv:elsif="bar()">
world
</div>
becomes
<% if foo() %>
<div>
hello
</div>
<% elsif bar() %>
<div>
world
</div>
<% end %>
Note that the elsif directive element needs to follow the if element's closing tag
mv:else=""
Used in conjunction with if and elsif, allows you to create if, elseif, else blocks, for example...
<div mv:if="@foo">
hello
</div>
<div mv:else="">
world
</div>
becomes
<% if @foo %>
<div>
hello
</div>
<% else %>
<div>
world
</div>
<% end %>
Inline substitutions
Since <%= foobar %> and <% foo %> are invalid xhtml values, MasterView has an inline substitution to
replace these for the cases when you simply want to inject something. {{{ gets replaced with <%
and {{{= gets replaced with <%= also }}} gets replaced with %> If you instead want to use the
old <% syntax instead, MasterView by default is setup to perform a substitution on those values before
parsing. However to be safe you should use the xhtml safe syntax otherwise html editors might end
up changing things on you.
{{{= foobar }}}
becomes
<%= foobar %>
and
{{{ foo }}}
becomes
<% foo %>
mv:image_tag="cat.jpg"
Replaces the tag with a image_tag helper, size is determined by width and height, other html attributes
are passed through. for example...
<img src="../../../public/images/cat.jpg" mv:image_tag="cat.jpg"/>
becomes
<%= image_tag 'cat.jpg' %>
<img src="../../../public/images/cat.jpg" alt="my cat" width="20" height="10" mv:image_tag="cat.jpg"/>
becomes
<%= image_tag 'cat.jpg', :alt => 'my cat', :height => 10, :width => 20 %>
Also if path isn't specified in the mv:image_tag attribute value then it will infer the path looking
for what follows the public/images/ in the src atttribute, like so
<img src="../../../public/images/cat.jpg" mv:image_tag=""/>
becomes
<%= image_tag 'cat.jpg' %>
This is useful to allow images to be used for demos/prototypes and then at runtime
use the appropriate asset using the rails helper.
mv:javascript_include="prototype.js"
Replaces the tag with a javascript_include_tag helper, for example...
<script type="text/javascript" src="../../../public/javascripts/prototype.js"
mv:javascript_include="prototype.js"></script>
becomes
<%= javascript_include_tag 'prototype.js' %>
You can also use a symbol
<script type="text/javascript" src="../../../public/javascripts/prototype.js"
mv:javascript_include=":defaults"></script>
becomes
<%= javascript_include_tag :defaults %>
And you can have the path inferred from the src path (uses the relative path to public/javascripts)
<script type="text/javascript" src="../../../public/javascripts/prototype.js"
mv:javascript_include=""></script>
becomes
<%= javascript_include_tag 'prototype.js' %>
This is useful to allow scripts to be used for demos/prototypes and then at runtime
use the appropriate asset using the rails helper.
mv:link_to="linkToOptions"
Replaces the tag with a link_to helper, it uses the contents of the tag for the name of the link,
so the name of the link can be changed by the html designer and it gets used in the appropriate place
in the helper, for example...
<a mv:link_to=":action => 'new'">New product</a>
becomes
<%= link_to 'New product', :action => 'new' %>
mv:link_to_function="mv:link_to_if="function, options""
Replaces the tag with a link_to_function helper. The attribute values
contains the function to call, along with optional keyword arguments
to pass to the link_to_function helper. The content of the element
is used as the function name.
### todo: add example here ###
mv:link_to_if="linkToIfConditionAndOption"
Replaces the tag with a link_to_if helper, uses the contents of the tag for the name of the
link so the name of the link can be changed by the html designer and it gets used in the appropriate
place in the helper, for example...
<a mv:link_to_if="@product_pages.current.previous, { :page => @product_pages.current.previous }"Previous page"</a>
becomes
<%= link_to_if @product_pages.current.previous, 'Previous page', {:page => @product_pages.current.previous } %>
mv:link_to_remote="linkToRemoteOptions"
Replaces the tag with a link_to_remote helper, uses the contents of the tag for the name of the
link so the name of the link can be changed by the html designer and it gets used in the appropriate
place in the helper, for example...
<a mv:link_to_remote=":action => 'new'">New product</a>
becomes
<%= link_to_remote 'New product', :action => 'new' %>
mv:stylesheet_link="style"
Replaces the tag with a stylesheet_link_tag helper, for example...
<link rel="stylesheet" type="text/css" href="../../../public/stylesheets/scaffold.css" mv:stylesheet_link="scaffold"/>
becomes
<%= stylesheet_link_tag "scaffold" %>
You may also leave attribute empty and it will infer the path from src (uses relative path from public/stylesheets)
<link rel="stylesheet" type="text/css" href="../../../public/stylesheets/scaffold.css" mv:stylesheet_link=""/>
becomes
<%= stylesheet_link_tag "scaffold.css" %>
This is useful to allow style to be used for demos/prototypes and then at runtime
use the appropriate asset using the rails helper.
mv:check_box="product, name"
Replaces this element with the check_box helper. It quotes the object and name if necessary, and merges any
html attributes into options if supplied
<input type="checkbox" mv:check_box="product, name"/>
becomes
<% check_box 'product', 'name' %>
and
<input type="checkbox" class="green" id="cb1" mv:check_box="product, name, {:readonly => true}, 'yes,', 'no'"/>
becomes
<% check_box 'product', 'name', {:readonly => true, :class => "green", :id => "cb1"}, 'yes,', 'no'"%>
mv:collection_select="product, category, Category.find_all, id, name"
Replaces the tag with a select helper, it quotes the object and method if necessary, and
merges any html attributes into the html_options
<select mv:collection_select="product, category, Category.find_all, id, name">
<option>One</option>
<option>One</option>
</select>
becomes
<%= collection_select 'product', 'category', Category.find_all, 'id', 'name' %>
and
<select size="3" mv:collection_select="product, category, Category.find_all, id, name, {}, :readonly => true ">
<option>One</option>
<option>One</option>
</select>
becomes
<%= collection_select 'product', 'category', Category.find_all, 'id', 'name', {}, :readonly => true, :size => 3 %>
mv:form=":action => ‘new’"
Replaces this tag and closing tag with the form_tag helper and a closing form tag. It also pulls the
method and multipart attributes from the element and merges that into the form_tag options, for example...
<form mv:form=":action => 'new'">foobar</form>
becomes
<%= form_tag( :action => 'new') %>
foobar
</form>
<form method="GET" mv:form=":action => 'new'">foobar</form>
becomes
<%= form_tag( { :action => 'new' }, :method => 'GET') %>
foobar
</form>
mv:form_remote=":action => ‘ url_for(:controller => "some", :action => "place")’"
Replaces this tag and closing tag with the form_remote_tag helper and a closing form tag
### needs work - fix prototype and add example ###
mv:hidden_field="object, method"
Replaces this tag with an hidden input tag using the rails hidden_tag helper, for example...
<input mv:hidden_field="product, desc" type="hidden" value="dummy text"/>
becomes
<%= hidden_field product, desc %>
mv:password_field="user, password"
Replaces the tag with a password_field helper using the attribute as well as merging any html
attributes that have been set by the designer, for example...
<input type="password" mv:password_field="user, password"/>
becomes
<%= password_field user, password %>
and similarly
<input type="password" mv:password_field="user, password" size="10" maxlength="15" class="pwdStyle"/>
becomes
<%= password_field, user, password, :class => 'pwdStyle', :maxlength = 15, :size => 10 %>
mv:radio_button="product, category, 'clothing'"
Replaces the tag with a radio_button helper, it quotes the object and method if necessary, and
merges any html attributes into the options
<input type="radio" mv:radio_button="product, category, 'clothing'"/>
becomes
<%= radio_button 'product','category','clothing' %>
and
<input type="radio" class="green" mv:radio_button="product, category, 'clothing', :readonly => true"/>
becomes
<%= radio_button 'product','category','clothing', :readonly => true, :class => 'green' %>
mv:select="product, category, Category.find_all.collect{|c| [c.name, c.id]}"
Replaces the tag with a select helper, it quotes the object and method if necessary, and
merges any html attributes into the html_options
<select mv:select="product, category, Category.find_all.collect{|c| [c.name, c.id]}">
<option>One</option>
<option>One</option>
</select>
becomes
<%= select 'product', 'category', Category.find_all.collect{|c| [c.name, c.id]} %>
and
<select size="3" mv:select="product, category, Category.find_all.collect{|c| [c.name, c.id]}, {}, :readonly => true ">
<option>One</option>
<option>One</option>
</select>
becomes
<%= select 'product', 'category', Category.find_all.collect{|c| [c.name, c.id]}, {}, :readonly => true, :size => 3 %>
mv:submit="submitOptions"
Replaces the tag with a submit_tag helper, it uses the html value attribute to set the text
in the helper, and appends any options after, for example...
<input type="submit" mv:submit="" value="Save product"/>
becomes
<%= submit_tag 'Save product' %>
and
<input type="submit" mv:submit=":foo => 'bar'" value="Save product"/>
becomes
<%= submit_tag 'Save product', :foo => 'bar' %>
mv:text_area="object, method"
Replaces the tag with a text_area helper, it uses the html attributes like rows, cols, disabled,
readonly, class, style, tabindex, accesskey and merges them with the object and method specified
in the attribute value, for example...
<textarea mv:text_areas="product, desc">dummy text</textarea>
becomes
<%= text_area prouct, desc %>
or a more complex example
<textarea mv:text_area="product, desc" rows="4" cols="60", class="mystyle">dummy text</textarea>
becomes
<%= textarea product, desc, :class => 'mystyle', :cols => '60', :rows => 4 %>
mv:text_field="object, method"
Replaces the tag with a text_field helper, it uses the html attributes like size, maxlength,
disabled, readonly, class, style, tabindex, accesskey and merges them with the object and
method specified in the attribute value, for example...
<input type="text" mv:text_field="product, name" value="dummy text"/>
becomes
<%= text_field product, name %>
and
<input type="text" mv:text_field="product, name" value="dummy text" class="mystyle" size="15" maxlength="20"/>
becomes
<%= text_field product, name, :class => 'mystyle', :maxlength => 20, :size => 15 %>
Directives index in alphabetical order:
| mv:attr | Replaces attribute value(s) on this element with the value of an expression |
| mv:block | Expands to the equivalent rhtml (erb) block code around this element |
| mv:check_box | Replaces this element with a Rails check_box helper |
| mv:collection_select | Replaces this element with a Rails collection_select helper.
(
Used on <select> form elements
)
|
| mv:content | Replaces the content of this element with the value of the expression |
| mv:else | Used in conjunction with the mv:if and mv:elsif directives to allow you to create if... elsif... else... end blocks |
| mv:elsif | Used in conjunction with the mv:if directive to allow you to create if... elsif... end blocks |
| mv:eval | Inserts an rhtml evaluation expression for the attribute value prior to this element |
| mv:form | Replaces the start and end tags of this element using the Rails form_tag block helper and a closing form tag |
| mv:form_remote | Replaces the start and end tags of this element using the Rails form_remote_tag helper and a closing form tag for Ajax-enabled form submission using the Prototype library |
| mv:generate | Generate output containing this element and its children |
| mv:gen_partial | Generate a Rails partial |
| mv:gen_replace | Used with mv:generate to replace the content of this element in the generated output with the value of the attribute |
| mv:hidden_field | Replaces this element with a hidden input element using the Rails hidden_tag helper.
(
Used on <input> form elements
)
|
| mv:if | Wraps this element with an if... end block using the attribute contents for the condition |
| mv:image_tag | Replaces this element using the Rails image_tag helper.
(
Used on <img> elements
)
|
| mv:import | Design-time directive to mark a snapshot of generated code |
| mv:import_render | Design-time directive to mark a snapshot of generated partial code |
| Inline Erb substitutions | Inline substitution notation for Erb expressions |
| mv:javascript_include | Replaces this element using the Rails javascript_include_tag helper.
(
Used on <script> element in html header section
)
|
| mv:link_to | Replaces this element using the Rails link_to helper.
(
Used on <a> link elements
)
|
| mv:link_to_function | Replaces this element using the Rails link_to_function helper which creates a link which calls a JavaScript function.
(
Used on <a> link elements
)
|
| mv:link_to_if | Replaces this element using the Rails link_to_if helper
(
Used on <a> link elements
)
|
| mv:link_to_remote | Replaces this element using the Rails link_to_remote helper
(
Used on <a> link elements
)
|
| mv:omit_tag | Omits this element from the generated output if the value is empty or evaluates to true |
| mv:password_field | Replaces this element with a password input element using the Rails password_field helper.
(
Used on <input> form elements
)
|
| mv:radio_button | Replaces this element with a Rails radio_button helper.
(
Used on <input> form elements
)
|
| mv:replace | Replaces this element and its content with the value of the expression |
| mv:stylesheet_link | Replaces this element using the Rails stylesheet_link_tag helper
(
Used on stylesheet <link> elements in html header section
)
|
| mv:submit | Replaces this element with a submit input element using the Rails submit_tag helper.
(
Used on <input> form elements
)
|
| mv:text_area | Replaces this element with a textarea input element using the Rails text_area helper.
(
Used on <textarea> form elements
)
|
| mv:text_field | Replaces this element with a text input element using the Rails text_field helper.
(
Used on <input> form elements
)
|
| © Copyright MasterView 2006 |
|