JavaScriptGenerator generates blocks of JavaScript code that allow you to change the content and presentation of multiple DOM elements. Use this in your Ajax response bodies, either in a <script> tag or as plain JavaScript sent with a Content-type of "text/javascript".
Create new instances with PrototypeHelper#update_page or with ActionController::Base#render, then call insert_html, replace_html, remove, show, hide, visual_effect, or any other of the built-in methods on the yielded generator in any order you like to modify the content and appearance of the current page.
Example:
update_page do |page|
page.insert_html :bottom, 'list', "<li>#{@item.name}</li>"
page.visual_effect :highlight, 'list'
page.hide 'status-indicator', 'cancel-link'
end
generates the following JavaScript:
new Insertion.Bottom("list", "<li>Some item</li>");
new Effect.Highlight("list");
["status-indicator", "cancel-link"].each(Element.hide);
Helper methods can be used in conjunction with JavaScriptGenerator. When a helper method is called inside an update block on the page object, that method will also have access to a page object.
Example:
module ApplicationHelper
def update_time
page.replace_html 'time', Time.now.to_s(:db)
page.visual_effect :highlight, 'time'
end
end
# Controller action
def poll
render(:update) { |page| page.update_time }
end
You can also use PrototypeHelper#update_page_tag instead of PrototypeHelper#update_page to wrap the generated JavaScript in a <script> tag.
- <<
- []
- alert
- assign
- call
- delay
- draggable
- drop_receiving
- hide
- insert_html
- literal
- redirect_to
- remove
- replace
- replace_html
- select
- show
- sortable
- toggle
- visual_effect
Writes raw JavaScript to the page.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 537
537: def <<(javascript)
538: @lines << javascript
539: end
Returns a element reference by finding it through id in the DOM. This element can then be used for further method calls. Examples:
page['blank_slate'] # => $('blank_slate');
page['blank_slate'].show # => $('blank_slate').show();
page['blank_slate'].show('first').up # => $('blank_slate').show('first').up();
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 387
387: def [](id)
388: JavaScriptElementProxy.new(self, id)
389: end
Displays an alert dialog with the given message.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 513
513: def alert(message)
514: call 'alert', message
515: end
Assigns the JavaScript variable the given value.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 532
532: def assign(variable, value)
533: record "#{variable} = #{javascript_object_for(value)}"
534: end
Calls the JavaScript function, optionally with the given arguments.
If a block is given, the block will be passed to a new JavaScriptGenerator; the resulting JavaScript code will then be wrapped inside function() { … } and passed as the called function‘s final argument.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 527
527: def call(function, *arguments, &block)
528: record "#{function}(#{arguments_for_call(arguments, block)})"
529: end
Executes the content of the block after a delay of seconds. Example:
page.delay(20) do
page.visual_effect :fade, 'notice'
end
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 546
546: def delay(seconds = 1)
547: record "setTimeout(function() {\n\n"
548: yield
549: record "}, #{(seconds * 1000).to_i})"
550: end
Creates a script.aculo.us draggable element. See ActionView::Helpers::ScriptaculousHelper for more information.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 568
568: def draggable(id, options = {})
569: record @context.send(:draggable_element_js, id, options)
570: end
Creates a script.aculo.us drop receiving element. See ActionView::Helpers::ScriptaculousHelper for more information.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 574
574: def drop_receiving(id, options = {})
575: record @context.send(:drop_receiving_element_js, id, options)
576: end
Hides the visible DOM elements with the given ids.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 503
503: def hide(*ids)
504: loop_on_multiple_args 'Element.hide', ids
505: end
Inserts HTML at the specified position relative to the DOM element identified by the given id.
position may be one of:
| :top: | HTML is inserted inside the element, before the element‘s existing content. |
| :bottom: | HTML is inserted inside the element, after the element‘s existing content. |
| :before: | HTML is inserted immediately preceeding the element. |
| :after: | HTML is inserted immediately following the element. |
options_for_render may be either a string of HTML to insert, or a hash of options to be passed to ActionView::Base#render. For example:
# Insert the rendered 'navigation' partial just before the DOM # element with ID 'content'. insert_html :before, 'content', :partial => 'navigation' # Add a list item to the bottom of the <ul> with ID 'list'. insert_html :bottom, 'list', '<li>Last item</li>'
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 444
444: def insert_html(position, id, *options_for_render)
445: insertion = position.to_s.camelize
446: call "new Insertion.#{insertion}", id, render(*options_for_render)
447: end
Returns an object whose to_json evaluates to code. Use this to pass a literal JavaScript expression as an argument to another JavaScriptGenerator method.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 393
393: def literal(code)
394: ActiveSupport::JSON::Variable.new(code.to_s)
395: end
Redirects the browser to the given location, in the same form as url_for.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 518
518: def redirect_to(location)
519: assign 'window.location.href', @context.url_for(location)
520: end
Removes the DOM elements with the given ids from the page.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 493
493: def remove(*ids)
494: loop_on_multiple_args 'Element.remove', ids
495: end
Replaces the "outer HTML" (i.e., the entire element, not just its contents) of the DOM element with the given id.
options_for_render may be either a string of HTML to insert, or a hash of options to be passed to ActionView::Base#render. For example:
# Replace the DOM element having ID 'person-45' with the # 'person' partial for the appropriate object. replace 'person-45', :partial => 'person', :object => @person
This allows the same partial that is used for the insert_html to be also used for the input to replace without resorting to the use of wrapper elements.
Examples:
<div id="people">
<%= render :partial => 'person', :collection => @people %>
</div>
# Insert a new person
page.insert_html :bottom, :partial => 'person', :object => @person
# Replace an existing person
page.replace 'person_45', :partial => 'person', :object => @person
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 488
488: def replace(id, *options_for_render)
489: call 'Element.replace', id, render(*options_for_render)
490: end
Replaces the inner HTML of the DOM element with the given id.
options_for_render may be either a string of HTML to insert, or a hash of options to be passed to ActionView::Base#render. For example:
# Replace the HTML of the DOM element having ID 'person-45' with the # 'person' partial for the appropriate object. replace_html 'person-45', :partial => 'person', :object => @person
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 458
458: def replace_html(id, *options_for_render)
459: call 'Element.update', id, render(*options_for_render)
460: end
Returns a collection reference by finding it through a CSS pattern in the DOM. This collection can then be used for further method calls. Examples:
page.select('p') # => $$('p');
page.select('p.welcome b').first # => $$('p.welcome b').first();
page.select('p.welcome b').first.hide # => $$('p.welcome b').first().hide();
You can also use prototype enumerations with the collection. Observe:
page.select('#items li').each do |value|
value.hide
end
# => $$('#items li').each(function(value) { value.hide(); });
Though you can call the block param anything you want, they are always rendered in the javascript as ‘value, index.’ Other enumerations, like collect() return the last statement:
page.select('#items li').collect('hidden') do |item|
item.hide
end
# => var hidden = $$('#items li').collect(function(value, index) { return value.hide(); });
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 418
418: def select(pattern)
419: JavaScriptElementCollectionProxy.new(self, pattern)
420: end
Shows hidden DOM elements with the given ids.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 498
498: def show(*ids)
499: loop_on_multiple_args 'Element.show', ids
500: end
Creates a script.aculo.us sortable element. Useful to recreate sortable elements after items get added or deleted. See ActionView::Helpers::ScriptaculousHelper for more information.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 562
562: def sortable(id, options = {})
563: record @context.send(:sortable_element_js, id, options)
564: end
Toggles the visibility of the DOM elements with the given ids.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 508
508: def toggle(*ids)
509: loop_on_multiple_args 'Element.toggle', ids
510: end
Starts a script.aculo.us visual effect. See ActionView::Helpers::ScriptaculousHelper for more information.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/prototype_helper.rb, line 554
554: def visual_effect(name, id = nil, options = {})
555: record @context.send(:visual_effect, name, id, options)
556: end