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"> </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"> </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!