Module: ActionView::Helpers::JavaScriptMacrosHelper

Defined in:
lib/action_view/helpers/java_script_macros_helper.rb

Overview

Provides a set of helpers for creating JavaScript macros that rely on and often bundle methods from JavaScriptHelper into larger units. These macros also rely on counterparts in the controller that provide them with their backing. The in-place editing relies on ActionController::Base.in_place_edit_for and the autocompletion relies on ActionController::Base.auto_complete_for.

Instance Method Summary collapse

Instance Method Details

#auto_complete_field(field_id, options = {}) ⇒ Object

Adds AJAX autocomplete functionality to the text input field with the DOM ID specified by field_id.

This function expects that the called action returns a HTML <ul> list, or nothing if no entries should be displayed for autocompletion.

You’ll probably want to turn the browser’s built-in autocompletion off, su be sure to include a autocomplete=“off” attribute with your text input field.

Required options are:

:url

URL to call for autocompletion results in url_for format.

Addtional options are:

:update

Specifies the DOM ID of the element whose innerHTML should be updated with the autocomplete entries returned by the AJAX request. Defaults to field_id + ‘_auto_complete’

:with

A JavaScript expression specifying the parameters for the XMLHttpRequest. This defaults to ‘fieldname=value’.

:indicator

Specifies the DOM ID of an element which will be displayed while autocomplete is running.

:tokens

A string or an array of strings containing separator tokens for tokenized incremental autocompletion. Example: :tokens => ',' would allow multiple autocompletion entries, separated by commas.

:min_chars

The minimum number of characters that should be in the input field before an Ajax call is made to the server.

:on_hide

A Javascript expression that is called when the autocompletion div is hidden. The expression should take two variables: element and update. Element is a DOM element for the field, update is a DOM element for the div from which the innerHTML is replaced.

:on_show

Like on_hide, only now the expression is called then the div is shown.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/action_view/helpers/java_script_macros_helper.rb', line 106

def auto_complete_field(field_id, options = {})
  function =  "new Ajax.Autocompleter("
  function << "'#{field_id}', "
  function << "'" + (options[:update] || "#{field_id}_auto_complete") + "', "
  function << "'#{url_for(options[:url])}'"
  
  js_options = {}
  js_options[:tokens] = array_or_string_for_javascript(options[:tokens]) if options[:tokens]
  js_options[:callback]   = "function(element, value) { return #{options[:with]} }" if options[:with]
  js_options[:indicator]  = "'#{options[:indicator]}'" if options[:indicator]
  {:on_show => :onShow, :on_hide => :onHide, :min_chars => :min_chars}.each do |k,v|
    js_options[v] = options[k] if options[k]
  end
  function << (', ' + options_for_javascript(js_options) + ')')

  javascript_tag(function)
end

#auto_complete_result(entries, field, phrase = nil) ⇒ Object

Use this method in your view to generate a return for the AJAX autocomplete requests.

Example action:

def auto_complete_for_item_title
  @items = Item.find(:all, 
    :conditions => [ 'LOWER(description) LIKE ?', 
    '%' + request.raw_post.downcase + '%' ])
  render :inline => '<%= auto_complete_result(@items, 'description') %>'
end

The auto_complete_result can of course also be called from a view belonging to the auto_complete action if you need to decorate it further.



137
138
139
140
141
 
# File 'lib/action_view/helpers/java_script_macros_helper.rb', line 137

def auto_complete_result(entries, field, phrase = nil)
  return unless entries
  items = entries.map { |entry| content_tag("li", phrase ? highlight(entry[field], phrase) : h(entry[field])) }
  content_tag("ul", items.uniq)
end

#in_place_editor(field_id, options = {}) ⇒ Object

Makes an HTML element specified by the DOM ID field_id become an in-place editor of a property.

A form is automatically created and displayed when the user clicks the element, something like this: <form id=“myElement-in-place-edit-form” target=“specified url”>

<input name="value" text="The content of myElement"/>
<input type="submit" value="ok"/>
<a onclick="javascript to cancel the editing">cancel</a>

</form>

The form is serialized and sent to the server using an AJAX call, the action on the server should process the value and return the updated value in the body of the reponse. The element will automatically be updated with the changed value (as returned from the server).

Required options are:

:url

Specifies the url where the updated value should be sent after the user presses “ok”.

Addtional options are:

:rows

Number of rows (more than 1 will use a TEXTAREA)

:cancel_text

The text on the cancel link. (default: “cancel”)

:ok_text

The text on the save link. (default: “ok”)

:options

Pass through options to the AJAX call (see prototype’s Ajax.Updater)

:with

JavaScript snippet that should return what is to be sent in the AJAX call, form is an implicit parameter



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/action_view/helpers/java_script_macros_helper.rb', line 37

def in_place_editor(field_id, options = {})
  function =  "new Ajax.InPlaceEditor("
  function << "'#{field_id}', "
  function << "'#{url_for(options[:url])}'"

  js_options = {}
  js_options['cancelText'] = options[:cancel_text] if options[:cancel_text]
  js_options['okText'] = options[:save_text] if options[:save_text]
  js_options['rows'] = options[:rows] if options[:rows]
  js_options['ajaxOptions'] = options[:options] if options[:options]
  js_options['callback']   = "function(form) { return #{options[:with]} }" if options[:with]
  function << (', ' + options_for_javascript(js_options)) unless js_options.empty?
  
  function << ')'

  javascript_tag(function)
end

#in_place_editor_field(object, method, tag_options = {}, in_place_editor_options = {}) ⇒ Object

Renders the value of the specified object and method with in-place editing capabilities.

See the RDoc on ActionController::InPlaceEditing to learn more about this.



58
59
60
61
62
63
64
 
# File 'lib/action_view/helpers/java_script_macros_helper.rb', line 58

def in_place_editor_field(object, method, tag_options = {}, in_place_editor_options = {})
  tag = ::ActionView::Helpers::InstanceTag.new(object, method, self)
  tag_options = {:tag => "span", :id => "#{object}_#{method}_#{tag.object.id}_in_place_editor", :class => "in_place_editor_field"}.merge!(tag_options)
  in_place_editor_options[:url] = in_place_editor_options[:url] || url_for({ :action => "set_#{object}_#{method}", :id => tag.object.id })
  tag.to_content_tag(tag_options[:tag], tag_options) +
  in_place_editor(tag_options[:id], in_place_editor_options)
end

#text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {}) ⇒ Object

Wrapper for text_field with added AJAX autocompletion functionality.

In your controller, you’ll need to define an action called auto_complete_for_object_method to respond the AJAX calls,

See the RDoc on ActionController::AutoComplete to learn more about this.



149
150
151
152
153
154
 
# File 'lib/action_view/helpers/java_script_macros_helper.rb', line 149

def text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {})
  (completion_options[:skip_style] ? "" : auto_complete_stylesheet) +
  text_field(object, method, tag_options) +
  content_tag("div", "", :id => "#{object}_#{method}_auto_complete", :class => "auto_complete") +
  auto_complete_field("#{object}_#{method}", { :url => { :action => "auto_complete_for_#{object}_#{method}" } }.update(completion_options))
end