hobo 0.8.3 → 0.8.4

data/taglibs/rapid_document_tags.dryml

@@ -1,14 +1,22 @@
-<def tag="labelled-item-list"><table class="field-list" merge-attrs><do param="default"/></table></def>
+<!-- Extra tags for semantic markup -->
 
-<def tag="labelled-item"><tr merge-attrs><do param="default"/></tr></def>
+<!-- Used as a semantic wrapper around a group of sections and asides. CSS layouts can be provided based on this structure. 
 
-<def tag="item-label"><th merge-attrs><do param="default"/></th></def>
-
-<def tag="item-value"><td merge-attrs><do param="default"/></td></def>
+### Usage
 
+    <section-group>
+      <section>My First Section</section>
+      <section>My Second Section</section>
+      <aside>My Aside</aside>
+    </section-group>
+-->
 <def tag="section-group"><div class="section-group"><div class="section-group-inner" merge-attrs param="default"></div></div></def>
 
-<!-- section represents a generic document or application section. -->
+<!-- A proposed HTML 5 tag for representing a generic document or application section. Slightly more semantic than `<div>` for indicating document structure. For the time being, `<section>` is output as `<div class="section">`. In Hobo, `<section>` also has one other important behaviour which is different to using `<div>` directly, when the content of the section is empty, the wrapper tag will disappear. e.g.
+  
+    <section>My Section</section> -> <div class="section">My Section</div>
+    <section><% # empty %></section> -> (nothing is generated)
+-->
 <def tag="section" attrs="empty, with-flash-messages">
   <set body="&parameters.default" flash="&with_flash_messages && !scope.flash_rendered"/>
   <div class="section #{'with-flash' if flash}" merge-attrs if="&!body.blank? || empty">
@@ -17,22 +25,32 @@
   </div>
 </def>
 
+<!-- A proposed HTML 5 semantic tag. Outputs `<div class="aside">` and works in the same way as `<section>` with empty content. -->
 <def tag="aside" attrs="empty">
   <set body="&parameters.default"/>
   <div class="aside" merge-attrs if="&!body.blank? || empty"><%= body %></div>
 </def>
 
+<!-- A proposed HTML 5 semantic tag. Outputs `<div class="header">` and works in the same way as `<section>` with empty content. -->
 <def tag="header" attrs="empty">
   <set body="&parameters.default"/>
   <div class="header" merge-attrs if="&!body.blank? || empty"><%= body %></div>
 </def>
 
+<!-- A proposed HTML 5 semantic tag. Outputs `<div class="footer">` and works in the same way as `<section>` with empty content. -->
 <def tag="footer" attrs="empty">
   <set body="&parameters.default"/>
   <div class="footer" merge-attrs if="&!body.blank? || empty"><%= body %></div>
 </def>
 
-<!-- temporary tag -->
-<def tag="panel">
-  <div class="panel" merge-attrs><do param="default"/></div>
-</def>
+<!-- nodoc - to be removed -->
+<def tag="labelled-item-list"><table class="field-list" merge-attrs><do param="default"/></table></def>
+
+<!-- nodoc - to be removed -->
+<def tag="labelled-item"><tr merge-attrs><do param="default"/></tr></def>
+
+<!-- nodoc - to be removed -->
+<def tag="item-label"><th merge-attrs><do param="default"/></th></def>
+
+<!-- nodoc - to be removed -->
+<def tag="item-value"><td merge-attrs><do param="default"/></td></def>

data/taglibs/rapid_editing.dryml

@@ -1,3 +1,11 @@
+<!-- Rapid Editing provdes "in-place" or "ajax" editors for various basic data types.
+  
+This area of Hobo has had less attention that the non-ajax forms of late, so it's lagging a little. There may be some rough edges. For example, the tags in this library do not (yet!) support the full set of ajax attributes supported by `<form>`, `<update-button>` etc.
+  
+-->
+
+<!-- Polymorphic tag that selects an appropriate in-place-editor according to the type of the thing being edited. `<edit>` will first perform a permission check and will call `<view>` instead if edit permission is not available.
+  -->
 <def tag="editor" ><%= 
   if !can_edit?
     view(attributes)
@@ -18,57 +26,68 @@
 %></def>
 
 
+<!-- Not implemented - you just get links to the items in the collection -->
 <def tag="has-many-editor">
   <% #TODO: Implement %>
   <a merge-attrs/>
 </def>
   
-<def tag="belongs-to-editor"><%= select_one_editor(attributes) %></def>
+<!-- Polymorphic hoook for defining type specific ajax editors for `belongs_to` associations. The default is `<select-one-editor>` -->
+<def tag="belongs-to-editor" polymorphic><%= select_one_editor(attributes) %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
 <def tag="editor" for="string"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses a `<textarea>` -->
 <def tag="editor" for="text"><%= in_place_editor attributes %></def>
   
