File: docs/JS_API.txt

###############################################################################
# pAjax                                                        JavaScript API #
###############################################################################
# Created:            # Copyright® 2005, PontUKom Corp # Updated:             #
#   2005-09-21 16:02  #        Guilherme Blanco        #   2005-09-21 17:18   #
###############################################################################


NOTE: Protected and private methods were not detailed. This means that you 
should never try to use these functions directly in your pAjax Application. I
am not the responsable for script hackings, using private methods to execute 
some special behaviour.


+-----------------------------------------------------------------------------+
| Class: pAjax                                                                |
+-----------------------------------------------------------------------------+
Extensible class providing to programmers the most powerful resources available
in pAjax class. Controls requests, fire event handlers and is  responsable for 
debugging pAjax Applications.



| Constants and static variables
+------------------------------------------------------------------------------
| __debugMode__ (boolean) Stores the current Debug Mode
+------------------------------------------------------------------------------



| Private methods
+------------------------------------------------------------------------------
| None
+------------------------------------------------------------------------------




| pAjax(void)
+------------------------------------------------------------------------------
| Build a pAjax instance
+------------------------------------------------------------------------------
| Type: Constructor
| Access: public
| Return: pAjax object
+------------------------------------------------------------------------------



| pAjax.debug(string msg)
+------------------------------------------------------------------------------
| This method is responsable to display customized debug messages from pAjax
+------------------------------------------------------------------------------
| Type: Static method
| Access: public
| Return: void
| Arguments:
|    - Message to be displayed
+------------------------------------------------------------------------------



| pAjax.getDebugMode(void)
+------------------------------------------------------------------------------
| Retrieves if Debug mode is enabled or disabled
+------------------------------------------------------------------------------
| Type: Static method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------


| pAjax.enableDebugMode(void)
+------------------------------------------------------------------------------
| Enables Debug mode
+------------------------------------------------------------------------------
| Type: Static method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------


| pAjax.disableDebugMode(void)
+------------------------------------------------------------------------------
| Disables Debug mode
+------------------------------------------------------------------------------
| Type: Static method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------



| pAjax.setDebugMode(boolean mode)
+------------------------------------------------------------------------------
| Enables/Disables Debug mode
+------------------------------------------------------------------------------
| Type: Static method
| Access: public
| Return: void
| Arguments:
|    - True: enable debug mode / False: disable debug mode
+------------------------------------------------------------------------------



| prepare(string funcName, const string requestType)
+------------------------------------------------------------------------------
| Generates a request (creates a pAjaxrequest instance) to be customizable
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: pAjaxRequest object
| Arguments:
|    - Name of the function or method to be called
|    - Constant setting request method (pAjaxRequest.GET or pAjaxRequest.POST)
+------------------------------------------------------------------------------



| getRequest(void)
+------------------------------------------------------------------------------
| Retrieves the pAjaxRequest object generated by prepare method
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: pAjaxRequest object
+------------------------------------------------------------------------------


| getReadyState(void)
+------------------------------------------------------------------------------
| Get the readyState of the request. Vary from 0 (not initialized) to 4 (done)
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: integer
+------------------------------------------------------------------------------



| getResponse(void)
+------------------------------------------------------------------------------
| Get the response of a request (structured data)
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: mixed
+------------------------------------------------------------------------------



| getXML(void)
+------------------------------------------------------------------------------
| Get the XML generated by request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------



| getText(void)
+------------------------------------------------------------------------------
| Get the Text generated by request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------



| getData(void) - depreciated
+------------------------------------------------------------------------------
| Get the response of a request (structured data)
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: mixed
+------------------------------------------------------------------------------



| toString(void)
+------------------------------------------------------------------------------
| Serializes the pAjax object into a string
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------






+-----------------------------------------------------------------------------+
| Class: pAjaxRequest                                                         |
+-----------------------------------------------------------------------------+
Effectively control the request. This class is reponsable for the request 
generation, compilation, execution, parameters and error checking.



| Constants and static variables
+------------------------------------------------------------------------------
| GET   (string)  Constant to prepare a GET request
| POST  (string)  Constant to prepare a POST request
| SYNC  (boolean) Constant to execute a request in Synchronous way
| ASYNC (boolean) Constant to execute a request in Assynchronous way
+------------------------------------------------------------------------------



| Private methods
+------------------------------------------------------------------------------
| __exec__
| __compileXML__
| __compileURI__
| __onreadystatechange
| __dispose__
| __setFunctionName__
+------------------------------------------------------------------------------



