My favorites | Sign in
Project Logo
Project Home
  
Downloads
  
Wiki
  
Issues
  
Source
    
Search
for
Updated Apr 20, 2009 by kristianoye
Labels: Featured, Phase-Implementation
APIsajax014  
API Reference for SAjax 0.14 (PHP)

Introduction

This document pertains to the object-oriented version of the SAjax 0.14 library. It is assumed that the target audience is already familiar with the SAjax 0.12 API and that will not be discussed in this document.

Reference

Within PHP

While the SAjax 0.12 API is still exposed and fully-functional, the implementation has all been moved within a new class called 'Sajax'. The Sajax class can only be accessed through a call to Sajax::Sajax(), which returns the singleton instance of the Sajax object. If you are using this alternative library, it is recommended that all SAjax API calls are made through this interface.
This method will add an additional message that will be included in the response from the server if debugging is turned on. The debugging information will be conveyed as JavaScript comment blocks in the alert window that pops up on your client. Example: 
   Sajax::Sajax()->AddDebugMessage("Attempting to connect to database.");
This takes as a parameter a block of JavaScript represented within a PHP string. The block is then output to the client when ExportBlockJS() is called or when ExportIncludeJS() is called if you prefer that method instead.
The AddScriptReference methods allows you to include additional, external JavaScript libraries to your document when ExportIncludeJS() is called. This is useful if you wish to keep your JavaScript implementation in a seperate file. Example: 
   Sajax::Sajax()->AddScriptReference('/static/js/blog.js');
Legacy: Included for backwards compatibility with 0.12
If set to true, then debugging is turned on. Each SAjax call results in a series of alert() popups to detail the communication between the client and the server. Example: 
   Sajax::Sajax()->EnableDebug(true);
If set to true Sajax will export JavaScript methods with the 'x' like Sajax 0.12. This is off by default. Note: If you call any of the Sajax 0.12 API functions, this will be automatically enabled.
Exports one or more PHP functions to the JavaScript-enabled client. Many difference types of callback expressions may be used, including:
'MethodName' - Exports a single PHP function.
'ClassName::MethodName' - Exports a single PHP object methood.
array($classObj, $methodName) - Exports a single PHP object callback.
$classObj - Exports all methods in object that use the 'Sajax' method prefix.
Example: 
  Sajax::Sajax()->Export(
  //  Exports all object methods with 'Sajax' prefix in name
  //  Also exports any method names returned by $myObject->GetSajaxExportList()
    $myObject,


  //  Exports the AddNumbers method in class Services
    'Services::AddNumbers',

  //  Exports a standalone PHP method
    'GetRandom');
These methods are then available to the client as either 1) JavaScript objects, or 2) JavaScript 'x' functions (if EnableLegacyJS is enabled).
The ExportMapped() method is very similar to Export() but that it differs in that it allows you to map a different URI to the service the requests. This is helpful if you want to scale your implementation across multiple PHP files or even multiple servers!
Example: 
  Sajax::Sajax()->ExportMapped(
  // These Ajax calls are brokered by a script called 'dispatch.php',
    '/services/dispatch.php',
    $myServices,
  Sajax::Sajax()->ExportMapped(
  // These Ajax calls are brokered by a different server entirely
    'http://chatserver.null.org',
    $myChatObject);
ExportBlockJS() renders all of the JavaScript required by the client in order to make successful Ajax calls. This is analogous to sajax_show_javascript. The optional boolean flag indicates whether you want the API to render the opening and closing 
<script>
tags for you (defaults to false).
ExportIncludeJS() renders HTML script tags to be included in your document header. The only script tag rendered by default is the one needed by clients in order to make successful Ajax calls. By default, the URI defaults to that of the current document but with an additional parameter attached (gcs=true). This tells the API to return only the JavaScript needed in a document with Content-Type of text/javascript. Example:
/foo.php: 
  Sajax::Sajax()->ExportIncludeJS()
This renders the following tag in the output of foo.php: 
  <script type="text/javascript" src="/foo.php?gcs=true"></script>
Then, when the document is loaded the client also requests /foo.php?gcs=true and this in turn renders the JavaScript required for successful Ajax calls (without cluttering your original document).
GetAllStubJS() is primarily for legacy support. It renders the legacy JavaScript used by clients for calling Ajax methods. WARNING: This method sends the rendered script directly to the client.
GetClientJS() returns the string of JavaScript code that allows a client to make successful Ajax calls. This includes the base Ajax call handling and all of the exported methods.
GetClientScriptURI() returns the default URI that clients use in order to request the JavaScript code used for issuing Ajax requests. This defaults to the current script, but can be explicitly set using SetScriptURI(). This is useful if you would prefer to provide a static copy of the JavaScript needed by your site (could cut out a bit of CPU).
Legacy: Returns a string containing all of the JavaScript required by the 0.12 legacy API.
Legacy: This method returns a string containing the JavaScript required for a single legacy-style JavaScript function stub.
Returns the default URI for servicing Ajax requests from within Sajax. This can be overridden with SetRemoteURI(). You may also use multiple URIs by using ExportMapped().
Returns a mapping of all exported methods, grouped by object namespace, along with the method names, legacy method names, service URI, and service name. 
$mappings['objectname'] = array(
   array(
      'function' => 'fname', 
      'legacy' => '_objectname__fname',
      'service' => 'objectname::fname',
      'uri' => '/serviceDispatch.php'));
HandleRequest() is the main dispatch method for handling Ajax calls and must be called somewhere in your code in order to make anything work at all. Ideally, this is called somewhere at the top of your code as it will ensure that 1) no extraneous output is returned to the client prior to the call, and 2) cuts down on wasted CPU cycles on the server by performing the bare minimum amount of work to make a successful method call.
Legacy: There is no side-effect to calling this method. It is called automatically by the singleton constructor and there is no need for you to have to call it.
SetRemoteURI() allows you to specify an alternate URI for servicing Ajax calls. This may be useful if you prefer to have a specialized script for handling your Ajax requests.
Example: 
   Sajax::Sajax()->SetRemoteURI('/services/broker.php');
SAjax defaults to using 'GET' as the HTTP method to service requests, but you can override this using SetRequestType(). Currently, SAjax supports GET and POST.
Example: 
  Sajax::Sajax()->SetRequestType('POST');
Overrides the URI of the JavaScript file required by the client to perform API calls.
Example: 
  Sajax::Sajax()->SetScriptURI('/static/js/services.js');

Within JavaScript

Sign in to add a comment
Hosted by Google Code