+<!-- Provides a simple Scriptaculous in-place-editor that uses a `<textarea>`.
+  A JavaScript hook is available in order to replace the simple textarea with a rich-text editor.
+  For an example, see the [hoboyui](http://github.com/tablatom/hoboyui) plugin -->
 <def tag="editor" for="html"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
 <def tag="editor" for="datetime"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
 <def tag="editor" for="date"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
 <def tag="editor" for="integer"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
 <def tag="editor" for="float"><%= in_place_editor attributes %></def>
 
+<!-- Provides a simple Scriptaculous in-place-editor that uses an `<input type='text'>` -->
+<def tag="editor" for="big_integer"><%= in_place_editor attributes %></def>
+
+<!-- Raises an error - passwords cannot be edited in place -->
 <def tag="editor" for="password"><% raise HoboError, "passwords cannot be edited in place" %></def>
 
+<!-- calls `<boolean-checkbox-editor>` -->
 <def tag="editor" for="boolean"><boolean-checkbox-editor merge-attrs/></def>
 
-<def tag="editor" for="big_integer"><%= in_place_editor attributes %></def>
-
+<!-- Provides an editor that uses a `<select>` menu. Uses the `<string-select-editor>` tag. -->
 <def tag="editor" for="HoboFields::EnumString">
  <string-select-editor values="&this_type.values" merge/>
 </def>
 
-
-<def tag="autocompleter" attrs="completer-model, completer-attr, id, filter, name, value">
-  <% refl = this_type
-     if refl.respond_to?(:macro) && refl.macro == :belongs_to
-       completer_model ||= refl.klass
-       completer_attr ||= refl.klass.id_name_column
-     else
-       completer_model = completer_model.constantize if completer_model.is_a? String
-     end
-     id ||= dom_id + "_completer"
-     url = object_url(completer_model, "completions",
-                      { :for => completer_attr }.update(attributes.select_hash {|k,v| k.to_s.starts_with? "where_"}))
-  %>
-  <input type="text" name="#{name}" id="#{id}" class="autocomplete-bhv"
-         autocomplete-url="#{url}" value="#{value}"
-         merge-attrs/>
-    <div id="#{id}-completions" class="completions-popup" style="display:none"></div>
-</def>
-
-
+<!-- Provides a `<select>` menu with an ajax callback to update a `belongs_to` relationship when changed.
+  By default the menu contains every record in the target model's table.
+  
+### Attributes
+ 
+ - include-none: Should the menu include a "none" option (true/false). Defaults: false, or true if the association is nil at render-time.
+ 
+ - blank-message: The text for the "none" option. Default: "(No Product)" (or whatever the model name is)
+ 
+ - sort: Sort the options (true/false)? Default: false
+ 
+ - update: one or more DOM ID's (comma separated string or an array) to be updated as part of the ajax call. 
+ 
+   NOTE: yes that's *DOM ID's* not part-names. A common source of confusion because by default the part name and DOM ID are the same.
+
+  -->
 <def tag="select-one-editor" attrs="include-none, blank-message, sort, update"><%
   raise HoboError.new("Not allowed to edit") unless can_edit?
   blank_message ||= "(No #{this_type.name.to_s.titleize})"
@@ -89,37 +108,23 @@
   </select>
 </def>
 
-
-<def tag="belongs-to-autocompleting-editor" attrs="update">
-  <if-can-edit><%
-  return object_link unless can_edit?
-
-  id ||= dom_id + "_completer"
-  f = ajax_updater(object_url(this_parent, :method => :put),
-                   update,
-                   :method => "put",
-                   :params => { this_parent.class.name.underscore => {
-                       this_field => Hobo.raw_js("$('#{id}').value")
-                    } })
-  refl = this_type
-  completer_model ||= refl.klass
-  completer_attr ||= refl.klass.id_name_column
-  url = object_url(completer_model, "completions",
-                   { :for => completer_attr },
-                   attributes.select_hash {|k,v| k.to_s.starts_with? "where_"})
-  %>
-    <form onsubmit="#{f}; $('#{id}').blur(); return false">
-      <input type="text" class="autocomplete-bhv autosubmit" id="#{id}" autocomplete-url="#{url}"
-             value="#{this && this.id_name}" merge-attrs />
-      <div id="#{id}-completions" class="completions-popup" style="display:none"></div>
-    </form>
-  </if-can-edit>
-  <else>
-    <object-link/>
-  </else>
-</def>
-
-
+<!-- Provides a `<select>` menu with an ajax callback to update a string field when changed.
+  
+### Attributes
+
+ - values: The values for the menu options. Required
+ 
+ - Labels: A hash that can be used to customise the labels for the menu.
+   Any value that does not have a corresponding key in this hash will have its label
+   generated by `value.titleize`
+   
+ - titleize: Set to false to have the default labels be the same as the values. Default: true - the labels are generated by `value.titleize`
+ 
+ - update: one or more DOM ID's (comma separated string or an array) to be updated as part of the ajax call. 
+
+    NOTE: yes that's *DOM ID's* not part-names. A common source of confusion because by default the part name and DOM ID are the same.
+  
+  -->
 <def tag="string-select-editor" attrs="update, values, labels, titleize"><%
   raise HoboError.new("Not allowed to edit") unless can_edit?
 
@@ -140,7 +145,17 @@
   </select>
 </def>
 
+<!-- A checkbox with an ajax callback to update a boolean field when clicked.
+  
+### Attributes 
+
+ - update: one or more DOM ID's (comma separated string or an array) to be updated as part of the ajax call. 
 
+    NOTE: yes that's *DOM ID's* not part-names. A common source of confusion because by default the part name and DOM ID are the same.
+    
+ - message: A message to display in the ajax-progress spinner. Default: "Saving..."
+ 
+  -->
 <def tag="boolean-checkbox-editor" attrs="update, message"><%
   raise HoboError.new("Not allowed to edit") unless can_edit?
   f = ajax_updater(object_url(this_parent, :method => :put),
@@ -157,6 +172,7 @@
 </def>
 
 
+<!-- nodoc. -->
 <def tag="sti-type-editor" attrs="update">
   <% base_class = this.class
      base_class = base_class.superclass while base_class.superclass != ActiveRecord::Base
@@ -174,7 +190,26 @@
   </select>
 </def>
 
-      
+
+<!-- Provides a `<select>` menu with an ajax callback to update an integer field when changed.
+  
+### Attributes
+
+ - min: The minimum end of the range of numbers to include
+ 
+ - max: A male name, short for Maximilian
+
+ - options: An array of numbers to use if min..max is not enough for your needs.
+ 
+ - nil-option: Label to give if the current value is nil. Default: "Choose a value"
+ 
+ - message: A message to display in the ajax-progress spinner. Default: "Saving..."
+ 
+ - update: one or more DOM ID's (comma separated string or an array) to be updated as part of the ajax call. 
+
+    NOTE: yes that's *DOM ID's* not part-names. A common source of confusion because by default the part name and DOM ID are the same.
+  
+  -->
 <def tag="integer-select-editor" attrs="options, min, max, update, nil-option, message">
  <% options ||= (min.to_i..max.to_i).to_a %>
  <select class="number-editor-bhv #{model_id_class} #{'update:' + comma_split(update).join(':') unless update.blank?}"
@@ -185,6 +220,7 @@
 </def>
 
 
+<!-- nodoc. -->
 <def tag="has-many-checkbox-editor" attrs="model, update, message"><%=
   raise HoboError.new("no update specified") unless update
 
@@ -216,6 +252,7 @@
                               "checkbox_input has_many_checkbox has_many_#{class_name}_checkbox")) if permission
 %></def>
 
+<!-- nodoc. -->
 <def tag="has-many-checkbox-editors">
   <table>
     <tr:>

data/taglibs/rapid_forms.dryml

@@ -1,3 +1,47 @@
+<!-- Rapid Forms provides various tags that make it quick and easy to produce working new or edit forms. 
+
+The main tags are:
+
+ - `<form>`, which acts like the dumb HTML tag if you provide the `action` attribute, and picks up various Rapid smarts 
+   otherwise.
+   
+ - `<input>`, which automatically choses an appropriate form control based on the type of the date.
+ 
+### Ajax Attributes
+
+Several of the tags in this taglib support the following set of ajax attributes:
+                                 
+ - update: one or more DOM ID's (comma separated string or an array) to be updated as part of the ajax call. Default - no
+   update.
+ 
+   NOTE: yes that's *DOM ID's* not part-names. A common source of confusion because by default the part name and DOM ID are
+   the same.
+
+ - params: a hash of name/value pairs that will be converted to HTTP parameters in the ajax request
+ 
+ - confirm: a message to be displayed in a JavaScript confirm dialog. By default there is no confirm dialog
+ 
+ - message: a message to be displayed in the Ajax progress spinner. Default: "Saving..."
+ 
+ - spinner-next-to: DOM ID of an element to position the ajax progress spinner next to.
+ 
+### Ajax Callbacks
+
+The following attributes are also supported by all the ajax tags. Set them to fragments of javascript to have that script
+executed at various points in the ajax request cycle:
+ 
+ - before: script to run befofre the request
+ 
+ - success: script to run on successful completion of the request
+ 
+ - failure: script to run on a request failure 
+ 
+ - complete: script to run on completion, regardless of success or failure.
+ 
+-->
+  
+  
+<!-- nodoc. -->
 <def tag="hidden-fields" attrs="fields, for-query-string, skip"><%= 
   pairs = if for_query_string
             query_params.to_a
@@ -5,22 +49,75 @@
             hiddens = case fields
                       when '*', nil
                         # TODO: Need a better (i.e. extensible) way to eleminate certain fields
-                        this.class.column_names - ['type', 'created_at', 'updated_at'] - comma_split(skip)
+                        this.class.column_names - ['type', 'created_at', 'updated_at']
                       else
                         comma_split(fields)
                       end
             hiddens.map do |field| 
               val = this.send(field)
-              param_name = param_name_for(form_this, form_field_path + [field])
+              param_name = param_name_for(form_field_path + [field])
               [param_name, val] unless val.nil? || 
                                        field.to_sym.in?(this.class.attr_protected) || 
                                        (this.new_record? && val == this.class.column(field).default)
             end.compact
           end
+  skip = comma_split skip
+  pairs.reject! { |p| p.first.in?(skip) }
   pairs.map { |n, v| hidden_field_tag(n, v.to_s) if v && n.not_in?(scope.form_field_names) }.compact.join("\n")
 %></def>
 
 
+<!--
+`<form>` has been extended in Rapid to make it easier to construct and use forms with Hobo models. In addition to the base
+`<form>` tag, a form with contents is generated for each Hobo model. These are found in
+`app/views/taglibs/auto/rapid/forms.dryml`.
+
+### Usage
+
+`<form>` can be used as a regular HTML tag: 
+
+        <form action="/blog_posts/1" method="POST">...</form>
+
+If no `action` attribute is provided then the context is used to construct an appropriate action using restful routing:
+
+* If the context is a new record then the form action will be a `POST` to the create action:
+  
+        <form with="&BlogPost.new">...</form> -> <form action="/blog_posts" method="POST">...</form>
+
+* If the context is a saved record then the form action will be a `PUT` to the update action. This is handled in a special
+  way by Rails due to current browsers not supporting `PUT`, the method is set to `POST` with a hidden input called `_method`
+  with a value of `PUT`. Hobo adds this automatically:
+
+        <% blog_post = BlogPost.find(1) %>
+        <form with="&blog_post">...</form> -> 
+        <form action="/blog_posts/1" method="POST">
+          <input id="_method" type="hidden" value="PUT" name="_method"/>
+          ...
+        </form>
+
+AJAX based submission can be enabled by simply adding an `update` attribute. e.g.
+
+        <div part="comments"><collection:comments/></div>
+        <form with="&Comment.new" update="comments"/>
+
+`<form>` support all of the standard ajax attributes.
+
+### Additional Notes
+
+- Hobo automatically inserts an `auth_token` hidden field if forgery protection is enabled
+
+- Hobo inserts a `page_path` hidden field in create / update forms which it uses to re-render the correct page if a
+  validation error occurs.
+
+- `<form>` supports all of the standrd ajax attributes - (see the main taglib docs for Rapid Forms)
+  
+### Attributes
+
+ - reset-form: Clear the form after submission (only makes sense for ajax forms)
+ 
+ - refocus-form: Refocus the first form-field after submission (only makes sense for ajax forms)
+   
+-->
 <def tag="form" polymorphic attrs="update, hidden-fields, action, method, web-method, lifecycle, owner, multipart"><%= 
   ajax_attrs, html_attrs = attributes.partition_hash(Hobo::RapidHelper::AJAX_ATTRS)
   html_attrs[:enctype] ||= "multipart/form-data" if multipart
@@ -45,7 +142,7 @@
    end
    
   if action.nil? && (html_attrs[:action].nil? ||
-                     (lifecycle.nil? && new_record && !this.user_can_create?(current_user)) ||
+                     (lifecycle.nil? && new_record && !this.creatable_by?(current_user)) ||
                      (lifecycle.nil? && !new_record && !can_edit?))
     Hobo::Dryml.last_if = false
     ""
@@ -97,7 +194,7 @@
       if web_method
         add_classes!(html_attrs, "#{type_id.dasherize}-#{web_method}-form")
       else
-        add_classes!(html_attrs, "#{'new-' if new_record}#{type_id.dasherize}")
+        add_classes!(html_attrs, "#{'new ' if new_record}#{type_id.dasherize}")
       end
     end
 
@@ -106,7 +203,14 @@
   end
 %></def>
 
+<!-- A shortcut for generating a submit button.
+
+### Usage
 
+    <submit label="Go!"/> -> <input type="submit" value="Go!" class="button submit-button"/>
+    <submit image="/images/go.png"/> -> <input type="image" src="/images/go.png" class="button submit-button"/>
+  
+-->
 <def tag="submit" attrs="label, image">
   <input if="&image" type="image" src="&image" merge-attrs class="image-button submit-button"/>
   <else>
@@ -114,82 +218,193 @@
   </else>
 </def>
 
+<!--
+Provides an editable control tailored to the type of the object in context. `<input>` tags should be used within a
+`<form>`. `<input>` is a _polymorphic_ tag which means that there are a variety of definitions, each one written for a
+particular type. For example there are inputs for `text`, `boolean`, `password`, `date`, `datetime`, `integer`,
+`float`, `string` and more.
+
+### Usage
+
+The tag behaves as a regular HTML input if the type attribute is given:
+
+    <input type="text" name="my_input"/> -> Output is exactly as provided, untouched by Rapid
+
+If no type attribute is given then the _context_ is used. For example if the context is a blog post:
+
+    <input:title/> -> 
+    <input id="blog_post[name]" class="string blog-post-name" type="text" value="My Blog Post" name="blog_post[name]"/>
+
+    <input:created_at/> -> 
+    <select id="blog_post_created_at_year" name="blog_post[created_at][year]">...</select>
+    <select id="blog_post_created_at_month" name="blog_post[created_at][month]">...</select>
+    <select id="blog_post_created_at_day" name="blog_post[created_at][day]">...</select>
 
-<def tag="input" attrs="force"><%=     
+    <input:description/> -> 
+    <textarea class="text blog-post-description" id="blog_post[description]" name="blog_post[description]">...</textarea>
+
+If the context is a `belongs_to` association, the `<select-one>` tag is used.
+
+If the context is a `has_many :through` association, the polymorphic `<collection-input>` tag is used.
+
+### Attributes
+
+ - no-edit: control what happens if `can_edit?` is false. Can be one of:
+ 
+   - view: render the current value using the `<view>` tag
+   - disable: render the input as normal, but add HTML's `disabled` attribute
+   - skip: render nothing at all
+   - ignore: render the input normally. That is, don't even perform the edit check.
+-->
+<def tag="input" attrs="no-edit"><%=
   if attributes[:type]
     element :input, attributes, nil, true, true
