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

padrino-helpers 0.1.3 → 0.1.4

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: