File: docs/Basic_Tutorial.txt

###############################################################################
# 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.