hobo-jquery 1.3.0pre2

data/public/stylesheets/hobo-jquery.css

@@ -0,0 +1,16 @@
+
+// stolen from clean.css
+
+ul.hjq-input-many {list-style-type: none;}
+
+ul.hjq-input-many > li { overflow:hidden; zoom:1;}
+ul.hjq-input-many .item {float:left;}
+ul.hjq-input-many div.buttons {float:left; margin-left:10px;}
+
+li.input-many-template { display:none; }
+
+.hjq-combobox .ui-button { margin-left: -1px; }
+.hjq-combobox .ui-button-icon-only .ui-button-text { padding: 0; }
+.hjq-combobox button.ui-button-icon-only { width: 20px; }
+.hjq-combobox .ui-autocomplete-input { margin-right: 0; }
+.hjq-combobox {white-space: nowrap;}

data/taglibs/hobo-jquery.dryml

@@ -0,0 +1,613 @@
+<!--
+
+This is the jQuery plugin for Hobo.  This plugin provides the jQuery UI widgets in a Hobo friendly manner, provides useful tags and functions for jQuery javascript coding, and provides additional composite tags.
+
+To use, see the [installation instructions](http://cookbook.hobocentral.net/plugins/hobo-jquery)  [(alternate link)](README.html)
+
+The jQuery UI tags support all of the [options that the corresponding jQuery UI widgets provide](http://docs.jquery.com/UI).  For example:
+
+    <hjq-datepicker dateFormat="yy-mm-dd" />
+
+Options that expect a type other than string can be provided by passing a ruby object:
+
+    <hjq-datepicker dayNamesMin="&['Di', 'Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa']" />
+
+Events are also supported.  Pass in a global Javascript function name:
+
+    <hjq-datepicker onSelect="hjq.util.log" />
+
+-->
+
+<!--
+This is Hobo jQuery's standard tag annotation method.   This annotation is automatically added to Hobo jQuery tags, but you may wish to use it in your own tag definitions.
+
+The current implementation uses HTML comments for annotation.  This may change in the future, if somebody can suggest a better mechanism.  [Here is a good discussion of the alternatives.](http://www.1729.com/blog/HtmlAnnotations.html).  Two more possibilities are http://www.w3.org/TR/xhtml-rdfa-primer and http://ejohn.org/blog/html-5-data-attributes/.
+
+To use it, invoke this tag directly before the tag to annotate.  To get the annotations, call hjq.getAnnotations with _this_ set to the element that has been annotated.  For example:
+
+    <def tag="mytag">
+      <annotate-tag option_a="42"/>
+      <div class="hjq-annotated">
+        ...
+      </div>
+    </def>
+
+    jQuery(this).find('.hjq-annotated').each(function() {
+      var annotations = hjq.getAnnotations.call(this);
+      ...
+    });
+-->
+<def tag="annotate-tag">
+  <%= "<!-- json_annotation (#{attributes.to_json}); -->".html_safe %>
+</def>
+
+<!--
+These are the Hobo jQuery and jQuery assets required by Hobo jQuery.  You will probably wish to add this to your page definition:
+
+    <extend tag="page">
+      <old-page merge>
+        <custom-scripts:>
+          <hjq-assets/>
+        </custom-scripts>
+      </old-page>
+    </extend>
+-->
+<def tag="hjq-assets">
+  <jquery-assets/>
+  <hobo-jquery-assets/>
+</def>
+
+<def tag="jquery-assets">
+  <stylesheet name='smoothness/jquery-ui-1.8.11.custom.css' />
+  <javascript name="jquery-1.5.2.min.js" />
+  <javascript name="jquery-ui-1.8.11.custom.min.js" />
+</def>
+
+<def tag="hobo-jquery-assets">
+  <stylesheet name='hobo-jquery.css' />
+  <javascript name="hobo-jquery.js" />
+  <javascript name="event.simulate.js" />
+  <script type="text/javascript">
+    jQuery.noConflict();
+    jQuery(document).ready(function() {
+      hjq.initialize.call(document);
+    });
+  </script>
+</def>
+
+
+<!--
+This is the [jQuery-UI datepicker](http://docs.jquery.com/UI/Datepicker).  All options and events are supported.
+
+It's probably easiest to add this to your application.dryml:
+
+    <def tag="input" for="Date">
+      <hjq-datepicker dateFormat="yy-mm-dd" merge />
+    </def>
+
+It's probably useful to set global options such as dateFormat in application.dryml and set local options such as yearRange in the tag invocation:
+
+    <input:birthdate yearRange="1900:#{Date.today.year}" />
+
+-->
+<def attrs="name" tag="hjq-datepicker">
+<%
+  options, attrs = attributes.partition_hash(['altField', 'altFormat', 'appendText', 'buttonImage', 'buttonImageOnly', 'buttonText', 'changeMonth', 'changeYear', 'closeText', 'constrainInput', 'currentText', 'dateFormat', 'dayNames', 'dayNamesMin', 'dayNamesShort', 'defaultDate', 'duration', 'firstDay', 'gotoCurrent', 'hideIfNoPrevNext', 'isRTL', 'maxDate', 'minDate', 'monthNames', 'monthNamesShort', 'navigationAsDateFormat', 'nextText', 'numberOfMonths', 'prevText', 'selectOtherMonths','shortYearCutoff', 'showAnim', 'showButtonPanel', 'showCurrentAtPos', 'showMonthAfterYear', 'showOn', 'showOptions', 'showOtherMonths', 'stepMonths', 'yearRange'])
+  events, html_attrs = attrs.partition_hash(['beforeShow', 'beforeShowDay', 'onChangeMonthYear', 'onClose', 'onSelect'])
+%>
+ <annotate-tag tag="hjq-datepicker" init="hjq.datepicker.init" options="&options" events="&events" />
+ <% html_attrs = add_classes(html_attrs, "hjq-annotated"); %>
+ <%= text_field_tag(name, this, html_attrs) %>
+</def>
+
+
+<!--
+This is the [jQuery-UI autocompleter](http://jqueryui.com/demos/autocomplete/).  All options and events provided by the jQuery autocompleter are supported in this Hobo tag.   Refer to the jquery autocomplete documentation for more details.
+
+This tag works very similarly to the `name-one` tag used in Hobo.  The main reason I use `hjq-autocomplete` is that the scriptaculous widget used by Hobo for `name-one` does not work well in Internet Explorer:  https://prototype.lighthouseapp.com/projects/8887/tickets/33
+
+If you do not provide a `source` option, this tag will essentially provide a default similar to this:
+
+    <hjq-autocomplete:project source="&Project.find(:all, :limit => 5000).map {|p| p.name}" />
+
+This will provide a local autocomplete, putting all possible options into your HTML.  This is useful when you have too many options to make a `select-one` infeasible, but will overload your server and crash your browser if you have millions of options.
+
+To do a server side autocomplete, use a path for your source option:
+
+    <hjq-autocomplete:project source="&query_projects_path" delay="500" minLength="3" />
+
+And add something like this to your controller:
+
+    index_action :query do
+      render :json => Project.name_contains(params[:term]).limit(100).*.name
+    end
+-->
+<def tag="hjq-autocomplete">
+<%
+  options, attrs = attributes.partition_hash(['disabled', 'appendTo', 'autoFocus', 'delay', 'minLength', 'position', 'source'])
+  events, html_attrs = attrs.partition_hash(['create', 'search', 'open', 'focus', 'select', 'close', 'change'])
+  options["source"] ||= begin
+                          complete_target = this_field_reflection.klass
+                          complete_target.find(:all, :limit => 5000).*.send(complete_target.name_attribute)
+                        end
+
+%>
+ <annotate-tag tag="hjq-autocomplete" init="hjq.autocomplete.init" options="&options" events="&events" />
+ <% html_attrs = add_classes(html_attrs, "hjq-annotated") 
+    html_attrs["name"] ||= param_name_for_this
+    html_attrs["value"] ||= name(:no_wrapper => true, :if_present => true)
+ %>
+ <%= text_field_tag(name, this, html_attrs) %>
+
+</def>
+
+
+<!-- Creates an enhanced version of the [jQuery-UI demo combobox](http://jqueryui.com/demos/autocomplete/#combobox).  This will turn any select (even a select-many) into a combobox.
+
+NOTE:  backwards compatibility with the Hobo&Rails prototype/lowpro handlers requires event.simulate.js.   You may need to rerun your hobo_query:install generator to copy this file into your application.
+
+Standard usage:
+
+    <hjq-combobox>
+      <select .../>
+    </hjq-combobox>
+
+If you don't supply the select, it will use Hobo's `<input>` tag.  This is usually the right default.
+
+You can tell Hobo to always use a combobox for select-one, select-many, select-input and/or select-menu.   Notice that we also changed the limit - 100 is the default, which makes sense for a select, but not for a combobox.
+
+    <extend tag="select-one">
+      <hjq-combobox tag="select-one">
+        <old-select-one limit="5000" merge/>
+      </hjq-combobox>
+    </extend>
+
+To make the behavior more like the demo's, turn off autoFill and clearButton:
+
+    <hjq-combobox autoFill="&false" clearButton="&false"/>
+
+Combobox is a new control that is built on autocomplete.   The autocomplete options may not be used directly.   If you need any of them let me know, they should not be too hard to add if you volunteer to test them.
+
+### Attributes
+
+- `autoFill` (default: true):  select first value rather than clearing if there's a match
+
+- `clearButton` (default: true): add a "clear" button
+
+- `adjustWidth` (default: true): if true, will set the autocomplete width the same as the old select.  (requires jQuery 1.4.4 to work on IE8)
+
+- uiStyle (default: false): if true, will add classes so that the autocomplete input takes a jQuery-UI style.  If false, the standard Hobo style is used.
+
+### Events
+
+- `selected` (default: `$(this).simulate('change');`):  this is a jQuery-UI event handler.  The default value for this option fires the `onchange` handler on the underlying `select` in a manner compatible with both prototype.js and jQuery.  For this to work, event.simulate.js must be loaded, and jQuery must be put into noConflict mode.  hobo-jquery should be doing both of these for you if you are using it as recommended in the README.
+
+-->
+
+<def tag="hjq-combobox" options="tag">
+<%
+  options, attrs = attributes.partition_hash(['autoFill', 'clearButton', 'adjustWidth', 'uiStyle'])
+  events, html_attrs = attrs.partition_hash(['selected'])
+%>
+  <annotate-tag tag="hjq-combobox" init="hjq.combobox.init" options="&options" events="&events"/>
+  <% tag ||= 'input' %>
+  <span class="hjq-combobox hjq-annotated" param="default">
+    <input merge param />
+  </span>
+</def>
+
+
+<!-- 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.
+
+Most of the enhancements from hjq-input-many have been folded back into hjq-input-many, but there are a few remaining differences:
+
+ - it supports delayed initialization, required for some Javascript elements like the jQuery UI datepicker
+ - the name of the main parameter is `item` rather than `default`
+ - hjq-input-many allows you to provide javascript callbacks.  input-many fires
+    rapid:add, rapid:change and rapid:remove events that can be hooked.
+ 
+### 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:
+
+    <hjq-input-many:products fields="name, price" />
+    
+You'll often want to provide the `item` parameter:
+
+    <hjq-input-many:products><item:><field-list fields="name, price" /></item:></hjq-input-many>
+
+A fully worked up example of nested hjq-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)
+
+### Attributes
+
+ - `minimum`: the minimum number of items in the collection.  Currently only '0' and '1' are supported values.  The default is '0'.
+
+ - `fields`: passed down to the `field-list` tag in the default `item`.
+
+ - `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`: a javascript function to call after an item has been added.  The context will be set to the new item.
+
+ - `remove-hook`: a javascript function to call before an item is removed.  The context will be set to the item.  If the hook returns false, the remove is cancelled.
+
+
+  -->
+<def tag="hjq-input-many" attrs="minimum, fields, template, add-hook, remove-hook" polymorphic >
+<%
+# helper function to create id's on buttons to facilitate testing
+def underize(s)
+  s.gsub(/\[/,"_").gsub(/\]/,"")
+end
+%>
+  <set empty="&this.empty?"/>
+  <annotate-tag tag="hjq-input-many" init="hjq.input_many.init" merge-attrs="minimum, add-hook, remove-hook" />
+  <ul class="hjq-input-many #{this_field.dasherize} #{css_data :input_many_prefix, param_name_for_this} hjq-annotated" merge-attrs="&attributes - attrs_for(:hjq_input_many_item)">
+    <% template ||= this.try.new_candidate || this.member_class.new %>
+    <% minimum ||= 0 ; minimum = minimum.to_i %>
+    <fake-field-context fake-field="-1" context="&template">
+      <li class="input-many-template" id="#{param_name_for_this}">
+        <hjq-input-many-item param="item" merge-attrs="fields" />
+        <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="empty #{'hidden' unless this.empty? and minimum==0}" id="#{param_name_for_this}[-1]_empty">
+      <!-- HACK way to signal an empty collection to the controller -->
+      <input type="hidden" class="empty-input" id="#{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 if="&(this_parent.empty? && minimum>0)" id="#{param_name_for_this}">
+        <hjq-input-many-item param="item" merge-attrs="fields" />
+        <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="#{'record-with-errors' unless this.errors.empty?}" id="#{param_name_for_this}">
+      <error-messages without-heading class="sub-record"/>
+      <hidden-id-field/>
+      <hjq-input-many-item param="item" merge-attrs="fields" />
+      <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>
+
+<!--
+    This is the default item used by `<hjq-input-many>`.  Redefine or extend if desired.
+-->
+<def tag="hjq-input-many-item" attrs="fields">
+  <card param="default">
+    <header: replace />
+    <body:><field-list merge-attrs="fields" /></body:>
+  </card>
+</def>
+
+<!--
+`<formlet>` works like an AJAX `<form>` without actually being an AJAX `<form>`.  This is useful in scenarios where forms aren't allowed or are problematic, like inside of another form.
+
+### Attributes
+
+ - standard Hobo HTML attributes (id, part, et cetera).  All supported.
+
+ - standard Hobo AJAX attributes:  (see [the cookbook](http://cookbook.hobocentral.net/api_taglibs/rapid_forms) )
+   
+   - `update`: (optional).  The DOM ID's of parts to update.  Note that you get an AJAX formlet whether this is provided or not.
+
+   - `message`: the spinner message
+
+   - `spinner-next-to`: DOM id of an element to position the ajax progress spinner next to.
+
+   - `before`, `success`, `error`, `complete`: These callbacks are slightly different from the standard form callbacks.  They are called with "this" set to the formlet.  Also, you may pass in a function name rather than a javascript fragment.  If the before callback returns false, it will cancel the submission.
+
+   - `confirm`: a message to be displayed in a JavaScript confirm dialog. By default there is no confirm dialog
+
+   - not supported: `type, script, params, reset-form, refocus-form, result-update`.  None of these are particularly hard to support.  Email or post a message to the list if you need them.
+
+ - standard Hobo Form attributes (all supported):
+
+   - `hidden-fields`
+
+   - `action`
+
+   - `method`
+
+   - `web-method`
+
+   - `lifecycle`
+
+   - `owner`
+-->
+<def tag="formlet" polymorphic attrs="update, hidden-fields, action, method, web-method, lifecycle, owner">
+<%
+#FIXME: code very similar to <form>.  refactor out common code.
+
+  ajax_attrs, html_attrs = attributes.partition_hash(Hobo::Rapid::Helper::AJAX_ATTRS)
+
+  ajax_options = {}
+
+  new_record = this.try.new_record?
+
+  method = if method.nil?
+             (action || web_method || new_record) ? "post" : "put"
+           else
+             method.downcase
+           end
+
+  ajax_options[:url] = action || begin
+     target = if owner
+                collection_name = this.class.reverse_reflection(owner).name
+                this.send(owner).send(collection_name)
+              else
+                this
+              end
+     action = web_method || lifecycle
+     object_url(target, action, :method => "post")
+  end
+
+  if action.nil? && (ajax_options[:url].nil? ||
+                     (lifecycle.nil? && new_record && !this.creatable_by?(current_user)) ||
+                     (lifecycle.nil? && !new_record && !can_edit?))
+    Dryml.last_if = false
+    logger.info("blank!!!")
+    ""
+  else
+    if method == "put"
+      # browsers don't support put -- use post and add the Rails _method hack
+      http_method_hidden = hidden_field_tag("_method", "PUT") 
+      ajax_options[:type] = "post"
+    else
+      ajax_options[:type] = method
+    end
+
+    ajax_attrs[:update] = if update 
+                            update.split(/,\s*/) 
+                          else
+                            []
+                          end
+
+    hiddens = nil
+    body = with_form_context do
+      # It is important to evaluate parameters.default first, in order to populate scope.form_field_names
+      b = parameters.default
+      hiddens = self.hidden_fields(:fields => hidden_fields) if new_record
+      b
+    end
+
+    auth_token = if method.nil? || method == 'get' || !protect_against_forgery?
+                   ''
+                 else
+                   element(:input, {:type => "hidden", 
+                           :name => request_forgery_protection_token.to_s,
+                           :value => form_authenticity_token}, nil, true, true)
+                 end
+     
+    unless method == "get"
+      page_path = if (request.post? || request.put?) && params[:page_path]
+                    params[:page_path]
+                  else
+                    request.fullpath
+                  end
+      page_path_hidden = hidden_field_tag("page_path", page_path) 
+    end
+
+    hiddens_div = element(:div, {:class => "hidden-fields"}, [http_method_hidden, page_path_hidden, auth_token, hiddens].safe_join)
+
+    body = [hiddens_div, body].safe_join
+
+    if action.nil? # don't add automatic css classes if the action was specified
+      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}")
+      end
+    end
+
+    Dryml.last_if = true
+  end
+
+  add_classes!(html_attrs, "formlet")
+%>
+<annotate-tag tag="formlet" ajax-attrs="&ajax_attrs" ajax-options="&ajax_options" />
+  <%= element("div", html_attrs, body) %>
+</def>
+
+<!--
+Submit button for use with `<formlet>`.  Submit won't work, because `<formlet>` isn't a form.
+-->
+<def tag="formlet-submit" attrs="label, image, method">
+  <% label ||= 'submit' %>
+  <if test='&image'>
+    <input class='image-button formlet-submit-button' type='image' src='&image' onClick='hjq.formlet.submit.call(this)' merge-attrs />
+  </if>
+  <else>
+    <input class='button formlet-submit-button' type='button' value='#{label}' onClick='hjq.formlet.submit.call(this)' merge-attrs />
+  </else>
+</def>
+
+<!--
+Submit button for use with the `<form>`.  This uses hjq.form.submit to
+submit the form via jquery form plugin ajax, rather than using the
+standard HTTP or Hobo form submission mechanisms.  The main advantage
+this has is that the jquery form plugin supports ajax submission of
+attachments.
+
+You must have the jquery form plugin installed.  It is not installed
+automatically by hobo-jquery.
+
+FIXME: this function HARD CODES it's ajax options, in particular
+update="attachments-div".  It does not (yet) get the parameters from
+the form, nor does it get them through the standard hobo-jquery
+mechanism.   update in hobo-jquery.js.
+-->
+<def tag="hjq-submit" attrs="label, image, method">
+  <% label ||= 'submit' %>
+  <if test='&image'>
+    <input class='image-button hjq-form-submit-button' type='image' src='&image' onClick='hjq.form.submit.call(this)' merge-attrs />
+  </if>
+  <else>
+    <input class='button hjq-form-submit-button' type='button' value='#{label}' onClick='hjq.form.submit.call(this)' merge-attrs />
+  </else>
+</def>
+
+<!--
+The JQuery UI [dialog](http://jqueryui.com/demos/dialog/).  All options and methods are supported.
+
+The default for [autoOpen](http://jqueryui.com/demos/dialog/#option-autoOpen) has been changed to `"&false"`.  To display the dialog set autoOpen to `"&true"`, use a `<hjq-dialog-open-button>`, use the [jQuery dialog open method](http://jqueryui.com/demos/dialog/#method-open), or use an `<hjq-dialog-and-button>` instead.
+
+The default for [position](http://jqueryui.com/demos/dialog/#option-position) is also set so that the dialog appears where it is defined.
+
+The [buttons](http://jqueryui.com/demos/dialog/#option-buttons) option has been changed slightly.  Instead of an Hash, it expects a list of pairs.  (Unlike Javascript Objects, Ruby Hash's do not preserve order).  Because of quoting issues, it's usually easier to assign the list to a variable and then include the list:
+
+    <% buttons = [ ["cancel", "jQuery(this).dialog('close')"] ] %>
+    <hjq-dialog buttons="&buttons" />
+
+or
+
+    <hjq-dialog id="story-dialog" buttons='&{"cancel" => "jQuery(this).dialog(\"close\")"}' />
+
+or
+
+    <hjq-dialog id="story-dialog" buttons='&{"cancel" => "hjq.dialog.close"}' />
+
+Because Ruby Hash's do not preserve order, you may use a list of pairs instead of a Hash.
+
+JQuery UI is sometimes picky about types.   For instance, the width option must be a number, not a string.  By default Hobo options are strings, but you can easily send a number by using the ampersand to switch to ruby mode:
+
+    <hjq-dialog width="&640"/>
+
+The following functions are predefined for use in dialog buttons:
+
+ * `hjq.dialog.close`:  close the dialog box
+ * `hjq.dialog.submit_formlet`:  submits all formlets inside the dialog
+ * `hjq.dialog.submit_formlet_and_close`: submits any enclosed formlets, then closes the dialog.
+-->
+<def tag="hjq-dialog" attrs="buttons">
+<% #FIXME: dry these names
+ options, attrs = attributes.partition_hash(["autoOpen", "bgiframe", "closeOnEscape", "dialogClass", "draggable", "height", "hide", "maxHeight", "maxWidth", "minWidth", "modal", "position", "resizable", "show", "stack", "title", "width", "zIndex"])
+ events, html_attrs = attrs.partition_hash(["beforeclose", "open", "focus", "dragStart", "drag", "dragStop", "resizeStart", "resize", "resizeStop", "close"])
+ options["autoOpen"]=false unless options.has_key?("autoOpen")
+%>
+ <span class="hjq-dialog-position"></span>
+ <annotate-tag tag="hjq-dialog" init="hjq.dialog.init" options="&options" events="&events" buttons="&buttons" />
+ <% html_attrs = add_classes(html_attrs, "hjq-annotated hidden hjq-dialog"); %>
+ <div merge-attrs="&html_attrs" param="default" />
+</def>
+
+<!--
+When pressed, will open a `<hjq-dialog>`.
+
+### Attributes
+ * `dialog` (required):a CSS selector (AKA jQuery selector) to locate the dialog in the DOM.  Remember, if you're passing an ID, place a '#' in front of the ID.
+ * supports all `<button>` attributes except for `onclick`
+
+### Example
+    <hjq-dialog id="hello-dialog">Hello!</hjq-dialog>
+    <hjq-dialog-open-button dialog="#hello-dialog">Press Me!</hjq-dialog-open-button>
+-->
+<def tag="hjq-dialog-open-button" attrs="dialog">
+  <button onclick="hjq.dialog_opener.click(this, jQuery('#{dialog}')); return false;" param="default" class="hjq-dialog-open-button" merge />
+</def>
+
+<!--
+Defines an `<hjq-dialog>` and a `<hjq-dialog-open-button>` and links the two together.
+
+### Attributes
+ * `id` (optional): the DOM id to use for the dialog
+-->
+<def tag="hjq-dialog-and-button">
+  <% # we can't use jQuery traversal functions since the dialog will move around in the DOM %>
+  <% attributes["id"]="hjq-dialog-#{(rand*1000000000).to_i}" unless attributes.has_key?("id") %>
+  <hjq-dialog param merge />
+  <hjq-dialog-open-button dialog="##{attributes['id']}" param />
+</def>
+
+<!--
+Defines a `<select-one>` and a button that brings up an `<hjq-dialog>` containing a form allowing you to enter a new item.  After the form is filled in and closed, the `<select-one>` is changed to select the new item.
+
+### Caveats
+
+`select-one-or-new-dialog` is a very simple control that depends on a large number of Hobo and hobo-jquery components to be working correctly in the standard manner.   These include ajax, a standard form context, and formlets.
+
+#### sort order
+
+The javascript for this control is a quick hack that assumes the new item created will be the last item in the select.   If you've defined a sort order, this assumption will be broken.   It will also be broken if there are more items than the select-one limit.
+
+#### parameterizing parts
+
+Because the select-one is a part, it cannot be parameterized.  However, you can adjust its definition by defining the polymorphic input for the type:
+
+    <def tag="input" for="StoryStatus">
+      <select-one include-none="&false" />
+    </def>
+
+#### controller actions
+
+For Hobo ajax to work, standard controller actions are required.   If you have customized the sub-item's create action, you may break select-one-or-new-dialog.
+
+There is one case where you have to customize the create action.   For Ajax to work, Hobo has to resurrect the context.   This is straightforward if the parent context exists in the database.   If it does not, then Hobo uses whatever 'this' is created by the controller action.   In our case, this is usually the wrong thing.
+
+Example:
+
+    class Story
+      hobo_model
+      fields do
+        name :string
+      end
+      belongs_to :story_status
+      # plus permissions, etc...
+    end
+
+app/views/stories/new.dryml:
+
+    <new-page>
+      <field-list:>
+        <story-status-view:>
+          <select-one-or-new-dialog/>
+        </story-status-view:>
+      </field-list:>
+    </new-page>
+
+app/controllers/story_statuses_controller.rb:
+
+    class StoryStatusesController < ApplicationController
+      def create
+        hobo_create do
+          if request.xhr?
+            self.this = Story.new
+          end
+        end
+      end
+    end
+
+
+-->
+<def tag="select-one-or-new-dialog">
+  <% dialog_id="hjq-dialog-#{typed_id.gsub(':', '-')}" %>
+  <% part_id = "select-one-#{typed_id.gsub(':', '-')}" %>
+  <input part="select-one-or-new-dialog-select" id="#{part_id}"/>
+  <hjq-dialog-open-button dialog="##{dialog_id}" param>
+    New <% this_field.humanize %>
+  </hjq-dialog-open-button>
+  <hjq-dialog param buttons='&[["cancel", "hjq.dialog.close"], ["ok", "hjq.dialog.submit_formlet_and_close"]]' title="New #{this_field.humanize}" id="&dialog_id" >
+    <formlet with="&this_type.new" update="&part_id" success="jQuery('##{part_id} select').val(jQuery('##{part_id} option:last').val())">
+      <field-list />
+    </formlet>
+  </hjq-dialog>
+</def>