Example

= 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>') # => &lt;hello&gt;&amp;&lt;goodbye&gt;

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 Padrino. See LICENSE for details.