<ajax>

New To Version 4.2

AJAX stands for Asynchronous Javascript XML and is used to collectively define the set of technologies and techniques which enable Javascript, running in the browser, to fetch and process data that resides on the server without doing a page refresh. This allows the page to be dynamic by loading data as necessary from the server, but without the overhead that comes with fetching a full page. Using Dynamic HTML (DHTML), you can insert the new data into the place of your choice within your page, you can use the returned data to change the look and style of your page, you can load a form control with the data, or anything else you can do with Javascript.

XMod's new <ajax> control makes it much easier to implement your own AJAX-based solutions. It handles all the plumbing for you. You can just focus on the end result. While the control makes it simpler, you'll still need to do some work and it will help to know at least a little Javascript and HTML.

ATTRIBUTES:

ref	A unique identifier used to access the AJAX control. Since this value will be used to register the AJAX object in the web page and the object will be accessible throughout the page, the value must be unique within the whole page and not just the form as with most XMod controls. . [String value]
action	The kind of action you'd like the AJAX control to perform once it has received the data from the web server. There are two types of actions: InsertResult: This will take the response text that is sent from the server and insert it into the HTML element identified in the target property, completely replacing that element's contents. CallFunction: This is probably the action that will be most used by those familiar with Javascript. It will take the returned results and pass them to the function you specify in the target attribute. Note that the function you specify must have the same signature (the same number of parameters) as what is specified below: function (status,statusText,responseText,responseXML) status is the code returned by the server, representing the status of your request. This is helpful in determining whether your request to the server succeeded. statusText is the text that describes the status responseText is the value you'll use most often. It is the actual raw result returned from the server. responseXML is used whenever the server returns an XML document. If it does, this will be an XML document object. Otherwise it will be null. [String value]
target	The meaning of this attribute changes based on what action is specified. If action is InsertResult then this value should be the ID of an element within the page. If you have a <span id="spnBookTitle"> </span> tag pair and you wanted to place the results of your AJAX call inside that tag, you would put spnBookTitle as your target value. If, however, the action has been set to CallFunction then you would specify the name of the function you want called when the results are returned. For example, let's say you have a function which shows results in an alert dialog box. The function is below: `function showResults(status,statusText,responseText,responseXML){ alert('showResults Function Called: ' + responseText); }` The value of target would be the name of that function: target="showResults". [String value]
method	This attribute determines how your request will be sent to the server. get: In most cases, you'll simply want to specify a web address like "/samples/book1.html". For simple requests such as this, you will be sending your requests via the GET method. This is the default value for this attribute. So, if you are using GET, you don't need to specify a method. post: However, if you'll need to send a fair amount of data to the server, you'll want to set method to this value. When you do you can also specify the contenttype attribute. (Optional - Default Value: get)
contenttype	This attribute is ignored unless you are sending data via HTTP POST (i.e. method="post"). When you do so, you'll need to tell the server what format you'll be sending the data in. Most of the time, the content type is "application/x-www-form-urlencoded" which simply means that you're sending data to the server in name/value pairs, like you would if you were sending data as part of the URL. For instance, if you had three parameters and their values to send: param1 value = red param2 value = 234 param3 value = john As part of a URL, you would send the data in this manner: http://mysite.com/mypage.aspx?param1=red&param2=234&param3=john If you were POSTing this data, you would send: param1=red&param2=234&param3=john (Optional - Default Value: application/x-www-form-urlencoded)

FUNCTIONS:

call(url,params)

This initiates your AJAX request. You would typically put this in the onclick or onchange or similar attribute of a control or hyperlink so that when the user clicks the link, the AJAX request is made. As part of the function call, you must supply a URL, but params is optional and only used if you've set method="post". If method="get" then params isn't needed since you would supply your parameters as part of the URL.

url: (Required) The URL is the page to which the AJAX request will be sent. This may be a simple web page containing HTML or Text, it may be a file containing Javascript, or it may be server-script page like an ASP.NET or ASP page. For security reasons, the URL specified must be in the same domain as the page making the AJAX request. In other words, if your form is on http://mysite.com, the page to which you send the request must also reside on http://mysite.com. It's possible to get around this restriction (though you should take care to ensure the data returned isn't harmful or malicious) by setting up a "proxy" page on your domain. The proxy acts as a middle man in that it requests the data from the outside source and sends it back to the requesting page.
params: (Optional) The params argument is only used if you've set the method attribute to post. In that case, you use this argument to tell the <ajax> control to send the value you specify to the web server as part of your request. Typically, the params argument would be something like this: param1=123&param2=brown&name=john ... However, the format of the data you send in must match the format you specify contenttype attribute.

