RubyGems - padrino-helpers - Versions diffs - 0.1.3 → 0.1.4 - Mend

padrino-helpers 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

data/README.rdoc +193 -88
data/Rakefile +2 -2
data/VERSION +1 -1
data/lib/padrino-helpers/format_helpers.rb +5 -6
data/padrino-helpers.gemspec +5 -8
data/test/helper.rb +1 -1
data/test/{active_support_helpers.rb → support_helpers.rb} +0 -0
data/test/test_format_helpers.rb +4 -4
metadata +4 -5

data/README.rdoc CHANGED Viewed

@@ -11,7 +11,7 @@ To install the 'full-stack' padrino framework, simply grab the latest version fr
   $ sudo gem install padrino --source http://gemcutter.org
 This will install the necessary padrino gems to get you started.
-Now you are ready to use this gem to enhance your sinatra projects or to create new Padrino applications.
+Now you are ready to use this gem to enhance your existing Sinatra projects or build new Padrino applications.
 You can also install only the padrino-helpers gem for more fine-grained use:
@@ -21,6 +21,51 @@ You can also install only the padrino-helpers gem for more fine-grained use:
 === 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.
+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.
+The list of defined helpers in the 'output helpers' category:
 * <tt>content_for(key, &block)</tt>
   * Capture a block of content to be rendered at a later time.
   * <tt>content_for(:head) { ...content... }</tt>
@@ -40,6 +85,24 @@ You can also install only the padrino-helpers gem for more fine-grained use:
 === 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.
+The list of defined helpers in the 'tag helpers' category:
 * <tt>tag(name, options={})</tt>
   * Creates an html tag with the given name and options
   * <tt>tag(:br, :style => 'clear:both')</tt> => <br style="clear:both" />
@@ -55,6 +118,24 @@ You can also install only the padrino-helpers gem for more fine-grained use:
 === 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'
+The list of defined helpers in the 'asset helpers' category:
 * <tt>flash_tag(kind, options={})</tt>
   * Creates a div to display the flash of given type if it exists
   * <tt>flash_tag(:notice, :class => 'flash', :id => 'flash-notice')</tt>
@@ -78,6 +159,28 @@ You can also install only the padrino-helpers gem for more fine-grained use:
 === 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"
+The list of defined helpers in the 'form helpers' category:
 * <tt>form_tag(url, options={}, &block)</tt>
   * Constructs a form without object based on options
   * Supports form methods 'put' and 'delete' through hidden field
@@ -128,28 +231,40 @@ You can also install only the padrino-helpers gem for more fine-grained use:
 * <tt>image_submit_tag(source, options={})</tt>
   * Constructs an image submit button from the given options
   * <tt>image_submit_tag "submit.png", :class => 'success'</tt>
-A form_tag might look like:
-  - 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"
 === 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'
+The list of defined helpers in the 'form builders' category:
 * <tt>form_for(object, url, settings={}, &block)</tt>
   * Constructs a form using given or default form_builder
   * Supports form methods 'put' and 'delete' through hidden field
@@ -193,33 +308,28 @@ The following are fields provided by AbstractFormBuilder that can be used within
 * <tt>image_submit(source, options={})</tt>
   * <tt>f.image_submit "submit.png", :class => 'long'</tt>
-A form_for using these basic fields might look like:
+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
-    %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'
-There is also a StandardFormBuilder which builds on the abstract fields that can be used within a form_for:
+    = 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>
+The following are fields provided by StandardFormBuilder that can be used within a form_for or fields_for:
 * <tt>text_field_block(field, options={}, label_options={})</tt>
   * <tt>text_field_block(:nickname, :class => 'big', :caption => "Username")</tt>
@@ -237,27 +347,8 @@ There is also a StandardFormBuilder which builds on the abstract fields that can
   * <tt>submit_block(:username, :class => 'big')</tt>
 * <tt>image_submit_block(source, options={})</tt>
   * <tt>image_submit_block('submit.png', :class => 'big')</tt>