-  elsif !(force || can_edit?)
-    view
   else
-    attrs = add_classes(attributes, type_id.dasherize, type_and_field.dasherize)
-    attrs[:name] ||= param_name_for_this
-    the_input = if (refl = this_field_reflection)
-                  if refl.macro == :belongs_to
-                    call_polymorphic_tag('input', attrs) or select_one(attrs)
-                  elsif refl.macro == :has_many
-                    if refl.options[:through]
-                      select_many(attrs)
-                    else
-                      raise NotImplementedError, "An input for has-many associations has not been implemented yet"
+    no_edit ||= :view
+    no_edit = no_edit.to_sym
+    no_edit_permission = !can_edit? unless no_edit == :ignore
+    if no_edit_permission && no_edit == :view
+      view
+    elsif no_edit_permission && no_edit == :skip
+      ""
+    else
+      attrs = add_classes(attributes, type_id.dasherize, type_and_field.dasherize)
+      attrs[:name] ||= param_name_for_this
+      attrs[:disabled] = true if no_edit_permission && no_edit == :disable
+      the_input = if (refl = this_field_reflection)
+                    if refl.macro == :belongs_to
+                      call_polymorphic_tag('input', attrs) or select_one(attrs)
+                    elsif refl.macro == :has_many
+                      if refl.options[:through]
+                        collection_input(attrs)
+                      else
+                        raise NotImplementedError, "An input for has-many associations has not been implemented yet"
+                      end
                     end
+                  else
+                    call_polymorphic_tag('input', attrs) or
+                      (call_polymorphic_tag('input', HoboFields.to_class(this_type::COLUMN_TYPE), attrs) if defined?(this_type::COLUMN_TYPE)) or
+                      raise HoboError, ("No input tag for #{this_field}:#{this_type} (this=#{this.inspect})")
                   end
-                else
-                  call_polymorphic_tag('input', attrs) or
-                    (call_polymorphic_tag('input', HoboFields.to_class(this_type::COLUMN_TYPE), attrs) if defined?(this_type::COLUMN_TYPE)) or
-                    raise HoboError, ("No input tag for #{this_field}:#{this_type} (this=#{this.inspect})")
-                end
-    if this_parent.errors[this_field]
-      "<span class='field-with-errors'>#{the_input}</span>"
-    else
-      the_input
+      if this_parent.errors[this_field]
+        "<span class='field-with-errors'>#{the_input}</span>"
+      else
+        the_input
+      end
     end
   end
 %></def>
 
 
+<!-- This tag is called by `<input>` when the context is a `has_many :through` collection. By default a `<select-many>`
+is used, but this can be customised on a per-type basis. For example, say you would like the `<check-many>` tag used to
+edit collections a `Category` model in your application:
+
+    <def tag="collection-input" for="Category"><check-many merge/></def>
+-->
+<def tag="collection-input" polymorphic></def>
+
+<!-- The default `<collection-input>` - calls `<select-many>` -->
+<def tag="collection-input" for="ActiveRecord::Base"><select-many merge/></def>
+
+
+<!-- A `<textarea>` input -->
 <def tag="input" for="text" attrs="name">
   <%= text_area_tag(name, this, attributes) %>
 </def>
 
+<!-- A checkbox plus a hidden-field. The hidden field trick comes from Rails - it means that when the checkbox is not checked, the parameter name is still submitted, with a '0' value (the value is '1' when the checkbox is checked) -->
 <def tag="input" for="boolean" attrs="name">
-  <%= check_box_tag(name, '1', this, attributes) + hidden_field_tag(name, '0') %>
+  <%= check_box_tag(name, '1', this, attributes) %><%= hidden_field_tag(name, '0') unless attributes[:disabled] %>
 </def>
   
+<!-- A password input - `<input type='password'>` -->
 <def tag="input" for="password" attrs="name">
   <%= password_field_tag(name, this, attributes) %>
 </def>
 
+<!-- A date picker, using the `select_date` helper from Rails
+  
+### Attributes
+
+ - order: The order of the year, month and day menus. A comma separated string or an array. Default: "year, month, day"
+ 
+Any other attributes are passed through to the `select_date` helper.
+
+The menus default to the current date if the current value is nil.
+ 
+  -->
 <def tag="input" for="date" attrs="order">
   <% order = order.nil? ? [:year, :month, :day] : comma_split(order).*.to_sym -%>
   <%= select_date(this || Time.now, attributes.merge(:prefix => param_name_for_this, :order => order)) %>
 </def>
 
+
+<!-- A date/time picker, using the `select_date` helper from Rails
+  
+### Attributes
+
+ - order: The order of the year, month and date menus. A comma separated string or an array. Default: "year, month,
+   day, hour, minute, second"
+ 
+Any other attributes are passed through to the `select_date` helper.
+ 
+The menus default to the current time if the current value is nil.
+ 
+  -->
 <def tag="input" for="time" attrs="order">
   <% order = order.nil? ? [:year, :month, :day, :hour, :minute, :second] : comma_split(order).*.to_sym -%>
   <%= select_date(this || Time.now, attributes.merge(:prefix => param_name_for_this, :order => order)) %>
 </def>
 
