hobo_rapid 1.4.0.pre2

data/taglibs/i18n/model_name_human.dryml

@@ -0,0 +1,16 @@
+<!-- Wrapper around ActiveModel::Name#human
+
+#### Attributes
+
+ - model - (optional) should be a model class or a record object (default to this)
+ - count - (optional) used to pick the inflected string for the model. It should be an integer.
+ -->
+<def tag="model-name-human" attrs="model, count"><%=
+  model ||= this
+  model = model.class unless model.kind_of? Class
+  # prepare symbolized attributes for merging
+  attrs = {}
+  all_attributes.each_pair{|k,v| attrs[k.to_sym] = v}
+  model.model_name.human( attrs )
+%>
+</def>

data/taglibs/i18n/t.dryml

@@ -0,0 +1,12 @@
+<!-- Simple wrapper around I18n.t.
+
+The tag content is used as the :default option. It is overridden by an explicit 'default' attribute.
+There is a default :count => 1.
+
+### Attributes
+
+ - key: the key to lookup
+ - all the attributes accepted by the wrapped method -->
+<fakedef tag="t" attrs="key">
+<!-- actually defined in i18n.rb -->
+</fakedef>

data/taglibs/inputs/after_submit.dryml

@@ -0,0 +1,32 @@
+<!--
+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.
+
+### 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 page in `session[:previous_uri]`:
+
+    <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>

data/taglibs/inputs/check_many.dryml

@@ -0,0 +1,25 @@
+<!-- Renders a `<ul>` list of checkboxes, one for each of the potential targt in a `has_many` association. The user can check the items they wish to have associated. A typical use might be selecting categories for a blog post.
+
+### Attributes
+
+ - `options` - an array of models that may be added to the collection
+ - `disabled` - if true, sets the disabled flag on all check boxes.
+
+  -->
+<def tag="check-many" attrs="options, disabled"><%
+  collection = this
+  param_name = param_name_for_this
+  options ||= begin
+    conditions = ActiveRecord::Associations::BelongsToAssociation.new(this_parent, this_field_reflection).send(:conditions)
+    this_field_reflection.klass.all(:conditions => conditions, :limit => 100).select {|x| can_view?(x)}
+  end
+  -%>
+  <ul class="check-many" param="default" merge-attrs>
+    <input type="hidden" name="#{param_name}[]" value=""/><% # ensure all items are removed when nothing checked
+    %>
+    <li repeat="&options" param>
+      <input id="#{dom_id(this, :check_many)}" type="checkbox" name="#{param_name}[]" value="@#{this.id}" checked="&this.in?(collection)" disabled="&disabled"/>
+      <label for="#{dom_id(this, :check_many)}"><name param/></label>
+    </li>
+  </ul>
+</def>

data/taglibs/inputs/collection_input.dryml

@@ -0,0 +1,10 @@
+<!-- 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>

data/taglibs/inputs/hidden_field.dryml

@@ -0,0 +1,48 @@
+<%# creates hidden inputs for the specified fields.
+
+### Attributes
+
+- `fields`: the fields to create hidden inputs for.   If neither fields nor for-query-string is specified, all fields except for `type`, `created_at` and `updated_at` are used.
+
+- `for-query-string`: creates hidden inputs from the query string
+  parameters of our original request.  AJAX parameters are skipped.
+%>
+<def tag="hidden-fields" attrs="fields, skip, for-query-string"><%=
+  pairs = if for_query_string
+            if for_query_string.blank? || for_query_string==true
+              query_parameters_filtered
+            else
+              query_parameters_filtered(:only => comma_split(for_query_string))
+            end
+          else
+            hiddens = case fields
+                      when '*', nil
+                        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_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.to_a.reject { |p| p.first.in?(skip) }.map { |n, v|
+    hidden_field_tag(n, v.to_s) if v && n.not_in?(scope.form_field_names)
+  }.compact.safe_join("\n".html_safe)
+%></def>
+
+
+<%#  a simple wrapper around hidden_field_tag.
+%>
+<def tag="hidden-field">
+  <%= hidden_field_tag(param_name_for_this, this, deunderscore_attributes(attributes)) %>
+</def>
+
+<!-- Renders an `<input type='hidden'>` for the `id` field of the current context -->
+<def tag="hidden-id-field">
+  <if:id><input type="hidden" name="#{param_name_for_this}" value="#{this}" /></if>
+</def>

