This guide
This is the main guide to start using and understanding AjaxIto. I wrote it to complement the "examples.php" file that has some useful demonstrations of how to use the class, all the code in that files is commented. So with this two files I think you won't have any problem using AjaxIto.
What is AjaxIto?
AjaxIto is a class written in php that makes it easy to integrate AJAX in a PHP application. It works with PHP versions >= 4.
With AjaxIto it is easy to call php functions via JavaScript, and refresh content and styles without reloading the page.
Why should you need AjaxIto?
If you want to refresh some parts of the page without reloading it. That includes the styles and content of all the objects that participate in the page.
How does AjaxIto work?
When you want some data be processed by your server or you just want to change a color of a part of your page (without reloading it), you call the AjaxIto JavaScript function. And there you define wich PHP method will take care of the request. Then, in that method, you do your work (access a database, write a file, create an image, use a webservice, etc.) and then setup the response (just two kind of responses are posible) via Ajaxito functions (ok, this may sound complicated, but you just need to see any basic example to understand how simple is).
So:
- You call the Ajaxito JavaScript function, this function sends the variables in the background to the "process script" (that is the same file where you instantied Ajaxito class (that's why is so important to create the object before any headers are sent to the client).
- The method of the selected class is executed and there are defined the responses
- The response is automatically parsed and the corresponding objects properties of the page are updated.
Simple step by step guide to start using AjaxIto
- Create a class that inherits from AjaxItoResPro (don't forget to include AjaxItoResPro.class.php file)
- The methods of that class will be the ones that can be called from using AJAX. So if your methods needs arguments define it with one argument. By this argument will be passed an array that contains all the variables passed during the JavaScript call. Also in that method you need a way to indicate the response so there are two methods that are inherited from the parent class that you need to know:
- The first is: addDOMProperty, with this method you will be able to change any style property of an object of the page, for example if you call: $this->addDOMProperty('colorDiv','color','#FF0000');, the response of this method will cause that the object identified by "colorDiv" will change it's text color to "#FF0000" (red). So you can set as many as this properties as you want, and you can set any style (just like you define them in your css sheet). So the three parameters are: the id of the html object, the name of the property to set, and the new value.
- The second is needed when you need to execute some JavaScript defined "on the fly" in the server. It's name is: addJavaScriptCode. It needs only one parameter that is the JavaScript code, for example: $this->addJavaScriptCode("alert('Hello World!');");, so, the response of this method will cause an alert message saying "Hello World!".
- In the page that you want tou use AJAX, create an AjaxIto object (just the first argument is needed that is the name of te instance that will be used to identificate the JS functions). It's very important to create the object before any headers are sent to the client (be careful with the blank lines)
- Then ask the object to insert all the javascript needed by calling the getJs() function.
- Also ask to insert what will be "loading message" by calling the getLoaderHTML() function. (you can pass by arguemnt your own styles to this message, it's just a div containing a word that is sepcified in every AJAX call, and appears while waiting for the server answer)
- Then you are ready to make the call... just do it like any JavaScript function, for example in the onClick Event: onClick="testing_doPHP('ExampleControllerClass','changeColor','red','Changing...');"
Note:
- The name of the JavaScript function is nameOfAjaxitoObject_doPHP(the name defined in step 3), in this case: testing_doPHP
- The first argument is the name of the class defined in the first step
- The second argument is the name of a method of that class
- The third agument is a string in an XML like format that defines the variables that will be passed (in an array) to the method. The format of this string is :<vars><var0><value>red</value></var0></vars>, where you can sepecify all the variables you need just adding <var1><value>value_of_the_variable_one</value></var1> before closing the <vars> node. You can also use the CDATA XML (Unparsed Character Data) node if you need to pass illegal characters like "<" and "&".
License
AjaxIto is Open Source under the BSD License (http://www.opensource.org/licenses/bsd-license.php). The text of the license could be found at the beginning of the code.
AjaxIto. By Javier Rubacha. Web: http://www.jabox.com.ar/ajaxito