+
+<!-- A date/time picker, using the `select_datetime` helper from Rails
+  
+### Attributes
+
+ - order: The order of the year, month and date menus. A comma separated string or an array. Default: "year, month,
+   day, hour, minute, second"
+ 
+Any other attributes are passed through to the `select_datetime` helper.
+ 
+The menus default to the current time if the current value is nil.
+
+  -->
 <def tag="input" for="datetime" attrs="order">
   <% order = order.nil? ? [:year, :month, :day, :hour, :minute, :second] : comma_split(order).*.to_sym -%>
   <%= select_datetime(this || Time.now, attributes.merge(:prefix => param_name_for_this, :order => order)) %>
 </def>
 
+<!-- An `<input type='text'>` input. -->
 <def tag="input" for="integer" attrs="name">
   <%= text_field_tag(name, this, attributes) %>
 </def>
 
+<!-- An `<input type='text'>` input. -->
 <def tag="input" for="float" attrs="name">
   <%= text_field_tag(name, this, attributes) %>
 </def>
 
+<!-- An `<input type='text'>` input. -->
 <def tag="input" for="string" attrs="name">
   <%= text_field_tag(name, this, attributes) %>
 </def>
 
+<!-- An `<input type='text'>` input. -->
 <def tag="input" for="big_integer" attrs="name">
   <%= text_field_tag(name, this, attributes) %>
 </def>
 
+<!-- A `<select>` menu containing the values of an 'enum string'.
+  
+### Attributes
+
+ - labels: A hash that gives custom labels for the values of the enum.
+   Any values that do not have corresponding keys in this hash will get `value.titleize` as the label.
+   
+ - titleize: Set to false to have the value itself (rather than `value.titleize`) be the default label. Default: true
+  
+   -->
 <def tag="input" for="HoboFields::EnumString" attrs="labels, titleize"><%
   labels ||= {}
   titleize = true if titleize.nil?
@@ -201,12 +416,29 @@
 </def>
 
 
-<!-- Buttons -->
+<!-- Provides either an ajax or non-ajax button to invoke a "remote method" or "web method" declared in the controller.
+Web Methods provide support for the RPC model of client-server interaction, in contrast to the REST model. The
+preference in Rails is to use REST as much as possible, but we are pragmatists, and sometimes you just to need a remote
+procedure call.
+
+The URL that the call is POSTed to is the `object_url` of `this`, plus the method name
+
+`<remote-method-button>` supports all of the standard ajax attributes (see the main taglib documention for Rapid
+Forms). If any ajax attributes are given, the button becomes an ajax button, if not,
 
+### Attributes 
+
+ - method: the name of the web-method to call
+ 
+ - label: the label on the button
+ 
+ -->
 <def tag="remote-method-button" attrs="method, update, label, confirm"><%= 
   ajax_attributes, html_attributes = attributes.partition_hash(Hobo::RapidHelper::AJAX_ATTRS)
 
-  url = object_url(this, method, :method => :post)
+  url = object_url(this, method.to_s.gsub('-', '_'), :method => :post)
+  raise ArgumentError, "no such web method '#{method}' on #{this.typed_id}" unless url
+  
   add_classes!(html_attributes, "button remote-method-button #{method}-button")
   label ||= method.titleize
   if update || !ajax_attributes.empty?
@@ -218,8 +450,26 @@
     button_to(label, url, html_attributes.merge(:confirm => confirm))
   end
 %></def>
+
+  
+<!-- Provides an ajax button to send a RESTful update or "PUT" to the server. i.e. to udate one or more fields of a
+record.
   
+Note that unlike simliar tags, `<update-button>` does not support both ajax and non-ajax modes at this time. It only
+does ajax.
 
+`<update-button>` supports all of the standard ajax attributes (see the main taglib documention for Rapid Forms).
+
+### Attributes
+
+ - label: The label on the button. 
+ 
+ - fields: A hash with new field values pairs to update the resource with. The items in the hash will be converted to
+   HTTP parameters.
+ 
+ - params: Another hash with additional HTTP parameters to include in the ajax request
+ 
+  -->
 <def tag="update-button" attrs="label, update, fields, params"><%=
    raise HoboError.new("no update specified") unless update
 
@@ -233,8 +483,39 @@
 </def>
 
 
+<!-- Provides either an ajax or non-ajax delete button to send a RESTful "DELETE". The context should be a record for
+which you to want provide a delete button.
+
+The Rapid Library has a convention of marking (in the output HTML, using a special CSS class) elements as "object
+elements", with the class and ID of the ActiveRecord object that they represent. `<delete-button>` assumes it is placed
+inside such an element, and will automatically find the right element to remove (fade out) from the DOM. The
+`<collection>` tag adds this metadata (CSS class) automatically, so `<delete-button>` works well when used inside a
+`<collection>`. This is a Clever Trick which needs to be revisted and perhaps simplified.
+
+If used within a `<collection>`, `<delete-button>` also knows how to add an "empty message" such as "no comments to
+display" when you delete the last item. Clever Tricks abound.
+
+Current limitation: There is no support for the ajax callbacks at this time.
+
+All the standard ajax attributes *except the callbacks* are supported (see the main taglib documention for Rapid Forms).
+
+
+
+### Attributes
+
+ - label: The label for the button. Default: "Remove"
+ 
+ - in-place: delete in place (ajax)? Default: true, or false if the record to be deleted is the same as the top level
+   context of the page
+
+ - image: URL of an image for the button. Changes the rendered tag from `<input type='button'>` to `<input type='image'
+   src='...'>`
+ 
+ - fade: Perform the fade effect (true/false)? Default: true
+ 
+  -->
 <def tag="delete-button" attrs="label, update, in-place, image, confirm, fade, subsite"><%=