-A form_for using these standard fields might look like:
-  - 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:
-  <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:
+You can also easily build your own FormBuilder which allows for customized fields and behavior:
   class MyCustomFormBuilder < AbstractFormBuilder
     # Here we have access to a number of useful variables
@@ -277,14 +368,29 @@ Once a custom builder is defined, any call to form_for can use the new builder:
 The form builder can even be made into the default builder when form_for is invoked:
-  # anywhere in the sinatra application
+  # anywhere in the Padrino or Sinatra application
   set :default_builder, 'MyCustomFormBuilder'
-And there you have it, a fairly complete form builder solution for sinatra.
+And there you have it, a fairly complete form builder solution for Padrino (and Sinatra).
 I hope to create or merge in an even better 'default' form_builder in the near future.
 === 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>relative_time_ago</tt>, <tt>time_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.
+The list of defined helpers in the 'format helpers' category:
 * <tt>escape_html</tt> (alias <tt>h</tt> and <tt>h!</tt>)
   * (from RackUtils) Escape ampersands, brackets and quotes to their HTML/XML entities.
 * <tt>relative_time_ago(date)</tt>
@@ -297,32 +403,16 @@ I hope to create or merge in an even better 'default' form_builder in the near f
   * <tt>time_in_words(2.days.ago)</tt> => "2 days ago"
   * <tt>time_in_words(100.days.ago)</tt> => "Tuesday, July 21"
   * <tt>time_in_words(1.day.from_now)</tt> => "tomorrow"
-* <tt>escape_javascript(html_content)</tt>
+* <tt>js_escape_html(html_content)</tt>
   * Escapes html to allow passing information to javascript. Used for passing data inside an ajax .js.erb template
-  * <tt>escape_javascript("<h1>Hey</h1>")</tt>
+  * <tt>js_escape_html("<h1>Hey</h1>")</tt>
 See the wiki article for additional information: <...WIKI...>
 === Render Helpers
-This component provides a number of rendering helpers for sinatra, making the process
-of displaying templates far smoother. This plugin also has support for useful additions
-such as partials (with support for :collection) into the templating system.
-* <tt>erb_template(template_path, options={})</tt>
-  * Renders a erb template based on the given path
-  * <tt>erb_template 'users/new'</tt>
-* <tt>haml_template(template_path, options={})</tt>
-  * Renders a haml template based on the given path
-  * <tt>haml_template 'users/new'</tt>
-* <tt>render_template(template_path, options={})</tt>
-  * Renders the first detected template based on the given path
-  * <tt>render_template 'users/new'</tt>
-  * <tt>render_template 'users/index', :template_engine => 'haml'</tt>
-* <tt>partial(template, *args)</tt>
-  * Renders the html related to the partial template for object or collection
-  * <tt>partial 'photo/_item', :object => @photo, :locals => { :foo => 'bar' }</tt>
-  * <tt>partial 'photo/_item', :collection => @photos</tt>
+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:
@@ -336,7 +426,7 @@ There is also a method which renders the first view matching the path and remove
   render_template 'path/to/any/template'
-It is worth noting these are mostly for convenience. When I had more complex view files in sinatra, I got tired of writing:
+It is worth noting these are mostly for convenience. With nested view file paths in Sinatra, this becomes tiresome:
   haml :"the/path/to/file"
   erb "/path/to/file".to_sym
@@ -352,7 +442,22 @@ This works as you would expect and also supports the collection counter inside t
   # Access to collection counter with <partial_name>_counter i.e item_counter
   # Access the object with the partial_name i.e item
