Changeset 1027

Show
Ignore:
Timestamp:
11/19/07 09:57:34 (11 months ago)
Author:
rogelio.samo..@gmail.com
Message:

- merb form helpers additional documentation. closes #317 [bryan@osesm.com]

--This line, and thmse below, will be ignored--

M Rakefile
M lib/form_helpers.rb

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • plugins/merb_helpers/Rakefile

    r1024 r1027  
    11require 'rubygems' 
    22require 'rake/gempackagetask' 
     3require 'spec' 
     4require 'spec/rake/spectask' 
    35 
    46PLUGIN = "merb_helpers" 
    …… 
    3537  sh %{sudo gem install pkg/#{NAME}-#{GEM_VERSION}} 
    3638end 
     39 
     40Spec::Rake::SpecTask.new do |t| 
     41   t.warning = true 
     42   t.spec_opts = ["--format", "specdoc", "--colour"] 
     43   t.spec_files = Dir['specs/**/*_spec.rb'].sort    
     44end 

  • plugins/merb_helpers/lib/form_helpers.rb

    r1009 r1027  
    2121    # 
    2222    #     <form action="/people/create" method="post"> 
     23    #       <label for="person_first_name">First Name</label> 
    2324    #       <input id="person_first_name" name="person[first_name]" size="30" type="text" /> 
     25    #       <label for="person_last_name">Last Name</label> 
    2426    #       <input id="person_last_name" name="person[last_name]" size="30" type="text" /> 
    25     #       <input name="commit" type="submit" value="Create" /> 
     27    #       <button type="submit">Create</button> 
    2628    #     </form> 
    2729    # 
    …… 
    3638    #     <form action="/foo/bar/1" method="post"> 
    3739    #       <label for="first_name">First Name</label><input id="first_name" name="first_name" size="30" type="text" /> 
    38     #       <input name="commit" type="submit" value="Create" /> 
     40    #       <button type="submit">Create</button> 
    3941    #     </form> 
    4042    module Form 
    …… 
    4547      # 
    4648      # ==== Example 
    47       # 
    4849      #   <%= error_messages_for :person %>       
    4950      def error_messages_for(obj, error_li = nil, html_class='submittal_failed') 
    …… 
    120121      # 
    121122      # ==== Examples 
    122       # 
    123123      #     <% form_for :person, :action => url(:people) do %> 
    124124      #       <%= text_control :first_name, :label => 'First Name' %> 
    …… 
    130130      #     <% end %> 
    131131      def fields_for(obj, attrs=nil, &block) 
     132        @_obj ||= nil 
     133        @_block ||= nil 
    132134        obj = obj_from_ivar_or_sym(obj) 
    133135        old_obj, @_obj = @_obj, obj 
    …… 
    167169      end 
    168170       
    169       # Provides a generic HTML text input tag 
     171      # Provides a generic HTML text input tag. 
    170172      # Provides a HTML text input tag based on a resource attribute. 
    171173      # 
    172174      # ==== Example 
    173       #   <%= text_field :fav_color, :label => 'Your Favorite Color' %> 
    174       #   => <label for="fav_color">Your Favorite Color</label><input type="text" name="fav_color" id="fav_color"/> 
     175      #     <%= text_field :fav_color, :label => 'Your Favorite Color' %> 
     176      #     # => <label for="fav_color">Your Favorite Color</label><input type="text" name="fav_color" id="fav_color"/> 
    175177      def text_field(attrs = {}) 
    176178        attrs.merge!(:type => "text") 
    …… 
    179181       
    180182      # Provides a HTML password input based on a resource attribute. 
    181       # This is generally used within a resource block such as +form_for+ 
    182       # ==== Example 
    183       #    <%= password_control :password, :label => 'New Password' %> 
     183      # This is generally used within a resource block such as +form_for+. 
     184      # 
     185      # ==== Example 
     186      #     <%= password_control :password, :label => 'New Password' %> 
    184187      def password_control(col, attrs = {}) 
    185188        attrs.merge!(:name => control_name(col)) 
    …… 
    188191      end 
    189192       
     193      # Provides a generic HTML password input tag. 
     194      # 
     195      # ==== Example 
     196      #     <%= password_field :password, :label => "Password" %> 
     197      #     # => <label for="password">Password</label><input type="password" name="password" id="password"/> 
    190198      def password_field(attrs = {}) 
    191199        attrs.delete(:value) 
    …… 
    201209      private :col_val_to_bool 
    202210 
     211      # Provides a HTML checkbox input based on a resource attribute. 
     212      # This is generally used within a resource block such as +form_for+. 
     213      # 
     214      # ==== Example 
     215      #     <%= checkbox_control :is_activated, :label => "Activated?" %> 
    203216      def checkbox_control(col, attrs = {}) 
    204217        errorify_field(attrs, col) 
    …… 
    207220      end 
    208221 
     222      # Provides a generic HTML checkbox input tag. 
     223      # 
     224      # ==== Example 
     225      #     <% checkbox_field :name => "is_activated", :value => "1" %> 
    209226      def checkbox_field(attrs = {}) 
    210227        on            = attrs.delete(:on)  || 1 
    …… 
    221238      # shown. 
    222239      # 
    223       # ==== Examples 
    224       # 
    225       #   <%= hidden_control :identifier %> 
    226       #   # => <input id="person_identifier" name="person[identifier]" type="hidden" value="#{@person.identifier}" /> 
    227       # 
     240      # ==== Example 
     241      #     <%= hidden_control :identifier %> 
     242      #     # => <input id="person_identifier" name="person[identifier]" type="hidden" value="#{@person.identifier}" /> 
    228243      def hidden_control(col, attrs = {}) 
    229244        attrs.delete(:label) 
    …… 
    232247      end 
    233248       
     249      # Provides a generic HTML hidden input field. 
     250      # 
     251      # ==== Example 
     252      #     <%= hidden_field :name => "secret", :value => "some secret value" %> 
    234253      def hidden_field(attrs = {}) 
    235254        attrs.delete(:label) 
    …… 
    238257      end 
    239258       
     259      # Provides a radio group based on a resource attribute. 
     260      # This is generally used within a resource block such as +form_for+. 
     261      # 
     262      # ==== Examples 
     263      #     <!-- the labels are the options --> 
     264      #     <%= radio_group_control :my_choice, [5,6,7] %> 
     265      #  
     266      #     <!-- custom labels --> 
     267      #     <%= radio_group_control :my_choice, [{:value => 5, :label => "five"}] %> 
    240268      def radio_group_control(col, options = [], attrs = {}) 
    241269        errorify_field(attrs, col) 
    …… 
    251279      end 
    252280       
     281      # Provides a generic HTML radio input tag. 
     282      # Normally, you would use multipe +radio_field+. 
     283      # 
     284      # ==== Example 
     285      #     <%= radio_field :name => "radio_options", :value => "1", :label => "One" %> 
     286      #     <%= radio_field :name => "radio_options", :value => "2", :label => "Two" %> 
    253287      def radio_field(attrs = {}) 
    254288        attrs.merge!(:type => "radio") 
    …… 
    257291      end 
    258292       
     293      # Provides a HTML textarea based on a resource attribute 
     294      # This is generally used within a resource block such as +form_for+ 
     295      # 
     296      # ==== Example 
     297      #     <% text_area_control :comments, :label => "Comments" 
    259298      def text_area_control(col, attrs = {}) 
    260299        attrs ||= {} 
    …… 
    263302      end 
    264303       
     304      # Provides a generic HTML textarea tag. 
     305      # 
     306      # ==== Example 
     307      #     <% text_area_field "my comments", :name => "comments", :label => "Comments" %> 
    265308      def text_area_field(val, attrs = {}) 
    266309        val ||="" 
    …… 
    272315      end 
    273316       
     317      # Provides a generic HTML submit button. 
     318      # 
     319      # ==== Example 
     320      #     <% submit_button "Process" %> 
    274321      def submit_button(contents, attrs = {}) 
     322        contents ||= "Submit" 
    275323        attrs.merge!(:type => "submit") 
    276324        tag("button", contents, attrs) 
    277325      end 
    278326 
     327      # Provides a generic HTML label. 
     328      # 
     329      # ==== Example 
     330      #     <% label "Name", "", :for => "name" %>  
     331      #     # => <label for="name">Name</label> 
    279332      def label(name, contents = "", attrs = {}) 
    280333        tag("label", name.to_s + contents, attrs) 
    281334      end 
    282335 
     336      # Provides a generic HTML select. 
     337      # 
     338      # ==== Options 
     339      # +prompt+:: Adds an additional option tag with the provided string with no value. 
     340      # +selected+:: The value of a selected object, which may be either a string or an array. 
     341      # +include_blank+:: Adds an additional blank option tag with no value. 
     342      # +collection+:: The collection for the select options 
     343      # +text_method+:: Method to determine text of an option (as a symbol). 
     344      # +value_method+:: Method to determine value of an option (as a symbol). 
    283345      def select_field(attrs = {}) 
    284346        collection = attrs.delete(:collection) 
    …… 
    293355      end 
    294356       
     357      # Provides a HTML select based on a resource attribute. 
     358      # This is generally used within a resource block such as +form_for+. 
     359      # 
     360      # ==== Example 
     361      #     <% select_control :name, :collection => %w(one two three four) %> 
    295362      def select_control(col, attrs = {}) 
    296363        attrs.merge!(:name => attrs[:name] || control_name(col)) 
    …… 
    315382      # 
    316383      # ==== Options 
    317       # +selected+:: The value of a selected object, may be either a string or an array. 
     384      # +selected+:: The value of a selected object, which may be either a string or an array. 
    318385      # +prompt+:: Adds an addtional option tag with the provided string with no value. 
    319386      # +include_blank+:: Adds an additional blank option tag with no value. 
    …… 
    384451      # 
    385452      # ==== Example 
    386       #   <% fieldset :legend => 'Customer Options' do -%> 
    387       #   ...your form elements 
    388       #   <% end -%> 
    389       # 
    390       #   => <fieldset><legend>Customer Options</legend>...your form elements</fieldset> 
     453      #     <% fieldset :legend => 'Customer Options' do -%> 
     454      #     ...your form elements 
     455      #     <% end -%> 
     456      # 
     457      #     => <fieldset><legend>Customer Options</legend>...your form elements</fieldset> 
    391458      # 
    392459      # ==== Options 
    …… 
    400467      end 
    401468       
    402       ## file input control 
     469      # Provides a HTML file input for a resource attribute. 
     470      # This is generally used within a resource block such as +form_for+. 
     471      # 
     472      # ==== Example 
     473      #     <% file_control :file, :label => "File" %> 
    403474      def file_control(col, attrs = {}) 
    404475        errorify_field(attrs, col) 
    …… 
    406477      end 
    407478       
     479      # Provides a HTML file input 
     480      # 
     481      # ==== Example 
     482      #     <% file_field :name => "file", :label => "File" %> 
    408483      def file_field(attrs = {}) 
    409484        attrs.merge!(:type => "file")