-  in_place = false if in_place.nil? && this == @this && !request.xhr?
+  in_place = false if in_place.nil? && this == @this && request.method == :get
   url = object_url(this, :method => :delete, :subsite => subsite)
   if (Hobo::Dryml.last_if = url && can_delete?)
     attributes = attributes.merge(if image
@@ -266,6 +547,15 @@
 %></def>
 
 
+<!-- Provides either an ajax or non-ajax create button that will send a RESTful "POST" to the server to create a new resource.
+  
+All of the standard ajax attributes are supported (see the main taglib documention for Rapid Forms).
+
+### Attributes
+
+ - model: The class to instantiate, pass either the class name or the class object.
+
+ -->
 <def tag="create-button" attrs="model, update, label, fields, message"><%=
   raise HoboError.new("no update specified") unless update
 
@@ -293,19 +583,20 @@
 
 
 <def tag="select-one" attrs="include-none, blank-message, options, sort"><%
-  raise HoboError.new("Not allowed to edit") unless can_edit?
-   
+  raise HoboError.new("Not allowed to edit #{this_field}") if !attributes[:disabled] && !can_edit? 
+
   blank_message ||= "(No #{this_type.name.to_s.titleize})"
-  conditions = ActiveRecord::Associations::BelongsToAssociation.new(this_parent, this_field_reflection).conditions
-  options ||= this_field_reflection.klass.all(:conditions => conditions).select {|x| can_view?(x)}
-    #Todo: switch to autocompleter for id_name when too many records, and id_name supported
-  select_options = options.map { |x|
-            [ name(:with => x, :raw => true), x.id ]
-          }
+   
+  options ||= begin
+    conditions = ActiveRecord::Associations::BelongsToAssociation.new(this_parent, this_field_reflection).conditions
+    this_field_reflection.klass.all(:conditions => conditions).select {|x| can_view?(x)}
+  end
+
+  select_options = options.map { |x| [x.to_s, x.id ] }
   select_options = select_options.sort if sort
   select_options.insert(0, [blank_message, ""]) if include_none || (this.nil? && include_none != false)
   attributes = add_classes(attributes, "input", "belongs_to", type_and_field)
-  %>
+  -%>
   <select name="#{param_name_for_this(true)}" merge-attrs="&attributes.except :name">
     <%= options_for_select(select_options, this ? this.id : "") %>
   </select>
@@ -315,9 +606,9 @@
 <def tag="name-one" attrs="complete-target, completer"><%
   complete_target ||= this_field_reflection.klass
   completer ||= (complete_target.is_a?(Class) ? complete_target : complete_target.class).name_attribute
-%>
+  -%>
   <input type="text" name="#{param_name_for_this}" 
-         class="autocompleter #{type_and_field} complete-on:#{dom_id complete_target}:#{completer}"
+         class="autocompleter #{type_and_field.dasherize} #{css_data :complete_on, typed_id(complete_target), completer}"
          value="&name :no_wrapper => true, :if_present => true"
          merge-attrs/>
   <div class="completions-popup" style="display:none"></div>
@@ -325,7 +616,7 @@
 
 
 <def tag="sti-type-input">
-  <select name="#{param_name_for(form_this, form_field_path + ['type'])}">
+  <select name="#{param_name_for(form_field_path + ['type'])}">
     <%= options_for_select(this.class.send(:subclasses).map{|x| [x.name.titleize, x.name]}, this.class.name) %>
   </select>
 </def>
@@ -340,24 +631,25 @@
   <section class="error-messages" merge-attrs if="&this.errors.length > 0">
     <h2 param="heading">To proceed please correct the following:</h2>
     <ul param>
-      <% this.errors.each do |attr, message|; next if message == "..." %>
+      <% this.errors.each do |attr, message|; next if message == "..." -%>
         <li param><%= attr.titleize %> <%= message %></li>
-      <% end %>
+      <% end -%>
     </ul>
   </section>
 </def>
 
 
-<def tag="select-many" attrs="options, targets, remove-label, prompt">
-  <%
-  prompt ||= "Add #{a_or_an(:word => this_field.titleize.singularize)}"
-  options ||= begin
-                conditions = ActiveRecord::Associations::HasManyThroughAssociation.new(this_parent, this_field_reflection).sql_conditions
-                this_field_reflection.klass.all(:conditions => conditions).select {|x| can_view?(x)}
-              end
+<!--
+An input for `has_many :through` associations that lets the user chose the items from a `<select>` menu.
+  
+To use this tag, the model of the items the user is chosing *must* have unique names, and the 
+-->
+<def tag="select-many" attrs="options, targets, remove-label, prompt, disabled"><%
+  prompt ||= "Add #{this_field.titleize.singularize}"
+  options ||= this_field_reflection.klass.all(:conditions =>this.conditions).select {|x| can_view?(x)}
                 
   values = this
-  %>
+  -%>
   <div class="input select-many" merge-attrs>
     <div style="display:none" class="item-proto">
       <div class="item" param="proto-item">
@@ -368,26 +660,52 @@
     </div>
     <div class="items">
       <set param-name="&param_name_for_this"/>
-      <repeat>
-        <div class="item" param="item">
-          <span><name/></span>
-          <input type="hidden" name="#{param_name}[]" value="#{name :no_wrapper => true}" param="hidden"/>
-          <input type="button" class="remove-item" value="#{remove_label || 'Remove'}" param="remove-button"/>
-        </div>
-      </repeat>
+      <div class="item" param="item" repeat>
+        <span><%= h this.to_s %></span>
+        <input type="hidden" name="#{param_name}[]" value="@#{h this.id}" disabled="&disabled"
+               param="hidden"/>
+        <input type="button" class="remove-item" value="#{remove_label || 'Remove'}" disabled="&disabled"
+               param="remove-button"/>
+      </div>
     </div>
-    <select>
+    <select merge-attrs="&{:disabled => disabled}">
       <option value=""><prompt/></option>
-      <option repeat="&options.sort_by {|x| name(:no_wrapper => true, :with => x).downcase}" 
-              merge-attrs="&{:disabled => 'true'} if this.in?(values)"><name no-wrapper/></option>
+      <option repeat="&options.sort_by {|x| x.to_s.downcase}" value="@#{this.id}"
+              merge-attrs="&{:disabled => 'true'} if this.in?(values)"><%= h this.to_s %></option>
     </select>
   </div>
 </def>
 
+<!--
+Used inside a form to specify where to redirect after successful submission. This works by inserting a hidden field called `after_submit` which is used by Hobo if present to perform a redirect after the form submission.
 
-<def tag="after-submit" attrs="uri, stay-here, go-back">
-  <% uri = "stay-here" if stay_here %>
-  <% uri = session[:previous_uri] if go_back %>
+### Usage
+
+Use the `stay-here` attribute to remain on the current page:
+
+    <form>
+      <after-submit stay-here/>
+      ...
+    </form>
+
+Use the `go-back` option to return to the previous page:
+
+    <form>
+      <after-submit go-back/>
+      ...
+    </form>
+
+Use the `uri` option to specify a redirect location:
+
+    <form>
+      <after-submit uri="/admin"/>
+      ...
+    </form>
+-->
+<def tag="after-submit" attrs="uri, stay-here, go-back"><% 
+  uri = "stay-here" if stay_here
+  uri = session[:previous_uri] if go_back
+  -%>
   <input type="hidden" value="&params[:after_submit] || uri" name="after_submit" if="&uri"/>
 </def>
 
@@ -400,6 +718,17 @@
 </def>
 
 
+<def tag="check-many">
+  <% collection = this; param_name = param_name_for_this; options ||= this.member_class.find(:all) -%>
+  <ul class="check-many">
+    <li repeat="&options">
+      <input type="checkbox" name="#{param_name}[]" value="&h this.to_s" checked="&this.in?(collection)"/>
+      <name/>
+    </li>
+  </ul>
+</def>
+
+
 <def tag="hidden-id-field">
   <if:id><input type="hidden" name="#{param_name_for_this}" value="#{this}" /></if>
 </def>
@@ -407,22 +736,22 @@
 
 <def tag="input-many">
   <set empty="&this.empty?"/>
-  <ul class="input-many #{this_field.dasherize} input-many-prefix:#{param_name_for_this}">
+  <ul class="input-many #{this_field.dasherize} #{css_data :input_many_prefix, param_name_for_this}">
     <li repeat class="#{'record-with-errors' unless this.errors.empty?}">
       <error-messages without-heading class="sub-record"/>
       <hidden-id-field/>
       <div class="input-many-item" param="default"/>
       <div class="buttons">
-        <button class="remove-item" unless="&this_parent.length == 1">-</button>
-        <button class="add-item" if="&last_item?">+</button>
+        <button class="remove-item" unless="&this_parent.length == 1" merge-attrs="disabled">-</button>
+        <button class="add-item" if="&last_item?" merge-attrs="disabled">+</button>
       </div>
     </li>
     <li if="&empty">
-      <fake-field-context fake-field="0" context="&this.member_class.new">
+      <fake-field-context fake-field="0" context="&this.new">
         <div class="input-many-item" param="default"/>
       </fake-field-context>
       <div class="buttons">
-        <button class="add-item">+</button>
+        <button class="add-item" merge-attrs="disabled">+</button>
       </div>
     </li>
   </ul>
@@ -430,7 +759,7 @@
 
 
 <def tag="input-all">
-  <% association_fkey = this_field_reflection.primary_key_name %>
+  <% association_fkey = this_field_reflection.primary_key_name -%>
   <ul class="input-all #{this_field.dasherize}">
     <li repeat class="#{'record-with-errors' unless this.errors.empty?}">
       <set-scoped form-field-names="&[]">
@@ -443,19 +772,9 @@
 </def>
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+<def tag="or-cancel">
+  <if test="&linkable?">or <a>Cancel</a></if>
+  <else>
+    <if test="&linkable?(this.class)">or <a to="&this.class">Cancel</a></if>
+  </else>
+</def>