| pAjaxRequest(pAjax obj, string funcName, const string requestType)
+------------------------------------------------------------------------------
| Build a pAjaxRequest instance (should never be created manually. Please check
| the method of pAjax object, prepare).
+------------------------------------------------------------------------------
| Type: Constructor
| Access: public
| Return: pAjaxRequest object
| Arguments:
|    - pAjax object
|    - Name of the function or method to be called
|    - Constant setting request method (pAjaxRequest.GET or pAjaxRequest.POST)
+------------------------------------------------------------------------------



| abort(void)
+------------------------------------------------------------------------------
| Abort a request, if it is being executed
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
+------------------------------------------------------------------------------



| execute(const boolean syncType)
+------------------------------------------------------------------------------
| Execute a request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - Synchronism type (pAjaxRequest.SYNC or pAjaxRequest.ASYNC)
+------------------------------------------------------------------------------



| async(void)
+------------------------------------------------------------------------------
| Assynchronous request call execution
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
+------------------------------------------------------------------------------



| sync(void)
+------------------------------------------------------------------------------
| Synchronous request call execution
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
+------------------------------------------------------------------------------



| setParam(string name, mixed value)
+------------------------------------------------------------------------------
| Add a new parameter to request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - Name of the parameter (the same that can be accessed in PHP code)
|    - Any data to be sent
+------------------------------------------------------------------------------



| getParam(string name)
+------------------------------------------------------------------------------
| Get a request parameter
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: mixed
| Arguments:
|    - Name of the parameter in the request
+------------------------------------------------------------------------------



| delParam(string name)
+------------------------------------------------------------------------------
| Remove a request parameter
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - Name of the parameter to be removed
+------------------------------------------------------------------------------



| errorOccurred(void)
+------------------------------------------------------------------------------
| Checks if a request calls generated an error or not
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------



| getReadyState(void)
+------------------------------------------------------------------------------
| Get the readyState of the request. Vary from 0 (not initialized) to 4 (done)
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: integer
+------------------------------------------------------------------------------



| getResponse(void)
+------------------------------------------------------------------------------
| Get the response of a request (structured data)
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: mixed
+------------------------------------------------------------------------------



| getXML(void)
+------------------------------------------------------------------------------
| Get the XML generated by request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------



| getText(void)
+------------------------------------------------------------------------------
| Get the Text generated by request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------



| getXmlHttp(void)
+------------------------------------------------------------------------------
| Get the XMLHttpRequest object generated by pAjaxRequest
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: object
+------------------------------------------------------------------------------



| getLoaded(void)
+------------------------------------------------------------------------------
| Checks if request call is loaded or not
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------



| getLoading(void)
+------------------------------------------------------------------------------
| Checks if request call is loading
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: boolean
+------------------------------------------------------------------------------



| setRequestType(const string requestType)
+------------------------------------------------------------------------------
| Modify request type
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - Constant setting request method (pAjaxRequest.GET or pAjaxRequest.POST)
+------------------------------------------------------------------------------



| getRequestType(void)
+------------------------------------------------------------------------------
| Get request type
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: const string
+------------------------------------------------------------------------------



| setURI(string URI)
+------------------------------------------------------------------------------
| Modify URI to execute the request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - Document URI
+------------------------------------------------------------------------------



| getURI(void)
+------------------------------------------------------------------------------
| Get document URI of request
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: string
+------------------------------------------------------------------------------



| setUsername(string username)
+------------------------------------------------------------------------------
| Set up a Username for a restricted document URI
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - URI Username
+------------------------------------------------------------------------------



| setPassword(string password)
+------------------------------------------------------------------------------
| Set up a Password for a restricted document URI
+------------------------------------------------------------------------------
| Type: Instance method
| Access: public
| Return: void
| Arguments:
|    - URI Password
+------------------------------------------------------------------------------






+-----------------------------------------------------------------------------+
| Function: pAjaxCall                                                         |
+-----------------------------------------------------------------------------+
Inline request call execution, recommended to non JS OOP programmers. Executes
a request and its return is executed via callback function.



| pAjaxCall(string URI = null, string funcName [, mixed arg [, ...]], callback)
+------------------------------------------------------------------------------
| Creates a call, executes it and execute a callback function when a response 
| is returned. Callback function must have an argument (data returned). If URI
| is set to null, the current document will be called. Unlimited arguments can
| be set as function arguments.
+------------------------------------------------------------------------------
| Type: Function
| Access: public
| Return: void
| Arguments:
|    - URI (optional. default: current document location)
|    - Name of the function or method to be called on server
|    - Argument (optional)
|    - ...
|    - Callback function (recieves an argument, the response of request)
+------------------------------------------------------------------------------






+-----------------------------------------------------------------------------+
| Class: pAjaxParser                                                          |
+-----------------------------------------------------------------------------+
Internal class to handle XML generation and XML Processment. Never use this
class in your pAjax Application. I'm not responsable for strange behaviours if
you try to use it. Details about this class will not be given.