data/taglibs/inputs/hot_input.dryml

@@ -0,0 +1,50 @@
+<!--
+This tag wraps an input with some ajax that refreshes a part when the input is changed.
+
+An example of when this is useful is when a form is rendered differently depending on what country is selected.   In this example, we'll change the label of the region to state or province or whatever is appropriate for the country.
+
+     <field-list: replace>
+       <do part="shipping">
+         <field-list fields="address,city,region,country,postal_code">
+           <country-view:><hot-input ajax /><country-view:>
+           <region-label:><%= this_parent.country._?.region_label %><region-label:>
+         <field-list>
+       </do>
+     <field-list:>
+
+The actual input is exposed as the default parameter, so it can be customized:
+
+     <hot-input ajax selector="select">
+       <combobox>
+         <select-one limit="5000"/>
+       </combobox>
+     </hot-input>
+
+Note also the selector option, which is useful for complex, combined inputs like a combobox.   A single change in a complex input may actually result in change events being fired on multiple fundamental HTML elements, so we use the selector to only watch a single input.
+
+The hot-input must be inside a form, and the form's context must be the same as the page's context.   You can work around this limitation by using custom controller code.
+
+### Attributes
+
+This tag supports the [standard form AJAX attributes](/api_taglibs/rapid_forms), such as update, message, spinner-next-to, etc.
+
+In particular, the part to update *must* be specified using either the `ajax`, `update` or `updates` attribute.
+
+* path: the path to send the AJAX request to.   If not specified, the current page path is used.
+* method: the HTTP method for the request.   Defaults to 'GET'.
+* events: the javascript event(s) to trigger on.  Default is 'change'.
+* selector: filter for the events.  Default is null.
+
+Note that `event` and `selector` are passed straight to `$.on()`  See [its documentation](http://api.jquery.com/on/) for more details.
+
+-->
+<def tag="hot-input" attrs="path, method, events, selector" >
+<%
+  attributes['message'] ||= 'Loading...'
+  ajax_attrs, html_attrs = attributes.partition_hash(HoboRapidHelper::AJAX_ATTRS)
+  add_data_rapid!(html_attrs, "hot-input", :ajax_attrs => ajax_attrs, :path => path || request.path, :method => method || 'GET', :events => events || 'change', :selector => selector)
+%>
+  <span class="hot-input" param="default" merge-attrs="&html_attrs">
+    <input merge param />
+  </span>
+</def>

data/taglibs/inputs/input.dryml

@@ -0,0 +1,76 @@
+<!--
+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>
+
+    <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, deunderscore_attributes(attributes), nil, true, true
+  else
+    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
+                        input_many(attrs)
+                      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 Hobo::Error, ("No input tag for #{this_field}:#{this_type} (this=#{this.inspect})")
+                  end
+      unless this_parent.errors[this_field].empty?
+        "<span class='field-with-errors'>#{the_input}</span>".html_safe
+      else
+        the_input
+      end
+    end
+  end
+%></def>

data/taglibs/inputs/input_all.dryml

@@ -0,0 +1,14 @@
+<!-- Renders a sub-section of a form with fields for every record in a `has_many` association. This is similar to `<input-many>` except there is no ability to add and remove items (i.e. no (+) and (-) buttons).
+  -->
+<def tag="input-all">
+  <% association_fkey = this_field_reflection.foreign_key -%>
+  <ul class="input-all #{this_field.dasherize}">
+    <li repeat class="#{'record-with-errors' unless this.errors.empty?}">
+      <set-scoped form-field-names="&[]">
+        <hidden-id-field/>
+        <do param="default"/>
+        <hidden-fields skip="&association_fkey"/>
+      </set-scoped>
+    </li>
+  </ul>
+</def>

data/taglibs/inputs/input_for.dryml

@@ -0,0 +1,38 @@
+<!-- A `<textarea>` input -->
+<def tag="input" for="text" attrs="name">
+  <%= text_area_tag(name, this, deunderscore_attributes(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">
+  <%= unless attributes[:disabled]
+        cb_tag = check_box_tag(name, '1', this, deunderscore_attributes(attributes))
+        cb_hidden_tag = hidden_field_tag(name, '0', :id => nil)
+        cb_hidden_tag + cb_tag
+      end %>
+</def>
+
+<!-- A password input - `<input type='password'>` -->
+<def tag="input" for="password" attrs="name">
+  <%= password_field_tag(name, this, deunderscore_attributes(attributes)) %>
+</def>
+
+<!-- An `<input type='text'>` input. -->
+<def tag="input" for="integer" attrs="name">
+  <%= text_field_tag(name, this, deunderscore_attributes(attributes)) %>
+</def>
+
+<!-- An `<input type='text'>` input. -->
+<def tag="input" for="BigDecimal" attrs="name">
+  <%= text_field_tag(name, this, deunderscore_attributes(attributes)) %>
+</def>
+
+<!-- An `<input type='text'>` input. -->
+<def tag="input" for="float" attrs="name">
+  <%= text_field_tag(name, this, deunderscore_attributes(attributes)) %>
+</def>
+
+<!-- An `<input type='text'>` input. -->
+<def tag="input" for="string" attrs="name">
+  <%= text_field_tag(name, this, deunderscore_attributes(attributes)) %>
+</def>

data/taglibs/inputs/input_for_date.dryml

@@ -0,0 +1,86 @@
+<!-- A date picker, using the `select_date` helper from Rails
+
+### Attributes
+
+ - all the options of select_date and date_select are passed to the select_date Rails
+ helper
+
+All the other attributes are passed to the `select_date` helper as the html-options hash.
+
+The menus default to the current date if the current value is nil.
+
+Examples:
+
+   - override the input for date tag in a form
+
+     <my-special-date-view:>
+        <select-date start-year="&1940" order="day,month,year" />
+     </my-special-date-view:>
+
+   - override the input tag application-wide
+
+     <def tag='input' for='date'>
+       <select-date merge order="day,month,year" start-year="&1940" />
+     </def>
+
+  -->
+<def tag="select-date" attrs="use-month-numbers, use-short-month, add-month-numbers, use-month-names, date-separator, start-year, end-year, discard-day, discard-month, discard-year, order, include-blank, default, disabled, prompt, prefix">
+  <% order = order.nil? ? [:year, :month, :day] : comma_split(order).*.to_sym -%>
+  <%= select_date(this || current_time,
+                  (all_attributes - attributes.keys).reverse_merge(:prefix => param_name_for_this).merge(:order => order),
+                  attributes - [:name]) %>
+</def>
+
+
+<%# Selects the `<datepicker>` as the default input for date.   To
+  choose the older `<select-date>` input, add this to your
+  application.dryml:
+
+     <def tag='input' for='date'>
+       <select-date merge/>
+     </def>
+%>
+<def tag="input" for="Date">
+  <datepicker merge/>
+</def>
+
+<!-- A date/time picker, using the `select_time` helper from Rails
+
+### Attributes
+
+ - include-seconds, time-separator, prompt and prefix are passed to the select_time helper as options
+
+All the other attributes are passed to the `select_time` helper as the html-options hash.
+
+The menus default to the current time if the current value is nil.
+
+  -->
+<def tag="input" for="time" attrs="include-seconds, time-separator, prompt, prefix">
+  <%= select_time( this || current_time,
+                   (all_attributes - attributes.keys).reverse_merge(:prefix => param_name_for_this),
+                   attributes - [:name] ) %>
+</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"
+ - date-separator, discard-type, prompt and prefix are passed to the select_date helper as options
+
+All the other attributes are passed to the `select_date` helper as the html-options hash.
+
+The menus default to the current time if the current value is nil.
+
+  -->
+<def tag="input" for="datetime" attrs="order, date-separator, discard-type, prompt, prefix">
+  <% if ! order.nil?
+       order = comma_split(order).*.to_sym
+       attributes.merge!(:order => order)
+     end -%>
+  <%= select_datetime(this || current_time,
+                     (all_attributes - attributes.keys).reverse_merge(:prefix => param_name_for_this).merge(:order => order),
+                      attributes - [:name] ) %>
+</def>

data/taglibs/inputs/input_for_enum_string.dryml

@@ -0,0 +1,26 @@
+<!-- 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
+ - `first-option` - a string to be used for an extra option in the first position. E.g. "Please choose..."
+ - `first-value` - the value to be used with the `first-option`. Typically not used, meaning the option has a blank value.
+
+   -->
+<def tag="input" for="HoboFields::Types::EnumString" attrs="labels, titleize, first-option, first-value"><%
+  labels ||= {}
+  labels = HashWithIndifferentAccess.new(labels)
+  titleize = true if titleize.nil?
+  options = this_type.values.map {|v| 
+    [I18n.t("activerecord.attributes.#{this_parent.class.to_s.downcase}/#{this_field}s.#{v}",
+      :default => titleize ? v.titleize : v), 
+    v]
+  }
+  %>
+  <select name="#{param_name_for_this}" merge-attrs>
+    <option value="#{first_value}" unless="&first_option.nil?"><first-option/></option>
+    <%= options_for_select(options, this) %>
+  </select>
+</def>

data/taglibs/inputs/input_many.dryml

@@ -0,0 +1,131 @@
+<!-- Creates a sub-section of the form which the user can repeat using (+) and (-) buttons, in order to allow an entire `has_many` collection to be created/edited in a single form.
+
+This tag is very different from tags like `<select-many>` and `<check-many>` in that:
+
+ - Those tags are used to *choose existing records* to include in the association, while `<input-many>` is used to actually create or edit the records in the association.
+
+### Example
+
+Say you are creating a new `Category` in your online shop, and you want to create some initial products *in the same form*, you can add the following to your form:
+
+    <input-many:products fields="name, price"/>
+
+which is the same as
+
+    <input-many:products><field-list fields="name, price"/></input-many>
+
+The body of the tag will be repeated for each of the current records in the collection, or will just appear once (with blank fields) if the colleciton is empty.
+
+### Attributes
+
+ - fields:  If you do not specify any content for the input-many, a `<field-list>` is rendered.   This attribute is passed through to the `<field-list>`
+
+ - skip:  Passed through to the `<field-list>`.  If not specified, it defaults to the parent association.
+
+ - `minimum`: the minimum number of items in the collection.  Currently only '0' and '1' are supported values.  The default is '0'.
+
+ - `template`: the default values for new items.  Normally this functionality is better provided by Model.new, but it's here if you need it.
+
+ - `add-hook`, `remove-hook`: javascript hooks which work similarly to the events described below.
+
+### Events
+
+ - `rapid:add`: fired after the element is inserted
+
+ - `rapid:remove`: fired before the element is inserted.  Returning false will cancel the removal.
+
+ - `rapid:change`: fired after an element has been removed or inserted.
+
+ - `hide`, `show`: passed to jquery-ui's hide and show functions.
+
+Example javascript:
+
+      var last_added;
+      var last_removed;
+      $(document).ready(function() {
+        $('.stories').on('rapid:add', function(ev) {
+          last_added = this;
+        });
+        $('.stories').on('rapid:remove', function(ev) {
+          last_removed = this;
+          if(!confirm("really?")) return false;
+        });
+      });
+
+### Example
+
+Say you are creating a new `Category` in your online shop, and you want to create some initial products *in the same form*, you can add the following to your form:
+
+    <input-many:products fields="name, price" />
+
+You'll often want to provide the `item` parameter:
+
+    <input-many:products><item:><field-list fields="name, price" /></item:></input-many>
+
+A fully worked up example of nested input-many's may be found in [agility/jquery-test](http://github.com/tablatom/agility/blob/jquery-test/app/views/projects/nested_has_many_test.dryml)
+  -->
+<def tag="input-many" attrs="minimum, fields, skip, more-skip, template, add-hook, remove-hook, hide, show" polymorphic >
+<%
+# helper function to create id's on buttons to facilitate testing
+def underize(s)
+  s.gsub(/\[/,"_").gsub(/\]/,"")
+end
+%>
+  <set empty="&this.empty?"/>
+  <% template ||= this.try.new_candidate || this.member_class.new -%>
+  <% minimum ||= 0 ; minimum = minimum.to_i -%>
+  <% skip ||= this.proxy_reflection.klass.reflect_on_all_associations.detect {|p| p.primary_key_name==this.proxy_reflection.primary_key_name}.try.name.to_s if this.respond_to? :proxy_reflection -%>
+  <% skip += ",#{more_skip}" if more_skip -%>
+  <% js_attrs = all_attributes.slice(:minimum, :add_hook, :remove_hook, :hide, :show) %>
+  <% js_attrs[:prefix] = param_name_for_this %>
+  <ul class="input-many #{this_field.dasherize}" data-rapid="#{data_rapid('input-many', js_attrs)}" merge-attrs>
+    <fake-field-context fake-field="-1" context="&template">
+      <li class="input-many-li input-many-template" id="#{underize param_name_for_this}">
+        <div class="input-many-item" param="default">
+          <field-list param merge-attrs="fields" skip="&skip" />
+        </div>
+        <div class="buttons">
+          <button param="remove-item" id="#{underize param_name_for_this}_remove">-</button>
+          <button param="add-item" id="#{underize param_name_for_this}_add">+</button>
+        </div>
+      </li>
+    </fake-field-context>
+    <li class="input-many-li empty #{'hidden' unless this.empty? and minimum==0}" id="#{underize param_name_for_this}_-1_empty">
+      <!-- HACK way to signal an empty collection to the controller -->
+      <input type="hidden" class="empty-input" id="#{underize param_name_for_this}" name="#{param_name_for_this}" value="" disabled="&(!this.empty? || minimum>0)" />
+      <fake-field-context fake-field="-1" context="&template">
+        <div param="empty-message">
+          <ht key="#{this.class.to_s.underscore}.collection.empty_message">
+            No <%= this.class.name.titleize.downcase.pluralize %>.
+          </ht>
+        </div>
+        <div class="buttons">
+          <button param="remove-item" class="hidden" id="#{underize param_name_for_this}_remove">-</button>
+          <button param="add-item" id="#{underize param_name_for_this}_add">+</button>
+        </div>
+      </fake-field-context>
+    </li>
+    <fake-field-context fake-field="0" context="&template">
+      <li class="input-many-li" if="&(this_parent.empty? && minimum>0)" id="#{underize param_name_for_this}">
+        <div class="input-many-item" param="default">
+          <field-list param merge-attrs="fields" skip="&skip" />
+        </div>
+        <div class="buttons">
+          <button param="remove-item" class="hidden" id="#{underize param_name_for_this}_remove">-</button>
+          <button param="add-item" id="#{underize param_name_for_this}_add">+</button>
+        </div>
+      </li>
+    </fake-field-context>
+    <li repeat class="input-many-li #{'record-with-errors' unless this.errors.empty?}" id="#{underize param_name_for_this}">
+      <error-messages without-heading class="sub-record"/>
+      <hidden-id-field/>
+      <div class="input-many-item" param="default">
+        <field-list param merge-attrs="fields" skip="&skip" />
+      </div>
+      <div class="buttons">
+        <button param="remove-item" class="#{'hidden' if this_parent.length<=minimum}" id="#{underize param_name_for_this}_remove">-</button>
+        <button param="add-item" class="#{'hidden' if not last_item?}" id="#{underize param_name_for_this}_add">+</button>
+      </div>
+    </li>
+  </ul>
+</def>

data/taglibs/inputs/inputs.dryml

@@ -0,0 +1 @@
+<%# Simple or complicated input widgets for use inside forms %>

data/taglibs/inputs/name_one.dryml

@@ -0,0 +1,74 @@
+<!-- An `<input type="text">` with auto-completion. Allows the user to chose the target of a `belongs_to` association by name.
+
+This tag relies on an autocompleter being defined in a controller.  A simple example:
+
+    <form with="&ProjectMembership.new">
+      <name-one:user>
+    </form>
+
+    class ProjectMembership < ActiveRecord::Base
+      hobo_model
+      belongs_to :user
+    end
+
+    class User < ActiveRecord::Base
+      hobo_user_model
+      has_many :project_memberships, :accessible => true, :dependent => :destroy
+    end
+
+    class UsersController < ApplicationController
+      autocomplete
+    end
+
+The route used by the autocompleter looks something like `/users/complete_name`.  The first part of this route is specified by the `complete-target` attribute, and the second part is specified by the `completer` attribute.
+
+`complete-target` specifies the controller for the route.  It can be specified by either supplying a model class or a model.  If a model is supplied, the id of the model is passed as a parameter to the controller.  (`?id=7`, for example)  The default for this attribute is the class of the context.   In other words, the class that contains the `has_many / has_one`, not the class with the `belongs_to`.
+
+`completer` specifies the action for the route.   `name-one` prepends `complete_` to the value given here.  This should be exactly the same as the first parameter to `autocomplete` in your controller.   As an example:  `autocomplete :email_address` would correspond to `completer="email_address"`.  The default for this attribute is the name field for the model being searched, which is usually `name`, but not always.
+
+The query string is passed to the controller in the `query` parameter.  (`?query=hello` for example).
+
+For more information on how to customize the controller, see the [controller manual](http://cookbook.hobocentral.net/manual/controllers#autocompleters)
+
+Here's a more complex example.  This used to be a part of [agility](http://cookbook.hobocentral.net/tutorials/agility) until it was simplified.
+
+    class ProjectsController < ApplicationController
+      autocomplete :new_member_name do
+        project = find_instance
+        hobo_completions :name, User.without_project(project).is_not(project.owner)
+      end
+    end
+
+Note that this was added to the projects controller, rather than the users controller as in the first example.  You can read this as: create an auto-complete action called `new_member_name` that finds users that are not already members of the project, and not the owner of the project, and completes the :name field.
+
+    <name-one:user complete-target="&@project" completer="new_member_name"/>
+
+We're using an object as the complete-target rather than a class.   This allows the `find_instance` in our controller action to function.
+
+There's another example of `<name-one>` use in the [recipes](http://cookbook.hobocentral.net/recipes/36-using-a-name-one-one-a).
+
+### Attributes:
+
+- `complete-target`, `completer`: see above
+- `min-chars`: The minimum number of characters that must be entered in the input field before an Ajax request is made.
+- `nil-value`: If there is no current value, this text will appear greyed out inside the control, and will disappear on focus.
+
+### Note:
+
+If you wish to set `min-chars` to 0, you will require this [patch to controls.js](http://github.com/bryanlarsen/scriptaculous/commit/3915b7b).   'controls.js' was added to your project via the rails generator, not via Hobo.
+
+  -->
+<def tag="name-one" attrs="complete-target, completer, min-chars, nil-value"><%
+  complete_target ||= this_field_reflection.klass
+  completer ||= (complete_target.is_a?(Class) ? complete_target : complete_target.class).name_attribute
+  min_chars ||= 1
+  value = name(:no_wrapper => true, :if_present => true)
+  -%>
+  <wrap tag="span" class="field-with-errors" when="&!this_parent.nil? && !this_parent.errors[this_field].empty?">
+    <input type="text" name="#{param_name_for_this}"
+           class="autocompleter #{type_and_field._?.dasherize} #{css_data :complete_on, typed_id(complete_target), completer} #{css_data :min_chars, min_chars} #{'nil-value' if value==''}"
+           value="#{value=='' ? nil_value : value}"
+           merge-attrs/>
+    <div class="completions-popup" style="display:none"></div>
+  </wrap>
+</def>