-And that concludes the render plugin for now but I am open to adding more methods as time progresses.
+The list of defined helpers in the 'render helpers' category:
+* <tt>erb_template(template_path, options={})</tt>
+  * Renders a erb template based on the given path
+  * <tt>erb_template 'users/new'</tt>
+* <tt>haml_template(template_path, options={})</tt>
+  * Renders a haml template based on the given path
+  * <tt>haml_template 'users/new'</tt>
+* <tt>render_template(template_path, options={})</tt>
+  * Renders the first detected template based on the given path
+  * <tt>render_template 'users/new'</tt>
+  * <tt>render_template 'users/index', :template_engine => 'haml'</tt>
+* <tt>partial(template, *args)</tt>
+  * Renders the html related to the partial template for object or collection
+  * <tt>partial 'photo/_item', :object => @photo, :locals => { :foo => 'bar' }</tt>
+  * <tt>partial 'photo/_item', :collection => @photos</tt>
 See the wiki article for additional information: <...WIKI...>

data/Rakefile CHANGED Viewed

@@ -8,12 +8,12 @@ begin
     gem.summary = "Helpers for padrino"
     gem.description = "Tag helpers, asset helpers, form helpers, form builders and many more helpers for padrino"
     gem.email = "nesquena@gmail.com"
-    gem.homepage = "http://github.com/padrino/padrino-helpers"
+    gem.homepage = "http://github.com/padrino/padrino-framework/tree/master/padrino-helpers"
     gem.authors = ["Padrino Team", "Nathan Esquenazi", "Davide D'Agostino", "Arthur Chiu"]
     gem.add_runtime_dependency     "sinatra",       ">= 0.9.2"
     gem.add_runtime_dependency     "padrino-core",  ">= 0.1.1"
     gem.add_development_dependency "haml",          ">= 2.2.1"
-    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_development_dependency "shoulda",       ">= 0"
     gem.add_development_dependency "mocha",         ">= 0.9.7"
     gem.add_development_dependency "rack-test",     ">= 0.5.0"
     gem.add_development_dependency "webrat",        ">= 0.5.1"

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 0.1.3
1	+ 0.1.4

data/lib/padrino-helpers/format_helpers.rb CHANGED Viewed

@@ -55,9 +55,9 @@ module Padrino
         end
       end
-      # Used in xxxx.js.erb files to escape html so that it can be passed to javascript from sinatra
-      # escape_javascript("<h1>Hey</h1>")
-      def escape_javascript(html_content)
+      # Used in xxxx.js.erb files to escape html so that it can be passed to javascript from Padrino
+      # js_escape_html("<h1>Hey</h1>")
+      def js_escape_html(html_content)
         return '' unless html_content
         javascript_mapping = { '\\' => '\\\\', '</' => '<\/', "\r\n" => '\n', "\n" => '\n' }
         javascript_mapping.merge("\r" => '\n', '"' => '\\"', "'" => "\\'")
@@ -65,9 +65,8 @@ module Padrino
         "\"#{escaped_string}\""
       end
-      alias js_escape escape_javascript
-      alias js_escape_html escape_javascript
-      alias escape_for_javascript escape_javascript
+      alias escape_javascript js_escape_html
+      alias escape_for_javascript js_escape_html
     end
   end

data/padrino-helpers.gemspec CHANGED Viewed

@@ -5,24 +5,21 @@
 Gem::Specification.new do |s|
   s.name = %q{padrino-helpers}
