240 lines
9.8 KiB
Text
240 lines
9.8 KiB
Text
|
= Application Extensions and Helpers (padrino-helpers)
|
||
|
|
|
||
|
|
=== Overview
|
||
|
|
|
||
|
|
This component provides a great deal of view helpers related to html markup generation.
|
||
|
|
There are helpers for generating tags, forms, links, images, and more. Most of the basic
|
||
|
|
methods should be very familiar to anyone who has used rails view helpers.
|
||
|
|
|
||
|
|
=== Output Helpers
|
||
|
|
|
||
|
|
Output helpers are a collection of important methods for managing, capturing and displaying output
|
||
|
|
in various ways and is used frequently to support higher-level helper functions. There are
|
||
|
|
three output helpers worth mentioning: <tt>content_for</tt>, <tt>capture_html</tt>, and <tt>concat_content</tt>
|
||
|
|
|
||
|
|
The content_for functionality supports capturing content and then rendering this into a different place
|
||
|
|
such as within a layout. One such popular example is including assets onto the layout from a template:
|
||
|
|
|
||
|
|
# app/views/site/index.erb
|
||
|
|
...
|
||
|
|
<% content_for :assets do %>
|
||
|
|
<%= stylesheet_link_tag 'index', 'custom' %>
|
||
|
|
<% end %>
|
||
|
|
...
|
||
|
|
|
||
|
|
Added to a template, this will capture the includes from the block and allow them to be yielded into the layout:
|
||
|
|
|
||
|
|
# app/views/layout.erb
|
||
|
|
...
|
||
|
|
<head>
|
||
|
|
<title>Example</title>
|
||
|
|
<%= stylesheet_link_tag 'style' %>
|
||
|
|
<%= yield_content :assets %>
|
||
|
|
</head>
|
||
|
|
...
|
||
|
|
|
||
|
|
This will automatically insert the contents of the block (in this case a stylesheet include) into the
|
||
|
|
location the content is yielded within the layout. You can also check if content exists for a block using
|
||
|
|
<tt>content_for?(true)</tt> which returns true if content exists.
|
||
|
|
|
||
|
|
The capture_html and the concat_content methods allow content to be manipulated and stored for use in building
|
||
|
|
additional helpers accepting blocks or displaying information in a template. One example is the use of
|
||
|
|
these in constructing a simplified 'form_tag' helper which accepts a block.
|
||
|
|
|
||
|
|
# form_tag '/register' do ... end
|
||
|
|
def form_tag(url, options={}, &block)
|
||
|
|
# ... truncated ...
|
||
|
|
inner_form_html = capture_html(&block)
|
||
|
|
concat_content '<form>' + inner_form_html + '</form>'
|
||
|
|
end
|
||
|
|
|
||
|
|
This will capture the template body passed into the form_tag block and then append the content
|
||
|
|
to the template through the use of <tt>concat_content</tt>. Note have been built to work for both haml and erb
|
||
|
|
templates using the same syntax.
|
||
|
|
|
||
|
|
For more information on using output helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== Tag Helpers
|
||
|
|
|
||
|
|
Tag helpers are the basic building blocks used to construct html 'tags' within a view template. There
|
||
|
|
are three major functions for this category: <tt>tag</tt>, <tt>content_tag</tt> and <tt>input_tag</tt>.
|
||
|
|
|
||
|
|
The tag and content_tag are for building arbitrary html tags with a name and specified options. If
|
||
|
|
the tag contains 'content' within then <tt>content_tag</tt> is used. For example:
|
||
|
|
|
||
|
|
tag(:br, :style => 'clear:both') => <br style="clear:both" />
|
||
|
|
content_tag(:p, "demo", :class => 'light') => <p class="light">demo</p>
|
||
|
|
|
||
|
|
The input_tag is used to build tags that are related to accepting input from the user:
|
||
|
|
|
||
|
|
input_tag :text, :class => "demo" => <input type='text' class='demo' />
|
||
|
|
input_tag :password, :value => "secret", :class => "demo"
|
||
|
|
|
||
|
|
Note that all of these accept html options and result in returning a string containing html tags.
|
||
|
|
|
||
|
|
For more information on using tag helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== Asset Helpers
|
||
|
|
|
||
|
|
Asset helpers are intended to help insert useful html onto a view template such as 'flash' notices,
|
||
|
|
hyperlinks, mail_to links, images, stylesheets and javascript. An example of their uses would be on a
|
||
|
|
simple view template:
|
||
|
|
|
||
|
|
# app/views/example.haml
|
||
|
|
...
|
||
|
|
%head
|
||
|
|
= stylesheet_link_tag 'layout'
|
||
|
|
= javascript_include_tag 'application'
|
||
|
|
%body
|
||
|
|
...
|
||
|
|
= flash_tag :notice
|
||
|
|
%p= link_to 'Blog', '/blog', :class => 'example'
|
||
|
|
%p Mail me at #{mail_to 'fake@faker.com', "Fake Email Link", :cc => "test@demo.com"}
|
||
|
|
%p= image_tag 'padrino.png', :width => '35', :class => 'logo'
|
||
|
|
|
||
|
|
For more information on using asset helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== Form Helpers
|
||
|
|
|
||
|
|
Form helpers are the 'standard' form tag helpers you would come to expect when building forms. A simple
|
||
|
|
example of constructing a non-object form would be:
|
||
|
|
|
||
|
|
- form_tag '/destroy', :class => 'destroy-form', :method => 'delete' do
|
||
|
|
= flash_tag(:notice)
|
||
|
|
- field_set_tag do
|
||
|
|
%p
|
||
|
|
= label_tag :username, :class => 'first'
|
||
|
|
= text_field_tag :username, :value => params[:username]
|
||
|
|
%p
|
||
|
|
= label_tag :password, :class => 'first'
|
||
|
|
= password_field_tag :password, :value => params[:password]
|
||
|
|
%p
|
||
|
|
= label_tag :strategy
|
||
|
|
= select_tag :strategy, :options => ['delete', 'destroy'], :selected => 'delete'
|
||
|
|
%p
|
||
|
|
= check_box_tag :confirm_delete
|
||
|
|
- field_set_tag(:class => 'buttons') do
|
||
|
|
= submit_tag "Remove"
|
||
|
|
|
||
|
|
For more information on using form helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== FormBuilders
|
||
|
|
|
||
|
|
Form builders are full-featured objects allowing the construction of complex object-based forms
|
||
|
|
using a simple, intuitive syntax.
|
||
|
|
|
||
|
|
A form_for using these basic fields might look like:
|
||
|
|
|
||
|
|
- form_for @user, '/register', :id => 'register' do |f|
|
||
|
|
= f.error_messages
|
||
|
|
%p
|
||
|
|
= f.label :username, :caption => "Nickname"
|
||
|
|
= f.text_field :username
|
||
|
|
%p
|
||
|
|
= f.label :email
|
||
|
|
= f.text_field :email
|
||
|
|
%p
|
||
|
|
= f.label :password
|
||
|
|
= f.password_field :password
|
||
|
|
%p
|
||
|
|
= f.label :is_admin, :caption => "Admin User?"
|
||
|
|
= f.check_box :is_admin
|
||
|
|
%p
|
||
|
|
= f.label :color, :caption => "Favorite Color?"
|
||
|
|
= f.select :color, :options => ['red', 'black']
|
||
|
|
%p
|
||
|
|
- fields_for @user.location do |location|
|
||
|
|
= location.text_field :street
|
||
|
|
= location.text_field :city
|
||
|
|
%p
|
||
|
|
= f.submit "Create", :class => 'button'
|
||
|
|
|
||
|
|
Forms can also accept nested attributes using `fields_for` within the form builder in recent releases. Check out the guide for {Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers] to learn more about nested forms.
|
||
|
|
|
||
|
|
There is also an additional StandardFormBuilder which builds on the abstract fields that can be used within a form_for.
|
||
|
|
|
||
|
|
A form_for using these standard fields might be:
|
||
|
|
|
||
|
|
- form_for @user, '/register', :id => 'register' do |f|
|
||
|
|
= f.error_messages
|
||
|
|
= f.text_field_block :name, :caption => "Full name"
|
||
|
|
= f.text_field_block :email
|
||
|
|
= f.check_box_block :remember_me
|
||
|
|
= f.select_block :fav_color, :options => ['red', 'blue']
|
||
|
|
= f.password_field_block :password
|
||
|
|
= f.submit_block "Create", :class => 'button'
|
||
|
|
|
||
|
|
and would generate this html (with each input contained in a paragraph and containing a label):
|
||
|
|
|
||
|
|
<form id="register" action="/register" method="post">
|
||
|
|
<p><label for="user_name">Full name: </label><input type="text" id="user_name" name="user[name]"></p>
|
||
|
|
...omitted...
|
||
|
|
<p><input type="submit" value="Create" class="button"></p>
|
||
|
|
</form>
|
||
|
|
|
||
|
|
You can also easily build your own FormBuilder which allows for customized fields and behavior.
|
||
|
|
|
||
|
|
For more information on using the Padrino form builders, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== Format Helpers
|
||
|
|
|
||
|
|
Format helpers are several useful utilities for manipulating the format of text to achieve a goal.
|
||
|
|
The four format helpers are <tt>escape_html</tt>, <tt>time_ago_in_words</tt>, and <tt>js_escape_html</tt>.
|
||
|
|
|
||
|
|
The escape_html and js_escape_html function are for taking an html string and escaping certain characters.
|
||
|
|
<tt>escape_html</tt> will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful
|
||
|
|
to sanitize user content before displaying this on a template. <tt>js_escape_html</tt> is used for
|
||
|
|
passing javascript information from a js template to a javascript function.
|
||
|
|
|
||
|
|
escape_html('<hello>&<goodbye>') # => <hello>&<goodbye>
|
||
|
|
|
||
|
|
There is also an alias for escape_html called <tt>h</tt> for even easier usage within templates.
|
||
|
|
|
||
|
|
Format helpers also includes a number of useful text manipulation functions such as <tt>simple_format</tt>,
|
||
|
|
<tt>pluralize</tt>, <tt>word_wrap</tt>, <tt>truncate</tt> and <tt>truncate_words</tt>.
|
||
|
|
|
||
|
|
simple_format("hello\nworld") # => "<p>hello<br/>world</p>"
|
||
|
|
pluralize(2, 'person') => '2 people'
|
||
|
|
word_wrap('Once upon a time', :line_width => 8) => "Once upon\na time"
|
||
|
|
truncate("Once upon a time in a world far far away", :length => 8) => "Once upon..."
|
||
|
|
truncate_words("Once upon a time in a world far far away", :length => 4) => "Once upon a time..."
|
||
|
|
|
||
|
|
These helpers can be invoked from any route or view within your application.
|
||
|
|
|
||
|
|
For more information on using the format helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
=== Render Helpers
|
||
|
|
|
||
|
|
This component provides a number of rendering helpers making the process of displaying templates a bit easier.
|
||
|
|
This plugin also has support for useful additions such as partials (with support for :collection) for the templating system.
|
||
|
|
|
||
|
|
Using render plugin helpers is extremely simple. If you want to render an erb template in your view path:
|
||
|
|
|
||
|
|
render :erb, 'path/to/erb/template'
|
||
|
|
|
||
|
|
or using haml templates works just as well:
|
||
|
|
|
||
|
|
render :haml, 'path/to/haml/template'
|
||
|
|
|
||
|
|
There is also a method which renders the first view matching the path and removes the need to define an engine:
|
||
|
|
|
||
|
|
render 'path/to/any/template'
|
||
|
|
|
||
|
|
Finally, we have the all-important partials support for rendering mini-templates onto a page:
|
||
|
|
|
||
|
|
partial 'photo/_item', :object => @photo, :locals => { :foo => 'bar' }
|
||
|
|
partial 'photo/_item', :collection => @photos
|
||
|
|
|
||
|
|
For more information on using the render and partial helpers, check out the guide for
|
||
|
|
{Padrino Helpers}[http://www.padrinorb.com/guides/application-helpers].
|
||
|
|
|
||
|
|
== Copyright
|
||
|
|
|
||
|
|
Copyright (c) 2011-2013 Padrino. See LICENSE for details.
|