File: docs/Migration_Doc_10_to_15.txt

###############################################################################
# pAjax                            MIGRATION DOCUMENT FROM VERSION 1.0 TO 1.5 #
###############################################################################
# Created:            # Copyright® 2005, PontUKom Corp # Updated:             #
#   2005-09-13 15:05  #        Guilherme Blanco        #   2005-09-13 15:45   #
###############################################################################

This document intents to describe the modifications necessaries to update pAjax
script from version 1.0 to version 1.5.
Since the whole class has been updated, with a lot of improvements and exciting
features, such as parser, real XML usage, etc, some modifications are necessary
to make your code running in the new version.

Please notice that class update is highly recommendable, since there're found
some critical bugs. I recommend all programmers that use pAjax to update yours
scripts to this new version.

The migration is simple, and probably don't take more than 10 minutes to be 
done. In this document, I explain how to update 1.0 scripts to 1.5 script with 
domain protection enabled (default protection mode). There are another 
protection mode that can run together with domain, but this document will not 
explain how to implement this feature.
If you are interested in adding this protection, read the API docs.


The migration can be spitted in simple steps, and try following all of them:


Step 1: Updating REQUIRE Libraries
Step 2: Changing Object Class Names
Step 3: showJavaScript() method
Step 4: handleRequest() method
Step 5: pAjaxRequest object
Step 6: pAjaxRequest.SYNC/ASYNC constants
Step 7: getResponse() method
Step 8: Other changes
Conclusion



+-----------------------------------------------------------------------------+
| Step 1: Updating REQUIRE Libraries                                          |
+-----------------------------------------------------------------------------+
There are no more pObjectFromAJAX PHP class. This step is simple and you can 
remove the like "require_once 'class.pObjectFromAJAX.php'" line.
The library pAJAX is now called as pAjax. Please change you scripts. You can do
it changing: require_once "class.pAJAX.php" to require_once "class.pAjax.php".


+-----------------------------------------------------------------------------+
| Step 2: Changing Object Class Names                                         |
+-----------------------------------------------------------------------------+
Since pAJAX name has been changed to pAjax, the PHP class and the JS class have
also to be updated too. In this step you change all pAJAX calls to pAjax, and
all pAJAXrequest to pAjaxRequest.


+-----------------------------------------------------------------------------+
| Step 3: showJavaScript() method                                             |
+-----------------------------------------------------------------------------+
This method has been changed, due some requests. Now, instead of write the JS
content directly in the document, it loads some files. Also, to allow path 
location, this method accepts one argument [optional. Default is current dir]
that points to the path where the JS files are located.
So, you have to update your call from this:


<script type="text/javascript">
  <?php $ajax->showJavaScript(); ?>
  ...
</script>


To this:


<?php $ajax->showJavaScript("../js"); ?>
<script type="text/javascript">
  ...
</script>


+-----------------------------------------------------------------------------+
| Step 4: handleRequest() method                                              |
+-----------------------------------------------------------------------------+
Probably most of this class users will not need to change this method, but for
those that uses non-UTF8 characters, this is necessary.
handleRequest method now takes one argument [optional. Default is UTF-8] that
points to charset to be used. If your language is supported by UTF-8, no change
is needed.


+-----------------------------------------------------------------------------+
| Step 5: pAjaxRequest object                                                 |
+-----------------------------------------------------------------------------+
When preparing a call, the second argument is the method to be used. In version
1.0, you use "GET" or pAJAXRequest.GET. In version 1.5, only pAjaxRequest.GET
is acceptable. Please take a look at the change (pAJAXRequest to pAjaxRequest).


+-----------------------------------------------------------------------------+
| Step 6: pAjaxRequest.SYNC/ASYNC constants                                   |
+-----------------------------------------------------------------------------+
In older versions (< 1.5), when executing a method call (via request method 
execute), you use the depreciate constants (pAJAX.ASSYNC and pAJAX.SYNC). Since
this is related to pAjaxRequest, these constants have been changed to 
pAjaxRequest Object. ASSYNC constant has been changed to ASYNC. So, the 
necessary changes to be done are:

pAJAX.ASSYNC should be changed to pAjaxRequest.ASYNC
pAJAX.SYNC should be changed to pAjaxRequest.SYNC


+-----------------------------------------------------------------------------+
| Step 7: getResponse() method                                                |
+-----------------------------------------------------------------------------+
Until version 1.0, getData was the responsable for data retrieving. In version
1.5, getResponse is the responsable for doing this job. getData method has been
depreciated, but it still supported in version 1.5, but it's highly recommended
to change the call, because version 1.6 will not have getData anymore.


+-----------------------------------------------------------------------------+
| Step 8: Other changes                                                       |
+-----------------------------------------------------------------------------+
These changes are documented is you hacked pAjax script for your own usage.
Some constants were defined in global scope, and could be changed via inline 
JavaScript. They are: pAJAX.requestType and pAJAX.debugMode.
If you use any of this properties, you need to change how it's called.

debugMode constant is depreciate, but 3 new methods are available. They are:
- setDebugMode
- enableDebugMode
- disableDebugMode

From version 1.5.1+, PHP does not control the debug mode anymore. Instead, JS
code have been updated to support debug mode control via JavaScript, providing
more powerful handler to programmer.

requestType constant, that holds the type of request (GET/POST) is depreciate.
There are no other equivalent available in version 1.5, since this constant is
depreciate.


+-----------------------------------------------------------------------------+
| Conclusion                                                                  |
+-----------------------------------------------------------------------------+
Also, there's a major change in version 1.5 from version 1.0. If you tryed the
old test2.php script (version 1.0) with a special char, you experienced an
unlikely htmlentities conversion. Version 1.5 does not have this problem, and
this could be reached via real XML usage in sending/recieveing data.
So, update your script if you treat the htmlentities conversion in your appz.

Reaching this point of the migration kit, your application should be working ok 
in version 1.5 now. Try executing it. If it doesn't work, report me the source
with a description.

Only if I have some feedback I can improve this class. So, send me suggestions!