-  s.version = "0.1.3"
+  s.version = "0.1.4"
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Padrino Team", "Nathan Esquenazi", "Davide D'Agostino", "Arthur Chiu"]
-  s.date = %q{2009-11-20}
+  s.date = %q{2009-11-23}
   s.description = %q{Tag helpers, asset helpers, form helpers, form builders and many more helpers for padrino}
   s.email = %q{nesquena@gmail.com}
   s.extra_rdoc_files = [
-    "LICENSE",
-     "README.rdoc"
+    "README.rdoc"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
      "README.rdoc",
-     "README.rdoc",
-     "Rakefile",
      "Rakefile",
      "VERSION",
      "lib/padrino-helpers.rb",
@@ -35,7 +32,6 @@ Gem::Specification.new do |s|
      "lib/padrino-helpers/render_helpers.rb",
      "lib/padrino-helpers/tag_helpers.rb",
      "padrino-helpers.gemspec",
-     "test/active_support_helpers.rb",
      "test/fixtures/markup_app/app.rb",
      "test/fixtures/markup_app/views/capture_concat.erb",
      "test/fixtures/markup_app/views/capture_concat.haml",
@@ -60,6 +56,7 @@ Gem::Specification.new do |s|
      "test/fixtures/render_app/views/template/haml_template.haml",
      "test/fixtures/render_app/views/template/some_template.haml",
      "test/helper.rb",
+     "test/support_helpers.rb",
      "test/test_asset_tag_helpers.rb",
      "test/test_form_builder.rb",
      "test/test_form_helpers.rb",
@@ -68,7 +65,7 @@ Gem::Specification.new do |s|
      "test/test_render_helpers.rb",
      "test/test_tag_helpers.rb"
   ]
-  s.homepage = %q{http://github.com/padrino/padrino-helpers}
+  s.homepage = %q{http://github.com/padrino/padrino-framework/tree/master/padrino-helpers}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}

data/test/helper.rb CHANGED Viewed

@@ -7,7 +7,7 @@ require 'webrat'
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
-require 'active_support_helpers'
+require 'support_helpers'
 require 'padrino-helpers'
 class Test::Unit::TestCase

data/test/{active_support_helpers.rb → support_helpers.rb} RENAMED Viewed

File without changes

data/test/test_format_helpers.rb CHANGED Viewed

@@ -82,15 +82,15 @@ class TestFormatHelpers < Test::Unit::TestCase
     end
   end
-  context 'for #escape_javascript method' do
+  context 'for #js_escape_html method' do
     should "escape double quotes" do
-      assert_equal "\"hello\"", escape_javascript('"hello"')
+      assert_equal "\"hello\"", js_escape_html('"hello"')
     end
     should "escape single quotes" do
-      assert_equal "\"hello\"", escape_javascript("'hello'")
+      assert_equal "\"hello\"", js_escape_html("'hello'")
     end
     should "escape html tags and breaks" do
-      assert_equal "\"\\n<p>hello<\\/p>\\n\"", escape_javascript("\n\r<p>hello</p>\r\n")
+      assert_equal "\"\\n<p>hello<\\/p>\\n\"", js_escape_html("\n\r<p>hello</p>\r\n")
     end
   end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: padrino-helpers
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Padrino Team
@@ -12,7 +12,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-11-20 00:00:00 -08:00
+date: 2009-11-23 00:00:00 -08:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -92,7 +92,6 @@ executables: []
 extensions: []
 extra_rdoc_files:
-- LICENSE
 - README.rdoc
 files:
 - .document
@@ -111,7 +110,6 @@ files:
 - lib/padrino-helpers/render_helpers.rb
 - lib/padrino-helpers/tag_helpers.rb
 - padrino-helpers.gemspec
-- test/active_support_helpers.rb
 - test/fixtures/markup_app/app.rb
 - test/fixtures/markup_app/views/capture_concat.erb
 - test/fixtures/markup_app/views/capture_concat.haml
@@ -136,6 +134,7 @@ files:
 - test/fixtures/render_app/views/template/haml_template.haml
 - test/fixtures/render_app/views/template/some_template.haml
 - test/helper.rb
+- test/support_helpers.rb
 - test/test_asset_tag_helpers.rb
 - test/test_form_builder.rb
 - test/test_form_helpers.rb
@@ -144,7 +143,7 @@ files:
 - test/test_render_helpers.rb
 - test/test_tag_helpers.rb
 has_rdoc: true
-homepage: http://github.com/padrino/padrino-helpers
+homepage: http://github.com/padrino/padrino-framework/tree/master/padrino-helpers
 licenses: []
 post_install_message: