AJSHP Project :: DOCUMENTATION

server-side

Gateway.class.php file is the core of this application but you don't need to modify the class, you need (or should) modify its internal $options variable to customize your interaction.

debug [ boolean, option: true/false - default: false ],
usefull to know what's happening during client/server interaction.
This variable is false by default and if you choose to enable debug, you need a subfolder called debug inside your Gateway.class.php folder writable and readable (CHMOD 777) .
Remember that if you enable this feature debug folder will have a lot of .html files, then is recommended to switch debug off in a multple users application or in a distribution.
compression [ boolean, option: true/false - default: false ],
is necessary when you recieve a lot of informations from the server or when you need the best performances for your AJSHP interaction.
This feature requires zlib extension enabled because use gz_compression for a smallest text lenght on server side.
Remember that if you have a progress listener it will not work correctly because read content-length is overwrote by ob_gzhandler.
accelerator [ boolean, option: true/false - default: false ],
is required if you want to minimize server operations then to make interaction faster.
When you choose a service from javascript, you need to specify the class name that you want to use from client. Usually, in php, classes are called in this way:
ClassName.class.php
For example, if you want to use a class called DatabaseManager it should be saved as DatabaseManager.class.php but if you have a different way to save your classes the Gateway have to read all files inside class folder and requires each file found to have all declared classes. This means that every file has to be parsed from server and problems with internal dedicated requires should be much more than accelerated way.
For example, if you have a file with a class that need file2 to work correctly but there is another file that need file2 too and you have not used require_once function inside theese 2 files, there will be problems while searching required class.
That's why I suggest to use true value for this option, calling classes files with regular names as MyClass.class.php is.
classfolder [ string, default: './' ],
is used from Gateway class to know where are other class files.
You can put them inside your gateway folder or in another folder as you prefere.
Absolute path or relative path is the same but remember, relative starts from gateway folder.
If you choose another folder you need to use GATEWAY_CLASS_PATH constant to start from your choosed class folder because Gateway includes every required classes.
Here there's an example of what I'm speaking about.
```
/**
 * site
 *   |__gateway
 *   |      |____Gateway.class.php // 'classfolder' => '../classes/'
 *   |
 *   |__classes
 *          |____FileManager.class.php
 *          |____Another.class.php
 */
class FileManager {
	var $file = 'text.txt';
	function write($what) {
		if(@$fp = fopen($this->file, 'w')) {
			fwrite($fp, $what);
			fclose($fp);
			$done = true;
		}
		else
			$done = false;
		return $done;
	}
}
						
```
If you call write method with AJSHP, the text.txt file will be created in gateway folder and not inside classes folder. Then if you want to know real path for FileManager class you need to check GATEWAY_CLASS_PATH constant, for example, in contructor.
```
	function FileManager($path = './') {
		if(defined('GATEWAY_CLASS_PATH'))
			$path = GATEWAY_CLASS_PATH;
		$this->file = $path.$this->file;
	}
						
```
utf8 [ boolean, option: true/false - default: false ],
You need to set this option true if you want to use experimental UTF-8 support.
With this option you need to create javascript connection var with true parameter.
Example:
```
var connection = NetServices.createGatewayConnection(true);
						
```

client-side (ajshp with an example)

AJSHP.js file is all you need to manage server-side classes from javascript.
It contains 3 objects for a unique application and 1 object usable for other javascript resources too (PHP_Serializer) .
The principal Object for this interaction is NetServices that allows you to connect with Gateway.class.php file and to know if interaction is working correctly or not.
AJSHP Object is a faster, rewrote and dedicated LoadVars Object, usable only with this kind of interaction.

starting AJSHP
The first thing to do is to include AJSHP.js file in your page, inside header
```
<script type="text/javascript" src="AJSHP.js"></script>
						
```
that will include three packed objects in few than 7Kb.
Evaluated code doesn't contain uncompatible functions, than all old browsers, as IE4, should load this file without problems.
Now we can start our first AJSHP application :-)
```
// NetServices requires Gateway.class.php to work correctly
NetServices.setDefaultGatewayUrl('gateway/Gateway.class.php');

// To get server responces you need a connection variable
var connection = NetServices.createGatewayConnection();
						
```
setDefaultGatewayUrl and createGatewayConnection are all NetServices methods, the first is the absolute or relative path where Gateway.class.php file is and the second initialize and return a new Object, called Connector. This object has only one publi method, called getService that will tell us if AJSHP is compatible with client browser and if always is working correctly (at least first connection to get methods from server class file).

The Listener
This variable will be your best friend in AJSHP interactions because every thing is filtered automatically by its methods.
Theese are basic methods usable to manage AJSHP

onStatus, tell us if something was wrong during interaction
onService, tell us if AJSHP has been loaded or not
special suffix methods, manage results and loading progression
- *_Result, called when interaction with specified method is completed
- *_Progress, called while AJSHP is reading server-side responce

It's time to view what and how theese methods can be used:

// listener initializzation
var listener = new Object();

