Home

Castle Stronghold

AjaxHelper

» Home » MonoRail » Documentation » MonoRail trunk Documentation » MonoRail Helpers » AjaxHelper

MonoRail supports Ajax by using the prototype jslib.

First of all, to use Ajax support you must make the javascript code available to your view:

 

$AjaxHelper.InstallScripts()


${AjaxHelper.InstallScripts()}

Which will render: 

<script type="text/javascript" src="/MonoRail/Files/AjaxScripts.rails"></script>

Behavioural functions used to be accesible on the AjaxHelper but are now located in the BehaviourHelper

Common parameters

The more you know about the prototype library, the better. We recommend the Developer Notes for prototype.js although it is a little outdated.

The prototype library has two main classes to perform remote requests:

The following parameters can be used on both Ajax.Request and Ajax.Updater:

ParameterDescription
url The url to be invoked. You cannot specify parameters (like url?key=value). If you need to pass parameters, use the with parameter.
method Http method to be used on the invocation. Defaults to 'post'.
with Defines the parameters to be send with the request. For example name=hammett&age=27&iscustomer=true
form If you omit the with parameter but include the form then it will generate code to serialize the current form. Equivalent to use with=Form.serialize(this).

When you specify the parameter update or success or failure, the AjaxHelper will generate an Ajax.Updater call. The following parameters applies to it:

ParameterDescription
update Defines the name of the html element that will be updated with the return xml of the request. Usually a div is used.
success/failure Defines the name of the html element that will be updated conditionally with the return xml of the request. If the request is successful, the elemented pointed by success will be updated, otherwise it will use the elemented pointed by failure.
evalScripts Defines whether the returned xml should have its javascript content evaluated. Defaults to true.
position Defines a strategy to insert the resulting xml on the DOM. The supported values are Before, Top, Bottom and After.

Callbacks can also be used. The prototype will invoke the specified javascript functions during different steps in the remote invocation.

ParameterDescription
Loading Called when the remote document is being loaded with data by the browser.
Loaded Called when the browser has finished loading the remote document.
Interactive Called when the user can interact with the remote document, even though it has not finished loading.
Complete Called when the XMLHttpRequest has completed.
OnSuccess Called when the request was successfully (Status code < 500)
OnFailure Called when the request was not successfully (Status code >= 500)

You can also specify that a function must be executed before, after or define it as a condition to the Ajax request be issue.

ParameterDescription
before Defines that the specified javascript function must run before the Ajax request is sent.
after Defines that the specified javascript function must run right after the Ajax request is sent.
condition Defines that the specified function must return true to allow the Ajax request to take place.

Note that the OnSuccess and OnFailure callbacks will include a parameter called request which is the original XmlHttpRequest object. Your callback function will need to have a parameter called request to operate properly.

Using it

The best and easiest way to use the AjaxHelper is to check the API documentation to identify the method you want. Check its signature. Most of them will have an IDictionary parameter. This is an approach to make the ajax usage on views more self-documented.

The method API documentation should highlight required parameters or special meanings that a parameter might have. Note that the common parameters discussed above applies to most of the methods on AjaxHelper.

Examples

The following snippets shows the AjaxHelper in action.

 

$AjaxHelper.LinkToRemote("Show server time", "showtime.rails", "%{update='maindiv', OnSuccess='showSuccessMessage(request)'}") 


${AjaxHelper.LinkToRemote("Show RSS feed", "Rss.castle", {@update:"maindiv", @OnSuccess:"showSuccessMessage(request)"})}

API documentation

You may also consult the API documentation for the AjaxHelper.

Site map

The following is a list of the documents related to AjaxHelper:

Google
Search WWW Search castleproject.org