EditBackground
All though we really encourage our users to use the WebControl way of creating Ajax functionality there will come times when more "low level constructs" are needed. Often these kind of scenarios will arise out of the need to embed 3rd part libraries and components into Gaia but still be able to have access to the values of these controls in the server-side code together with the whole "Gaia Page Life Cycle" logic.
Gaia has the ability to directly call Server-Side Ajax Methods from your own custom JavaScript, this is done through the Gaia.Control.callPageMethod method. It takes three parameters;
- Method name
- Array of arguments
- JavaScript delegate (or method) to execute when the server returns
The Method name is the name of the method on your page in your codebehind file.
The Array of arguments is a JavaScript array of parameters taken by your method on the server-side.
The JavaScript delegate is a method you define yourself which will be executed when the Ajax server-side Method call returns.
Note that none of the Gaia Ajax Widgets JavaScript files will be included on your page unless you either explicitly include them yourself or add up at least one visible Gaia Control onto your page.
Also callPageMethod will try to find the method first on your Page, then if it doesn't find it there it will look into your MasterPage if you have one defined. Also the method you're calling must be marked with the
Method attribute since otherwise users could call into your private methods in your classes and in fact also the private methods of the classes in ASP.NET which would be a serious security risk. Gaia can also call methods residing in UserControls by adding up the ClientID of the UserControls follwed by a "." and then the name of the method. If you for instance have a UserControl with a ClientID of "myUserControl" and you want to call a method named "Foo" on this UserControl you would type in; "myUserControl.Foo" as the method name parameter to the callPageMethod function.
If it doesn't find a method matching all these criterias it will throw an exception resulting in an HTTP 500 status error code.
EditAjax WebMethods in Gaia and "nested controls"
In Gaia you can call Ajax WebMethods residing in nested MasterPages within nested UserControls and so on as many time as you wish. Though you need to "lead" Gaia through your nested scope of objects. This means that if you have two nested MasterPages and two nested UserControls within the inner MasterPage you can still call methods in the "most inner UserControl". This should then be done like this;
...callPageMethod(‘ContentPlaceHolder1.ContentPlaceHolder2.UserControl1.UserControl2.MyPageMethod’...
Where the ContentPlaceHolderX is the ContentPlaceHolderID of your MasterPage and the UserControlX is the ClientID of your UserControls.
It even works even though you have defined no CodeBehind file for your WebPage.
EditSample code demonstrating calling Ajax Server-Side methods from JavaScript
<%@ Page
Language="C#"
AutoEventWireup="true"
ClassName="_Default" %>
<%@ Register
Assembly="Gaia.WebWidgets"
Namespace="Gaia.WebWidgets"
TagPrefix="gaia" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Ajax Sample</title>
<script runat="server" type="text/C#">
// We must mark our server-side method with the "Method" attribute
[Gaia.WebWidgets.Method]
private string foo()
{
// Here we can modify any Gaia Widgets we wish
lbl.Text = "Hello world";
// And this will be the "return value" back to the client script
return "Ajax Web 2.0 world... ;)";
}
</script>
<script type="text/javascript">
// JavaScript and point called when server-side method returns
// The "response" argument here will be the return statement from the server-side method
function fooFinished(response)
{
$('someHtmlElement').innerHTML = response;
}
// Called by the button "onclick" JavaScript event
function callFoo()
{
Gaia.Control.callPageMethod("foo", null, fooFinished);
}
</script>
</head>
<body>
<form id="form1" runat="server">
<gaia:Label
runat="server"
ID="lbl" />
<br />
<input type="button" onclick="callFoo();" value="Hello WHO?" />
<div id="someHtmlElement">
Hello
</div>
</form>
</body>
</html>