Samples: (Assumes the request is made from a page in http://mysite.com)

ajax1.call('/samples/books/101/synopsis.html')

ajax1.call('/calculateresult.aspx?val1=100&val2=50&operator=add')

ajax1.call('http://mysite.com/scripts/myscript.js')

...with method set to "post":

ajax1.call('/samples/books/101/synopsis.html')

ajax1.call('/samples/books.asp','id=101&type=synopsis')

ajax1.call('http://mysite.com/proxy.aspx', 'color=blue&city=Jacksonville')

EXAMPLES:

Example 1: Inserting HTML Into Your Page

Let's start with a simple example: inserting some HTML from a page that resides on your server into your XMod form. In your favorite text editor or web editor, create the following simple web page:

<html>
<body>
<p style="color:red">Now is the winter of our discontent...</p>
</body>
</html>

This is a very simple page. It displays a bit of Shakespearean text in red. Save this to the root of your web site as "samplecontent1.html". This is what we'll be retrieving from the server to insert into our page. Create a new XMod data-entry form. Since we'll be working with HTML, we'll need to create a Custom HTML Layout form. In your form, paste in this code then save the form:

<ajax ref="ajax1" action="InsertResult" target="divAjaxResults"/>
<literal>
<h2>AJAX Sample</h2>
<input type="button" onclick="ajax1.call('/samplecontent1.html')" value="Click Me" /><br /><br />
<div id="divAjaxResults" style="border: 1px solid black">Nothing</div>
</literal>
</controls>
</form>

Now, this form isn't very useful. There aren't even any XMod controls on it. Nevertheless, it serves as a good introduction to what you can do with AJAX in XMod. We've created a custom HTML layout form. The form contains one <ajax> tag and a <literal> </literal> block which contains all the HTML we're working with.

Notice the <ajax> tag only has three properties, the "ref" attribute - a required value. This value should be unique within the entire page (not just the form). We're also assigning the "action" property a value of "InsertResult". This tells the control that we want to stick the results into an element on the page. The "target" attribute, then, specifies the ID of the element into which the results will be inserted. The control uses the "innerHTML" property of the target element which means that everything inside that element will be replaced by the results of the AJAX call.

Next, you'll see that we've defined an ordinary HTML button control. This is where the action takes place. In its onclick event, we're using our control to make a call ("ajax1.call") to the server and return the web page we specify ('/samplecontent1.html'). Notice that the onclick attribute of the button is "ajax1.call('...')". "ajax1" is the value we supplied in the ref attribute of the <ajax> tag. If we had given the <ajax> tag a ref of "MrClean" the onclick attribute of the <button> tag would look like: "MrClean.call('...')". Remember that in Javascript the upper and lower case of items is important. "mrclean.call('...')" wouldn't work.

If you're familiar working with Javascript in XMod, you might be thinking to yourself that you should get the client-side ID of the ajax control using code like this:

document.getElementById(XModForm{XMOD_ModuleId}.ajax1)

In most cases you'd be correct. But the <ajax> tag is a special case since it doesn't represent an actual control on the form. Thus, the tag is built so that you just need to use its ref to address it. This also means that you need to take a little extra care to ensure you name your <ajax> tag with a value that is unique within the page.

Finally, we define a <div> tag with the ID of "divAjaxResults". Since we set the target of the <ajax> control to "divAjaxResults", the control will request "/samplecontent1.html" from the web server and stick its contents into the <div> tag, effectively inserting the Shakespearean quote into our form.

Example 2: Sending the Results to a Custom Function for Processing

This example shows how you can bypass the built-in processing of the <ajax> tag and send the results to a function you've created. This allows you to process the returned results in whatever manner you see fit. To keep things simple, we're going to create a function that displays the status of the request and the returned result in an alert dialog box.

For this example, we'll use the same file we created for Example 1 - the file containing our bit of Shakespearean dialog. We saved that file to our web site's root folder with the name "samplecontent1.html". So, all that remains for us to do is to create the XMod form. Create a new XMod data-entry form. Since we'll be working with HTML, we'll need to create a Custom HTML Layout form. In your form, paste in this code and save the form:

<scriptblock scriptid="AjaxCallback" registeronce="true" blocktype="ClientScript"> <script language="javascript" type="text/javascript"> function showResults(status,statusText,responseText,responseXML){ alert('showResults Function Called: ' + responseText); } </script> </scriptblock>

    <ajax ref="ajax1" action="CallFunction" target="showResults"/>
<literal>
   <h2>AJAX Call Function Sample</h2>
   <input type="button" onclick="ajax1.call('/samplecontent1.html')" value="Click Me" /><br />
</literal>
</controls>
</form>

This form is similar to the form we created for Example 1. In this version, though, we've set the <ajax> tag's action attribute to "CallFunction" and we've set the target attribute to the name of our function (showResults). The onclick attribute of the <button> tag is the same as Example 1. The biggest difference is the use of the <scriptblock> tag (new to version 4.2).

If you've used the <xmod:scriptblock> tag in your templates, then this will seem quite familiar as this is essentially the same tag, but it's been designed to be used in data-entry forms. We're using the <scriptblock> tag so that we can register our Javascript function near the top of the page. This is necessary because, in Javascript, a function must be declared before you can use it. So, by using the <scriptblock> tag, we are ensuring our function is declared, near the top of the page - before the AJAX object needs to use it. In the <scriptblock> tag, we assign a page-wide-unique name as the scriptid attribute. We're also using the registeronce attribute of the <scriptblock> tag so that our script will only appear once in the page. Inside the <scriptblock> tag, we include a standard script block - like you would include in any HTML page.

Our function, called showResults must match the same signature that the AJAX control is expecting. What is happening behind the scenes is that the AJAX control will receive the results from the AJAX request and then call our showResults function, passing in a defined set of parameters. If our function isn't set up to receive those parameters, an error will result. So, we define our function to receive the status, statusText, responseText, responseXML parameters. They can have different names, but they must be in the same order. The function itself is simple. It displays an alert dialog box that contains the contains the results returned from the AJAX request (responseText)..

The result: When the form is displayed, clicking the button will initiate the AJAX request. That request will be made to the web server to return the contents of the file "/samplecontent1.html". Since we specified an action of "CallFunction", the contents of samplecontent1.html will be passed to the function we identified in the <ajax> tag's target attribute: showResults. The end result is that an alert box will pop-up with the message "showResults Function Called:" along with the HTML source code of samplecontent1.html. This is because the alert dialog box does not interpret HTML which would happen if we inserted it into the page as we did in Example 1.