Raxan's flexible client-server communication model makes it easier to build sophisticated web applications while taking advantage of the framework's integrated features.
In the client-server model, a client submits data to the web server via a GET or POST request. This data can be either a server-side event notification, a page request or form submit. Upon receiving the request, the server will process the data and then returns the result as an HTML or JSON formatted text.
The list below shows the main methods for sending and receiving data to and from the server.
Type | Client Method | Direction | Server Method |
---|---|---|---|
Events | Raxan.dispatchEvent() | bind(), delegate(), registerEvent() | |
Variables | Raxan.getVar() | registerVar() | |
Functions | Any JavaScript Function | callScriptFn() | |
Conduits | Raxan.createConduit() | registerConduit() |
Events are special actions that are used to invoke a callback method on the web server. These events can be triggered locally or remotely.
To receive server-side event notifications in Raxan you can use either bind(), delegate() or the xt-bind/xt-delegate attributes. Here's an example showing how to use bind()
<?php
$this->button1->bind('click','.buttonClick');
?>
This will bind the callback method to the click event on the client.
When button1 is clicked the framework will call the buttonClick method on the server. See Server-side Events for more information.
To programmatically dispatch an event from the client, use can use the Raxan.dispatchEvent() method.
Raxan.dispatchEvent Syntax:
Raxan.dispatchEvent(option) - dispatch with an array of options
Raxan.dispatchEvent(type, fn) - dispatch with callback function
Raxan.dispatchEvent(type, value, fn)
Raxan.dispatchEvent Options:
Example:
<script type="text/javascript">
Raxan.dispatchEvent('click',value,function(result,success){
alert(result);
});
</script>
The Raxan.dispatchEvent() method is normally used to invoke a registered event:
<?php
protected function _init() {
// register the add item event
$this->registerEvent('additem','.callbackFunction');
}
?>
Dispatch the "additem" event from the client:
<script type="text/javascript">
Raxan.ready(function() {
// dispatch event with callback
Raxan.dispatchEvent('additem',function(result, success) {
if (!success) return false;
alert(result);
})
// dispatch event while passing value and callback paramters
var eventValue = 'Hello';
Raxan.dispatchEvent('additem',eventValue,function(result,success) {
if (!success) return false;
alert(result);
})
// dispatch with options
Raxan.dispatchEvent( {
type : 'additem',
view : 'form',
value : 'some value here',
serialize : '#form1',
complete: function(result, success, statusCode) {
if (!success) {
if (statusCode==404) alert('File not found');
else alert('Error while connecting to server: ' + result);
return false; // return false to prevent display of error message
}
// code here
}
})
})
</script>
Registered variables provide a convenient way to send data to the client from the server. For example, You can send an array of items to the browser after the user has triggered an event:
<?php
protected function sendData($msg) {
// register the variable so that it can be available to the client
$this->registerVar('msgVar',$msg);
}
?>
You can use the following code to retrieve the content of the "msgVar" variable from the client:
<script type="text/javascript">
Raxan.ready(function() {
var msg;
// retrieve msgVar
msg = Raxan.getVar('msgVar');
alert(msg);
// retrieve and remove msgVar
msg = Raxan.getVar('msgVar',true);
alert(msg);
})
</script>
The registerVar() method supports the following data types:
To call a JavaScript function from the sever use the callScriptFn() method as shown below:
<?php
protected callback($e) {
// call and pass a simple parameter to "some_function" on the client
$param1 = 'Test message';
$this->callScriptFn('some_function',$param1);
// call and pass an array parameter to "some_function" on the client
$param1 = 'Colors';
$param2 = array('red','green','blue');
$this->callScriptFn('some_function',$param1,$param2);
}
?>
A conduit forms a consistent data link between the client and the server so that data can be asynchronously access when needed. Conduits can also be used to download and cache very large dataset that can later be displayed within the browser.
A conduit must first be registered on the server then accessed from the client.
To create a conduit, use the registerConduit method as shown below:
<?php
protected function _init() {
$this->registerConduit('myDataset','.getData');
}
// data conduit handler
protected function getData($offset, $limit, $params, &$rowCount) {
$db = $this->Raxan->connect('mysql: host=local; dbname=testdb','user','password', true);
// get row count
if (!$rowCount) {
$stmt = $db->query('select count(*) as total from customers');
$rowCount = (int)$stmt->fetchColumn(0);
}
// get dataset
$ds = $db->execQuery('select * from customers limit $offset,$limit');
return $ds;
}
?>
To connect to the above conduit use the Raxan.createConduit() method. This will return an instance to the Raxan.Conduit object:
<script type="text/javascript">
// create connection to conduit
var cn = Raxan.createConduit('myDataset');
// get first record
cn.first(function(row,index) {
alert('The first customer is ' + row['name']);
});
</script>
See Asynchronous Data Conduits for more information.
Up Next: Asynchronous Data Conduits