AjaxCore Tutorial


As per request of users, here's a brief example on how to use AjaxCore framework to create AJAX applications.

In this example, we will be creating a page for registering users, to keep things simple, let's suppouse there's an Username input field, a Password input field, and a textarea for user Signature.

Where's AJAX suppose to be? as there are only three fields on our example, it would be really nice to check out first that username not exists on our database prior to allowing the user to submit the form, so let's do that!. fist we create the fields of our example in a cool table.  
Now, we insert after the username field, a button to check out if username exists, and a Div to store results.

<table border="0" style="font-size: 10pt; font-family: Verdana">
    <tr>
        <td style="width: 300px; height: 50px;">
            Username:
        </td>
        <td style="width: 400px; height: 50px;">
            <input type="text" id="username" name="username" style="width: 200px" />
            <input type="button" id="checkButton" name="checkButton" value="Check" />  
            <div id="resultsDiv">&nbsp;</div>
        </td>
    </tr>
    <tr>
        <td style="width: 300px; height: 50px;">
            Password:
        </td>
        <td style="width: 400px; height: 50px;">
            <input type="password" id="password" name="password" style="width: 200px" />
        </td>
    </tr>
    <tr>
        <td style="width: 300px; height: 200px;">
            Signature:
        </td>
        <td style="width: 400px; height: 200px;">
            <textarea rows="5" style="width: 200px"></textarea>
        </td>
    </tr>
    <tr>
        <td colspan="2"  align="center">
            <input type="button" id="registerButton" name="registerButton" value="Register" disabled="disabled"/>
        </td>
    </tr>
Where the yellow highlight represents the field text, the green highlight the input, the blue the results div (where text will be displayed) and the orange, the buttons.


At this point, the basic structure on the page is created, now lets create the AJAX stuff.

First, we have to create a class that extends from AjaxCore, we may use any name we want, so we'll try with "AjaxFunctions" name for the class. 

class AjaxFunctions extends AjaxCore 

 function 
AjaxFunctions()
 { 
    parent::AjaxCore();
 }
}



this is the basic structure of the class that extends from AjaxCore, but before we run it, it needs some extra configurations, to keep config values on the same place, we create a function called "setup" and we setup all values there. ( all config values are explained on the documentation ) 

 function setup()
 {
    
$this->setCurrentFile("AjaxFunctions.class.php");
 } 

This sentence, sets the current class name, (where is stored on the disk), this is important because this is where the AJAX request will be made when an event is triggered,

The next step, is to create a PHP function that handles when the user press the button "checkButton", so here it is.

 function checkUsername()
 { 
 } 

Later we'll create the code to check if the username exists in this function, one important thing, is that always your functions remains takes no parameters, no matter if you need like in this case "an username value" from the webpage.

Now, let's put all this stuff together.
<?php

require_once("AjaxCore.class.php");  // first we include the AjaxCore class

class AjaxFunctions extends AjaxCore 

 function 
AjaxFunctions()
 {
   
$this->setup();
    
parent::AjaxCore();
 } 
 function 
setup()
 {
    
$this->setCurrentFile("AjaxFunctions.class.php");
 } 
 function 
checkUsername()
 { 
 }
}

new 
AjaxFunctions(); // do not forget this!
?>

notice that the two sentences highlighted, the first one just calls the function "setup" that we defined before. The second one, is very important and you'll usually forget to add this, so please re-check this line is at the bottom of the page, after the closing brace of the class.

Now, we go back to the register page, and add some AJAX stuff.

<?php
require_once("AjaxFunctions.class.php"); 
// include our class
$ajax=new AjaxFunctions
();
 
?>
<html>
<head>
    <title>Register page</title>
    <script type="text/javascript" src="prototype.js"></script> <!-- include stantard prototype library -->
    <script type="text/javascript" src="AjaxCore.js"></script> <!-- include AjaxCore library -->

    <?php
    
echo $ajax->getJSCode
();
    
?>
</head>

Notice, the text highlighted in green is PHP code. At the beginning of the page, we include our class and creates an instance of this class, then we call  getJSCode() function later to print some JavaScript handles that will take care of the AJAX request. Also, do not forget to include the JavaScript files highlighted with yellow, as they are needed.

The next step, is to add some "binding" code after the checkButton we defined before, there are 3 ways of binding, all of them are documented on the project's documentation page.

* bind ( does a bind between a html object and a php function, when a JavaScript event is triggered )
* bindTimer ( does a bind between a html object and a php function, when a JavaScript event is triggered and timer expires)
* bindPeriodicalTimer ( does a bind between a html object and a php function, when a JavaScript event is triggered and keeps repeating each time timer expires).

In this case, we need a simple bind between the checkButton and the checkUsername PHP function, so, if you see the documentation you'll get the signature of the method.

