Conduits are special data links between the client and the server. You can think of a data conduit as a pipe connecting a water tank to the kitchen faucet. From within the kitchen you can control the amount of water coming into and out of pipe. This is exactly what Raxan data conduits do.
By using JavaScript you can dynamical control the flow of data to your web page. This means that you will be able page or loop through a range of data records within the conduit.
<script type="text/javascript">
Raxan.ready(function(){
var cn = Raxan.createConduit('customers');
function loadPage(n) {
cn.page(n, function(rowset,offset) {
var lst = '';
for(i in rowset) {
lst+='<div>'+rowset[i]['first_name']+'</div>';
}
$('#result').html(lst);
});
}
})
</script>
When a conduit is connected to the server it sends a request to have data downloaded to the web page. This action triggers special data handlers that are used to return the data to the client. Here's the what page execution cycle looks like during a conduit request:
The conduit API will automatically handle data caching, loading and navigation so that you can focus on what you want to do with the data.
To create a conduit you will first need to register the conduit and the data handler:
<?php
protected function _init() {
// register a conduit called myDataset
$this->registerConduit('myDataset','.dataHandler');
}
protected function dataHandler($offset, $limit, $params, &$rowcount){
// use a .csv file for the data source
$csv = $this->Raxan->importCSV('contacts.csv');
if (rowcount==0) $rowcount = count($csv); // set rowcount
$ds = array_slice($csv, $offset, $limit);
return $ds; // returns the dataset as a 2D array
}
?>
From the browser you can use the Raxan.createConduit() to create a connection to the conduit.
Raxan.createConduit() Syntax:
Raxan.createConduit(name,option)
Raxan.createConduit() Options:
To create a
<script type="text/javascript">
Raxan.ready(function() {
// connect to the "myDataset" conduit using default settings
var cn = Raxan.createConduit('myDataset');
// create a custom connection
var cn = Raxan.createConduit('myDataset',{
bufferSize: 100,
pageSize: 20,
before: function(){ /* executed before conduit is called */ },
after: function(){ /* executed after conduit is called */ },
error: function(conduit, result){
if (result) alert('error:'+result);
return true; // let Raxan know that the error was handled
}
});
})
</script>
After connecting to the server you can submit a request to download data when needed:
<script type="text/javascript">
cn.first(function(row,offset){
$('#list1').append('#'+offset+' - '+row['name']+'<br>');
})
</script>
Use the conduit JavaScript API to load and navigate data sets.
To load the an individual data record use first(), next(), prev(), last(), or moveTo():
<script type="text/javascript">
// get first record
cn.first(function(row,offset) {
alert('First contact: ' + row['name']);
});
// get next record
cn.next(function(row,offset) {
alert('Next contact: ' + row['name']);
});
// get last record
cn.last(function(row,offset) {
alert('Last contact: ' + row['name']);
});
// get prev record
cn.last(function(row,offset) {
alert('Previous contact: ' + row['name']);
});
// move to record #10
cn.moveTo(10,function(row,offset) {
alert('Contact #'+(offset+1)+': ' + row['name']);
});
</script>
To retrieve a record without changing the current offset or position use the get method as shown below:
<script type="text/javascript">
//retrieve record #25 without changing the current position
cn.get(25,function(row,offset) {
alert('Contact #'+(offset+1)+': ' + row['name']);
});
</script>
A page is a set of data records based on the pageSize option value. If the pageSize option is set to 10 then the Raxan will download 10 records from the server.
To load a page, use the page() method as shown below:
<script type="text/javascript">
// load page #1
cn.page(1, function(rowset,offset){
var i, row;
for(i in rowset) {
row = rowset[i];
// append record to #content
$('#content').append('Contact #'+(offset+1)+': ' + row['name']);
}
})
</script>
The page() method will retrieve the records from server (or data cache), then pass an array of records and the current offset to the callback function.
To retrieve the total number of page count use the pageCount() method:
To retrieve a set of records from the from the conduit, you can use the loop() and loopBy() method. The loop() method requires a starting and ending value for the range of records to be retrieved, while the loopBy() method only requires the number of records to be retrieved from the current offset:
<script type="text/javascript">
// retrieve the first 20 records (0-19)
cn.loop(0,19,function(row, offset,index, length){
var elm = $('#info');
if (index==0) elm.html('').hide();
if (index<length) elm.append(row['name']+'<br>');
if (index>=length-1) elm.show;
})
// retrieve the next 10 records from the current offset
cn.loopBy(10,function(row, offset, index, length){
var elm = $('#info');
if (index==0) elm.html('').hide();
if (index<length) elm.append(row['name']+'<br>');
if (index>=length-1) elm.show;
})
</script>
The "index" parameter represents the current index within the loop while the "length" parameter represents the number of items within the loop. See the Raxan JavaScrit Object (RJO) for more information.
Up Next: Raxan JavaScript Object