Basic Tutorial : using the API

Assyncronous Javascript and XML (AJAX)

Specification and Diagram

Client (PHP / TPL / HTML) The html/php page or tpl template includes the file connector.js and it redirects to Connector Object the request, with parameters (GET/POST method). The html/php page or tpl template receives from Connector object the response of the request, inside its return function. This response has string or object format.

Connector Object (JS) The Connector object receives from the return of the Controller, inside its return method (handler), it unserialize the result and it redirects to client. The Connector Object receives from request with its parameters, and it redirects to main Controller, using AJAX .

The main Controller receives from return of the executed method, the result. This result is serialized and redirected to Connector Object. Controller (PHP)

The main Controller receives from Connector Object the request and it instanciates the required object.

After the execution of the requested method, the result will be returned to main Controller. This result has string or object format.

The object created from the client request executes the required method with parameters (if required). module.class.method
and parameters (PHP class)

Basic Implementation (Example)

Client (HTML, PHP or TPL) using cExecute command:

<html>

<body>

<input type="button" onclick="javascript:f_example()">

</body>

</html>

<script src="js/connector.js" type="text/javascript"></script>

<script language="JavaScript" type="text/javascript">

//	some function

function f_example(){

//	internal function to receive the response of the request

var handler = function (responseText){

//	The response it can be an Object or string.

data = responseText;

}

//	Executes the public function of the Connector object. This object already was created inside of //	the js file included.

//	Parameters:

//	String arg => “module.class.method” + “&param1=valor1&param2=valor2...”

//	function handler => internal function created to receive the response. It must have an

//	argument in the signature of the method.

//	1. Using GET method:

var args = “module.class.method&param1=value1&param2=value2”;

cExecute (args, handler);

//	String params => “param1=value1&param2=value2”.

//	2. Using POST method:

args = “module.class.method”;

var params = “param1=valor1&param2=valor2”;

cExecute (args, handler, params);

}

</script>

Tip1: To execute the command cExecute, you can use the sintax “$this.class.method” instead of “module.class.method”, when the class method is inside the same module.

2.2. Client (HTML, PHP or TPL) using cExecuteForm command

The command cExecuteForm must been used when it send a form to a PHP class and	that it contains upload files (enctype=“multipart/form-data”). This command uses AJAX only	to receive the return value. The data form are submitted, using simple POST method, to another	url.

<html>

<body>

<form name="form1" method="post" enctype="multipart/form-data">

<input type="text" name="to">

<input type="file" name="file">

</form>

<input type="button" onclick="javascript:f_send()">

</body>

</html>

<script src="js/connector.js" type="text/javascript"></script>

<script language="JavaScript" type="text/javascript">

//	some function

function f_send(){

//	internal function to receive the response of the request

var handler = function (responseText){

//	The response it can be an Object or string.

data = responseText;

}

//	Executes the public function of the Connector object. This object already was created inside of //	the js file included.

//	Parameters:

//	String arg => “module.class.method” + “&param1=valor1&param2=valor2...”

//	HTMLElement document.form=> form created in the document.

args = “module.class.method”;

cExecuteForm (args, document.form1, handler);

}

</script>

Tip2: To execute the command cExecuteForm, you can use the sintax “$this.class.method” instead of “module.class.method”, when the class method is inside the same module.

2.3. Server (PHP Class example)

<?php

class User{

function get_user_id(){

// return result (string).

return $_SESSION['userid'];

}

function verify_user($params){

// return result (Object).

return $params;

}

}

?>

2.4.The structure of the directory (files)

The structure of the directory follows the same pattern used by eGroupWare Project.

+ module

inc

/ class.functions.inc.php	// Class has common functions and utilities.

js

/ connector.js	// Connector inside the /js

templates

controller.php	// Controller inside the root module

Tip 1: How to use objects of the eGroupware Project

In case that it wants to use objects contained in the session of the user (objects created by eGroupware), inside of classes and using AJAX, it includes the following lines in the client page (PHP). It also verifies if the the variable session.auto_start = 1 in php.ini config file.

// in case that still it has not been included for the application.

$GLOBALS['phpgw_info']['flags'] = array(

'noheader' => True,

'nonavbar' => True,

'currentapp' => 'appName',

'enable_nextmatchs_class' => True

);

include('../header.inc.php');

// populate data inside array $_SESSION

$_SESSION['phpgw_info']['expressomail']['user'] = $GLOBALS['phpgw_info']['user'];

Tip 2: Loading javascript files (*.js) automatically

If you want to load one or more js files, just it copies them to js folder of the

module, and it includes the following lines in the client page (PHP):

// Include JS Files

$obj = createobject("module.functions");

echo $obj -> getFilesJs();

Ex.:

+ module

js

/ file_1.js

/ file_2.js

...

/ file_n.js

Author: Nilton Emílio Bührer Neto (niltonneto@celepar.pr.gov.br)	Date: June / 01 / 2005

Important: All the words “module”, contained in this tutorial, they must be substituted by the name of the directory of the application.

2005-06-21T09:14:24