padrino-helpers

= 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: content_for, capture_html, and concat_content

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

...

Example <%= stylesheet_link_tag 'style' %> <%= yield_content :assets %> ...

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 content_for?(true) 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 '

' + inner_form_html + '' 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 concat_content. 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://padrinorb.com/guides/application-helpers/output-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: tag, content_tag and input_tag.

The tag and content_tag are for building arbitrary html tags with a name and specified options. If the tag contains 'content' within then content_tag is used. For example:

tag(:br, :style => 'clear:both') =>
content_tag(:p, "demo", :class => 'light') =>

demo

The input_tag is used to build tags that are related to accepting input from the user:

input_tag :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://padrinorb.com/guides/application-helpers/tag-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 '[e-mail]', "Fake Email Link", :cc => "[e-mail]"} %p= image_tag 'padrino.png', :width => '35', :class => 'logo'

For more information on using asset helpers, check out the guide for {Padrino Helpers}[http://padrinorb.com/guides/application-helpers/asset-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://padrinorb.com/guides/application-helpers/form-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://padrinorb.com/guides/application-helpers/form-builders/] 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):

Full name:

...omitted...

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://padrinorb.com/guides/application-helpers/standard-form-builder/].

=== Format Helpers

Format helpers are several useful utilities for manipulating the format of text to achieve a goal. The four format helpers are escape_html, time_ago_in_words, and js_escape_html.

The escape_html and js_escape_html function are for taking an html string and escaping certain characters. escape_html will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful to sanitize user content before displaying this on a template. js_escape_html is used for passing javascript information from a js template to a javascript function.

escape_html('&') # => <hello>&<goodbye>

There is also an alias for escape_html called h for even easier usage within templates.

Format helpers also includes a number of useful text manipulation functions such as simple_format, pluralize, word_wrap, truncate and truncate_words.

simple_format("hello\nworld") # => "

hello
world

" 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://padrinorb.com/guides/application-helpers/format-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://padrinorb.com/guides/application-helpers/render-helpers/].

== Copyright

Copyright (c) 2011-2015 Padrino. See LICENSE for details.