PHP Classes

File: docs/Basic_Tutorial.txt

Recommend this page to a friend!
  Classes of Guilherme Blanco  >  pAjax  >  docs/Basic_Tutorial.txt  >  Download  
File: docs/Basic_Tutorial.txt
Role: Documentation
Content type: text/plain
Description: Basic Usage of pAjax
Class: pAjax
Do RPC calls from the browser without page reloads
Author: By
Last change: Updated content
Date: 17 years ago
Size: 12,904 bytes
 

Contents

Class file image Download
############################################################################### # pAjax BASIC TUTORIAL # ############################################################################### # Created: # CopyrightŪ 2005, PontUKom Corp # Updated: # # 2005-08-16 17:44 # Guilherme Blanco # 2005-09-22 11:57 # ############################################################################### It's with great satisfaction that I start this tutorial about the new version of my RPC (Remote Procedure Calls) class. The name of this class is pAjax, following the same rule of pTree and pConfig. The usage is very intuitive, and I think you won't have too many troubles to use it. Some changes have been applyed to simplify its usage, and also a parser has been created to help programmers to identify errors while sending or recieving data. To reach the maximum power of this tutorial, I recommend that the readers have knowledge in Object Oritented Programming in JavaScript. I did my part and I wrote a simple tutorial explaining how to create OO in JS. Please read that document before continuing reading this one. The whole system is build under OO Paradigm. To simplify usage, pAjax JS class is extensible and should be the base class if you want to build your JS code fully Object Oriented. Also, inline calls are available, by the function pAjaxCall. This document will explain how to use it. If you are a 1.0 user, I recommend you to read the migration kit; but if you want to continue the reading of this tutorial, you'll learn the new features in a detailed description instead of simple conversions. +-----------------------------------------------------------------------------+ | Browser Compatibility | +-----------------------------------------------------------------------------+ | Compatibility Table +------------------------------------------------------------------------------ +------------------------------------------------------+-------------+--------+ | Browser Name | Works? | Tested | +------------------------------------------------------+-------------+--------+ | Internet Explorer 5 MAC | No | No | | Internet Explorer 5 | No | No | | Internet Explorer 5.5 | Should work | No | | Internet Explorer 6 | Yes | Yes | | Internet Explorer 6 SP1 | Yes | Yes | | Internet Explorer 7 Beta1 | Yes | No | +------------------------------------------------------+-------------+--------+ | Mozilla Firefox 1.0+ | Yes | Yes | | Mozilla 0.9+ < 1.0 | Should work | No | +------------------------------------------------------+-------------+--------+ | Opera 7 | No | No | | Opera 8 | Should work | No | +------------------------------------------------------+-------------+--------+ | Netscape 7 | Should work | No | | Netscape 8 | Should work | No | +------------------------------------------------------+-------------+--------+ | Safari | Should work | No | +------------------------------------------------------+-------------+--------+ | Notes +------------------------------------------------------------------------------ - Internet Explorer 5 doesn't have the ActiveX component XmlHttp implemented - Opera 7 doesn't have the XmlHttpRequest component implemented I've been thinking to support IE 5 and Opera 7 users. Altho, hidden IFRAME technique is the only approach that I can imagine. Maybe version 2.0 will have this feature implemented. Suggestions are appreciated, feel free to contact me! This is not the right place to write it, but I still plan to help people that creates AJAX based applications to solve the Bookmark issue. If you don't know, with AJAX you loose the control of browser buttons Forward and Back, also to store the right page of the selected information. The user cannot send the URL to a friend, for example, because it'll point to the main page, not to the selected information. The real solution to this issue is system dependant, but I'm studying a lot to find a generic way to solve it. I really appreciate if you could point me to any information about how people solved in their application. Grabbing interesting ideas, I could make a solution without too much effort. +-----------------------------------------------------------------------------+ | Object Oriented JS pAjax Usage | +-----------------------------------------------------------------------------+ One of the most exciting features available in pAjax JavaScript object are the events. Currently, pAjax supports 4 events, as you can see in example 3. They're: onInit, onCreate, onChange and onLoad. onInit - event fired when the pAjax object or a derived class is created onCreate - event fired when the object XmlHttpRequest (Ok, ActiveXObject on IE) is created. Commom used to create a Loading box (or bar) notifying the user to wait from server response. onChange - function executed at each change of readyState property in the XmlHttpRequest object onLoad - event dispatched when the required action returned desirable data. Call themethod getResponse() to retrieve content from server. The returned data is created in the same structure as the server returns, so, if you the function execution returns an array, the getResponse will return an array. If it returns an object, the method will return an object, and so on. | Structure to send data to server +------------------------------------------------------------------------------ The system use calls to send data to server. A call is a script execution that allows parameters to be set. Currently, the call can be a function or a class method execution. If you want to call a method, define the name of the global variable in PHP, followed by a dot and the name of properties that are sub-objects and so on, until you reach the desirable method. One of the major interesting feature in the version 1.5 is that there are no level limit of objects (ie: obj.subObj.anotherSubObj.methodCall is acceptable if the properties and the method are set to public). There're three limitations in this part yet. I plan to support them in the next versions. One of them is the factory methods calls. This limitation disables the ability to use private members and use the get methods. For example: obj.getSubObj().anotherPublicSubObj.execMethod <<< do not allowed yet The second limitation breaks the concept of this script. For every request, you should point to a function/method. Imagine that I have an inline script, with no functions defined and I want to get the data returned by this script. But there're no function to call! So, the limitation is that no inline script calls are supported. There are some application that this is recommended, like a RSS generator. I plan to support inline script calls in version 1.6. The last limitation is static methods. You can't call a static method from JS. For now, you can't call, for example: Class::SomeMethod This limitation will be fixed soon. I plan to allow this usage in version 1.6. | Sending data to server +------------------------------------------------------------------------------ To create a call, the prepare method is provided. It takes two arguments: - The function name/object path + method name - Send method (GET or POST) Example: var oRequest = this.prepare("multiply", pAjaxRequest.POST); Take a look at example "multiplier.php". As you can see, multiply is the name of the function to be called and POST is the request send method. To define arguments, use the pAjaxRequest object command called setParam. This takes 2 arguments, the first one is the name of the variable and the second is its value. So: oRequest.setParam("value1", x); oRequest.setParam("value2", y); I need to remind you that the values sent will be function arguments, and will mantain the definition order. So, the function multiply will recieve as its arguments: $x = content of JS call setParam("value1", ...) $y = content of JS call setParam("value2", ...) The body of the multiply function: function multiply($x, $y) { return $x * $y; } The systems works perfectly in this way, even with some suggestions to remove the obligation to define the argument name in the method setParam. Defined all requisites, the execute method of pAjaxRequest sends the data: oRequest.execute(); At each event, its correspondent method will be called. By this way, when data is recieved, the method onLoad will be dispatched. In this method, exists a data capture, retrieved trough getResponse() method: _p.onLoad = function () { document.getElementById("z").value = this.getResponse(); } NOTE: Remember that the class use case-sensitive calls, and then onload is different from onLoad. To handle the request sent to server, a PHP Class called pAjax is available. It provides some function to generate JS Code, handle the request and add security in your pAjax Application. For example, to generate the JS Code in your Application to allow pAjax JS creation, simply call the static pAjax method called showJavaScript, which supports an optional parameter that refers to the directory path of JS files. <?php pAjax::showJavaScript("../js/pajax"); ?> This example tells to call the JS files from the parent directory (current directory is the same of the current file is located. So, if this code was written in server/www/test.php file, the path to JS files should be: server/js/pajax Handle requests is really simple. All you have to do is create a pAjax instance in the handler document and add the handleRequest method (which supports an optional parameter refering to charset to be used in data transmission. Default charset is UTF-8). Look: <?php require_once "class.pAjax.php"; $AJAX = new pAjax(); $AJAX->handleRequest("ISO-8859-1"); // For UTF-8: $AJAX->handleRequest(); ?> Please notice that handleRequest method should be the last PHP thing in your document, but before any document char be written (because it uses headers). So, something like this will not work: <html> <?php $AJAX = new pAjax(); $AJAX->handleRequest(); ?> Also, if you define the handleRequest as the first thing in your document (before all requires and definitions), the pAjax can not know defined classes or functions on document. Everything you want to be handles should stay BEFORE the handleRequest call, otherwise you probably will recieve an error with something like "Function/Method does not exist or it is not declared on page". +-----------------------------------------------------------------------------+ | Inline JS pAjax Usage | +-----------------------------------------------------------------------------+ Starting in version 1.5, pAjax allows programmers to make inline pAjax calls. I recieved a lot of request to implement this feature, and I think this will solve all doubts while using JS OO for non-JS OO programmers. When using this method, you'll have a lot of restrictions. Some of them are the events. There're no more event handlers. Instead, you have a callback function that is similar to onLoad (available in JS OO usage). Other restrictions are data retrieving. You can't retrieve data like OO usage. But, fortunately, the callback function recieves an argument that is the content of method getResponse(). Try looking at example inline_call2.php. This is a simple usage of inline call feature. pAjaxCall takes at least 3 arguments. - URI: if set as null, the current location will be used - Function/Method name - Callback function If you define more than 3 arguments, they'll be treated as arguments to be sent to server (the equivalent of setParam functions). Please don't forget the argument defined in callback function. This is the content of getResponse that is sent to the function as an argument.