// onStatus method, called when there's an error.
// message contains a string with method name that
// has generated the error, for example
// Error for class Test and its method readFile
listener.onStatus = function(message) {
	alert(message);
}

// onService method, called when AJSHP is loaded or not
// s is a "success" boolean variable
listener.onService = function(s) {
	if(s == false)
		// ajshp cannot connect to server or required class
		alert('Error, PHP is not working correctly.');
	
	// we can set a variable to know if AJSHP is working or not
	this.enabled = s;
}

Now if we want to call a server-side class method and recieve returne value, we need to create a listener public method with the same name of server-side called method and _Result suffix.

// our server-side class has a method, 
// for example, called encodeString that accepts
// a string and an integer and returns
// its base64 encoded value for integer times.
listener.encodeString_Result = function(v) {
	if(document.getElementById)
		document.getElementById('result').innerHTML = v;
}

// we would print a progression of this
// interaction to know how much time we should wait.
// p is an integer value of progression that's is
// really correct only with server side compression set to false
// (in IE <= 6 it's a fake value)
listener.encodeString_Progress = function(p) {
	if(document.getElementById)
		document.getElementById('progress').innerHTML = p + '%';
}

Now we can create the service and complete our first AJSHP interaction.

The service
This variable will be the server-side caller, automatically popolated with all public methods but constructor.

// to connect on server for the first time
// we need connection.getService method
// that accepts class name and listener to manage
// declared methods
var service = connection.getService('MyFirstAJSHP', listener);

// it's an asynchronous method then we can't call directly
// service.encodeString(); because while we haven't read
// all public methods from server side, encodeString will
// be unavailable.

Server side managed class
Here is an example of our server-side class, saved inside gateway folder (where Gateway.class.php file is)

<?php
// MyFirstAJSHP.class.php
class MyFirstAJSHP {
	function encodeString($str, $times) {
		if(!is_int($times) || (int)$times <= 0)
			$times = 1;
		return str_repeat(base64_encode($str), (int)$times);
	}
}
?>

HTML example page
All things are here, in this file, just try it :-)

<html>
<head>
<title>© AJSHP Project :: MyFirstAJSHP example</title>
<script type="text/javascript" src="AJSHP.js"><!--// © AJSHP //--></script>
<script type="text/javascript">
	NetServices.setDefaultGatewayUrl('gateway/Gateway.class.php');
	var connection = NetServices.createGatewayConnection();
	var listener = new Object();
	listener.onStatus = function(message) {
		alert(message);
	}
	listener.onService = function(s) {
		if(s == false)
			alert('Error, PHP is not working correctly.');
		this.enabled = s;
	}
	listener.encodeString_Result = function(v) {
		if(document.getElementById)
			document.getElementById('result').innerHTML = v;
	}
	listener.encodeString_Progress = function(p) {
		if(document.getElementById)
			document.getElementById('progress').innerHTML =
			p + '%';
	}
	var service = connection.getService('MyFirstAJSHP', listener);
</script>
<script type="text/javascript">
	function test_AJSHP() {
		if(document.getElementById) {
			if(service && listener.enabled) {
				service.encodeString(
					document.getElementById('ms').value,
					parseInt(
					document.getElementById('mi').value
					)
				);
			}
		}
		else
			alert('please upgrade your browser');
	}
</script>
</head>
<body>
<div>
What string do you want to encode ?<br />
<input id="ms" type="text" maxlength="300" value="write something" />
<br /> <br />
How many times you want to repeat encoded string ?
<br />
<input id="mi" type="text" maxlength="5" value="10" />
<br /> <br />
<input type="button" value="TEST AJSHP" onclick="test_AJSHP();" />
<br /> <br />
AJSHP Progression: <span id="progress">0%</span>
<br />
<span id="result"></span>
</div>
</body>
</html>

FAQ (client and server)

Is this a secure way to send and recieve data from clients to server ?
Client interaction is the same, if you use javascript or use a generic form, you need to check sent variables on server before do something, then there are any different strange or dangerous things with this kind of interaction. Only your server-side skill is the key for security, with or without javascript. Then, if you send or recieve uncrypted database connection vars or admin password, for example, the strange is not ajshp ... !
Is possible to create a degradable interaction, usable without javascript ?
Sure and I think in a better way because you can write server classes just one time and choose how to manage them, with or without javascript. In AJSHP mode, the driver is the client, in server-side mode, the driver is a dedicated class that does what client does ... and usually, in other AJAX technologies, you need to rewrote 2 times both client and server :-)
Is possible to use cookies or session on server side called methods ?
Yes, RPC is trasparent only for your eyes, not for you browser, that will read called page as every other than cookies or session should be used without any problems.
How many limits has this client/server interaction mode ?
Client should have an AJAX compatible browser (maybe all recent browsers are compatible)
You can send from php and javascript only compatible variables (look inside PHP_Serializer comments to know more)
Should be dangerous if developer hasn't a good client and server skill

Do you have some question ? Please send me your suggest or your personal faq, visit contribute section.