Module | ActionView::Helpers::PrototypeHelper::JavaScriptGenerator::GeneratorMethods
In: | lib/action_view/helpers/prototype_helper.rb

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:

      # Generates:
      #     new Insertion.Bottom("list", "<li>Some item</li>");
      #     new Effect.Highlight("list");
      #     ["status-indicator", "cancel-link"].each(Element.hide);
      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

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

Calls to JavaScriptGenerator not matching a helper method below generate a proxy to the JavaScript Class named by the method called.

Examples:

      # Generates:
      #     Foo.init();
      update_page do |page|
        page.foo.init
      end

      # Generates:
      #     Event.observe('one', 'click', function () {
      #       $('two').show();
      #     });
      update_page do |page|
        page.event.observe('one', 'click') do |p|
         p[:two].show
        end
      end

You can also use PrototypeHelper#update_page_tag instead of PrototypeHelper#update_page to wrap the generated JavaScript in a <script> tag.

### Methods

<< [] alert assign call delay draggable drop_receiving hide insert_html literal redirect_to remove replace replace_html select show sortable toggle visual_effect

### Public Instance methods

<<(javascript)

Writes raw JavaScript to the page.

Example:

     page << "alert('JavaScript with Prototype.');"

[](id)

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();

You can also pass in a record, which will use ActionController::RecordIdentifier.dom_id to lookup the correct id:

      page[@post]     # => $('post_45')
      page[Post.new]  # => $('new_post')

alert(message)

Displays an alert dialog with the given `message`.

Example:

      # Generates: alert('This message is from Rails!')
      page.alert('This message is from Rails!')

assign(variable, value)

Assigns the JavaScript `variable` the given `value`.

Examples:

     # Generates: my_string = "This is mine!";
     page.assign 'my_string', 'This is mine!'

     # Generates: record_count = 33;
     page.assign 'record_count', 33

     # Generates: tabulated_total = 47
     page.assign 'tabulated_total', @total_from_cart

call(function, *arguments, &block)

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.

Examples:

      # Generates: Element.replace(my_element, "My content to replace with.")
      page.call 'Element.replace', 'my_element', "My content to replace with."

      # Generates: alert('My message!')
      page.call 'alert', 'My message!'

      # Generates:
      #     my_method(function() {
      #       $("one").show();
      #       $("two").hide();
      #    });
      page.call(:my_method) do |p|
         p[:one].show
         p[:two].hide
      end

delay(seconds = 1) {|| ...}

Executes the content of the block after a delay of `seconds`. Example:

      # Generates:
      #     setTimeout(function() {
      #     ;
      #     new Effect.Fade("notice",{});
      #     }, 20000);
      page.delay(20) do
        page.visual_effect :fade, 'notice'
      end

draggable(id, options = {})

Creates a script.aculo.us draggable element. See ActionView::Helpers::ScriptaculousHelper for more information.

drop_receiving(id, options = {})

Creates a script.aculo.us drop receiving element. See ActionView::Helpers::ScriptaculousHelper for more information.

hide(*ids)

Hides the visible DOM elements with the given `ids`.

Example:

     # Hide a few people
     # Generates: ["person_29", "person_9", "person_0"].each(Element.hide);
     page.hide 'person_29', 'person_9', 'person_0'

insert_html(position, id, *options_for_render)

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 preceding 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'.
      # Generates: new Insertion.Before("content", "-- Contents of 'navigation' partial --");
      page.insert_html :before, 'content', :partial => 'navigation'

      # Add a list item to the bottom of the <ul> with ID 'list'.
      # Generates: new Insertion.Bottom("list", "<li>Last item</li>");
      page.insert_html :bottom, 'list', '<li>Last item</li>'

literal(code)

Returns an object whose `to_json` evaluates to `code`. Use this to pass a literal JavaScript expression as an argument to another JavaScriptGenerator method.

redirect_to(location)

Redirects the browser to the given `location` using JavaScript, in the same form as `url_for`.

Examples:

     # Generates: window.location.href = "/mycontroller";
     page.redirect_to(:action => 'index')

     # Generates: window.location.href = "/account/signup";
     page.redirect_to(:controller => 'account', :action => 'signup')

remove(*ids)

Removes the DOM elements with the given `ids` from the page.

Example:

     # Remove a few people
     # Generates: ["person_23", "person_9", "person_2"].each(Element.remove);
     page.remove 'person_23', 'person_9', 'person_2'

replace(id, *options_for_render)

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.
      page.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
      #
      # Generates: new Insertion.Bottom({object: "Matz", partial: "person"}, "");
      page.insert_html :bottom, :partial => 'person', :object => @person

      # Replace an existing person

      # Generates: Element.replace("person_45", "-- Contents of partial --");
      page.replace 'person_45', :partial => 'person', :object => @person

replace_html(id, *options_for_render)

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.
      # Generates:  Element.update("person-45", "-- Contents of 'person' partial --");
      page.replace_html 'person-45', :partial => 'person', :object => @person

select(pattern)

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:

      # Generates: $$('#items li').each(function(value) { value.hide(); });
      page.select('#items li').each do |value|
        value.hide
      end

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:

      # Generates: var hidden = $$('#items li').collect(function(value, index) { return value.hide(); });
      page.select('#items li').collect('hidden') do |item|
        item.hide
      end

show(*ids)

Shows hidden DOM elements with the given `ids`.

Example:

     # Show a few people
     # Generates: ["person_6", "person_13", "person_223"].each(Element.show);
     page.show 'person_6', 'person_13', 'person_223'

sortable(id, options = {})

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.

toggle(*ids)

Toggles the visibility of the DOM elements with the given `ids`. Example:

     # Show a few people
     # Generates: ["person_14", "person_12", "person_23"].each(Element.toggle);
     page.toggle 'person_14', 'person_12', 'person_23'      # Hides the elements
     page.toggle 'person_14', 'person_12', 'person_23'      # Shows the previously hidden elements

visual_effect(name, id = nil, options = {})

Starts a script.aculo.us visual effect. See ActionView::Helpers::ScriptaculousHelper for more information.

[Validate]