Developing a JQuery Application
In this example we show how to build an AJAX application using JQuery for a RISE information solution. We assume that you are fairly accustomed to HTML and Javascript programming so we'll focus on the RISE parts. Our example is a limited application that displays "Hello World!" in the selected language and allows the user to add new languages.
JQuery is a minimal footprint Javascript library and it's an excellent choice for building AJAX web applications based on JSON and RISE web services. Furthermore, it's provided online so you don't need to download it as part of your solution. Just include it in your web page using <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>.
Sample solution
The HelloWorld sample is a small browser based application for finding out how to say "Hello world!" in different countries. It contains a set of interactive panels, all displayed in a single web page, and some language and country data. Note that the data is for test purposes only and could be incomplete and/or incorrect.
The actual AJAX sample application is implemented inside a plain HTML file. You may follow this example by downloading our Visual Studio solution including the web services used by the AJAX application. The project README file explains the needed setup.
The HelloWorld model
The HelloWorld RISE sample model contains two object; Country and Hello. Each Country may have one or more Hello attached to it. An Hello consists of a phrase and a language specification. Thus, the model allows a country to have one or more ways to say "Hello World!". The sample model comes with sample countrys and their official languages entered.
Understanding the application
The AJAX application is implemented inside a plain HTML file, HelloWorld.html. In this file we've placed a Javascript section where we've implemented all the dynamics and our AJAX.
The below snippet shows the code that's involved when the page is loaded. When the page is loaded it calls the Javascript function ListCountries. The ListCountries function calls the web service method ListCountry and, on success, creates HTML containing a selection list with all the countries. Finally, the generated HTML is displayed inside an HTML element with ID selectCountry. We'll go through this code in more detail at the end of the article.
var wsuri = 'hello.WS.IHelloWorld.asmx';
function ListCountries() {
$.ajax({
type: "POST",
url: wsuri + "/ListCountry",
data: '{ "maxRowsToReturn": null }',
contentType: "application/json; charset=utf-8",
dataType: "json",
success: function(response) {
var results = response.d || response;
var el = document.getElementById('country');
el.options[el.options.length] = new Option('select country', '0');
for (i=0; i<results.length; i++)
el.options[el.options.length] = new Option(results[i].Name, results[i].ID.toString());
},
error: function(x, msg) {
document.getElementById('selectCountry').innerHTML = msg || "Error";
},
complete: function() {
document.getElementById('phrases').innerHTML = '';
document.getElementById('languageMissing').innerHTML = '';
}
});
} |
Step-by-step walk-through:
- The Javascript function ListCountries uses the JQuery method $.ajax to call a web service. $.ajax is asynchronous¹ and accepts a single parameter (an object) containing all settings, input arguments and callback functions needed. For more details see the JQuery.ajax documentation.
- The first attributes, type and url, determine how to locate and call the web service. Essentially, the url should be URL to web service / method name.
- The data attribute is a JSON encoded string containing the parameters to pass to the web service method. In this example we pass a single argument maxRowsToReturn which is set to null. Make sure you use strict JSON encoding where member names and string values are quoted using ".
- The contentType argument is set to application/json to instruct the web service to use its JSON serializer/deserializer.
- The dataType is for JQuery internal use. It tells JQuery to expect a JSON result back from the service.
- The success function is called by JQuery on successful completion. The result data is available in the response argument. Note that different JSON serializers may return different results. The assigment, results = response.d || response, takes care of the differences between .NET and PHP (standard). The articles on the RISE C# codegenerator and the RISE PHP codegenerator provides further details on JSON encoding. In the example the result is used to populate a selection list.
- The error function is called, instead of the success function, by JQuery if an error occurs. The msg argument contains the type of error.
- Finally JQuery calls the complete function. This function is called after the call to success or error.
¹ Asynchronous means that other Javascript code in your HTML page may be executed before the callback is called.