bind(string $id, string $event, string $bindto, [ string $params ])

and of course, this method returns the JavaScript code that does the AJAX request, so we only need to fill this function and all dirty stuff is generated. Now we place the bind, after the button.

  <?php  echo $ajax->bind("checkButton","onclick","checkUsername","username");  ?>   

where, "checkButton" is the ID of the button.
          "onclick" is the event that triggers the action.
          "checkUsername", is the PHP function that will be called.
          "username", is the field that we need to send along with the AJAX request ( if you need to send various fields, with this syntax     "field1,field2,field3" , if you need an static value, i.e. send something is not an element on the page, you'll have to attach a prefix _ on the var name, as  "field1, field2, _static1=whatever"

Now, the last thing to do is Add some code to the PHP functions that handles the request, as this function needs the "username" sended along with the binding, you'll have to retrive it with $this->request['variablename']; 

 function checkUsername()
 {
    
$user=$this->request['username']; // retrieve username sended with the bind; 
    
$code=array(); // define an array to store our JavaScript code;
    
if($user=="test"
        { 
// username exists
        
$code[]=$this->htmlDisable("registerButton"); // disable register button
        
$code[]=$this->htmlInner("resultsDiv","<font color='red'>Username already exists</font"); // sets some text on the on div "resultsDiv"
        
}
    else
        { 
// username not exists
        
$code[]=$this->htmlEnable("registerButton"); // enables register button
        
$code[]=$this->htmlInner("resultsDiv","<font color='green'>Username Ok</font");  // sets some text on the on div "resultsDiv"
        
}
    
    echo 
$this->arrayToString($code); // converts our array into a printable JavaScript string
 


notice: some of the methods of this function were added on AjaxCore 1.1.1,

now, we've created our first AJAX application.


Below both files used on this tutorial

BEGIN AjaxFunctions.php
--------------------------------------------------------------------------

<?php

require_once("AjaxCore.class.php");  // first we include the AjaxCore class
class AjaxFunctions extends AjaxCore 

 function 
AjaxFunctions()
 {
    
$this->setup();
    
parent::AjaxCore();
 } 

 function 
setup()
 {
    
$this->setCurrentFile("AjaxFunctions.class.php");
 }

 function 
checkUsername()
 {
    
$user=$this->request['username'];
    
$code=array(); // define an array to store our JavaScript code;
    
if($user=="test"
        { 
// username exists
        
$code[]=$this->htmlDisable("registerButton"); // disable register button
        
$code[]=$this->htmlInner("resultsDiv","<font color='red'>Username already exists</font");  // sets some text on the on div "resultsDiv" 
        
}
    else
        { 
// username not exists
        
$code[]=$this->htmlEnable("registerButton"); // enables register button
        
$code[]=$this->htmlInner("resultsDiv","<font color='green'>Username Ok</font");   // sets some text on the on div "resultsDiv" 
        


    echo 
$this->arrayToString($code); // converts our array into a printable JavaScript string
 
}
}
new 
AjaxFunctions(); // do not forget this!
?>

BEGIN register.php
--------------------------------------------------------------------------

<?php
require_once("AjaxFunctions.class.php"); // include our class
$ajax=new AjaxFunctions();
 
?>
<html>
<head>
    <title>Register page</title>
    <script type="text/javascript" src="prototype.js"></script> <!-- include stantard prototype library -->
    <script type="text/javascript" src="AjaxCore.js"></script> <!-- include AjaxCore library -->
    <?php
    
echo $ajax->getJSCode();
    
?>
</head>
<body>

<table border="0" style="font-size: 10pt; font-family: Verdana">
    <tr>
        <td style="width: 300px; height: 50px;">
            Username:
        </td>
        <td style="width: 400px; height: 50px;">
            <input type="text" id="username" name="username" style="width: 200px" />
            <input type="button" id="checkButton" name="checkButton" value="Check" /> 
            <?php
                
echo $ajax->bind("checkButton","onclick","checkUsername","username");
            
?>   
            <div id="resultsDiv">&nbsp;</div>
        </td>
    </tr>
    <tr>
        <td style="width: 300px; height: 50px;">
            Password:
        </td>
        <td style="width: 400px; height: 50px;">
            <input type="password" id="password" name="password" style="width: 200px" />
        </td>
    </tr>
    <tr>
        <td style="width: 300px; height: 200px;">
            Signature:
        </td>
        <td style="width: 400px; height: 200px;">
            <textarea rows="5" style="width: 200px"></textarea>
        </td>
    </tr>
    <tr>
        <td colspan="2"  align="center">
            <input type="button" id="registerButton" name="registerButton" value="Register" disabled="disabled"/>
        </td>
    </tr>
</table>
</body>
</html>


That's all, Folks!