Cabron Connector - PHP Flash Remoting

Introduction

The ActionScript method names that you'll use while working with Cabron Connector mainly follows the syntax of the Macromedia version of Flash Remoting.

Steps

A typical ActionScript that uses Cabron Connector will be built as follows (the lines marked with "+" are mandatory):

+ #include "Cabron.as"
+ #include "CabronDebugger.as"
- set up debugger options
+ create CabronConnector instance
+ set gateway URL
- set deserialization properties for the connector instance
+ define responder object or method
- define error handler method
- define deserialization monitoring method
+ create service instance
- set deserialization properties for the service instance
+ call the method of the service

Including the files

You will need to include the following line in the first frame of your movie to enable Cabron Connector:

#include "Cabron.as"

If you plan to debug your movie, you should include:

#include "CabronDebugger.as"

If you include the line above, and open the Printr Debugger Panel from Window > Printr Debugger, you'll be able to see debug information about the remoting.
Before making the movie live, it's wise to remove the debugger inclusion from your movie. If you leave the inclusion, it will increase the size of the movie a bit, but the main point is that the movie can be debugged by others.

The #include "CabronDebugger.as" will enable the printr and returnr functions, meaning that you'll be able to inspect ActionScript objects with a call like this:

printr(objetcToInspect);

You can read more about the Printr Debugger at printrmx.sourceforge.net

Creating Cabron Connector instance

var cabronConnectorInstance = new CabronConnector();

Setting gateway URL

cabronConnectorInstance.setGatewayURL(url);

The url should specify the folder in which the gateway.php is located.
The gatewayURL can be set by this call, or by other means. The evaluation process for the gatewayURL is the following:

if the variable cabronGatewayURL is passed through FlashVars to the movie, this value will override any value specified in the movie
if the url passed to the setGatewayURL is beginning with "http://" or "https://" this will be the gatewayURL
if the url passed to the setGatewayURL does not begin with the mentioned strings, the url will be considered to be a partial one, and the server name will be added in front of this string
if the setGatewayURL method was not called, the gatewayURL is set to "http://localhost/cabronconnector/gateway"

Creating service instance

var serviceInstance = cabronConnectorInstance.getService("serviceName",responderObject);

The first parameter, the serviceName is the name of a PHP file without the ".php" extension.
This file must be located in the services directory that is set in the gateway.php. If the file is located deeper in a directory, you should place here the path to the file without the extension, and the OS specific path delimiter ('/' or '\') replaced by "."

The service can consist of:

a simple procedural php file that defines one or more functions
a class (that is named like the file but without the extension, and the first letter capitalized) with one or more methods

The responderObject will handle all the callback for methods of this service.

Calling the method of the service

The syntax is the following:

serviceInstance.methodName([responderObject], parameter1, ...);

If the first parameter has defined the onResult or methodName_Result functions, it will be taken as responder, otherwise it will be treated as a normal parameter.

ActionScript code hints

If you want the ActionScript panel to display code hints for the different Cabron objects, you should add the following class suffixes to the different objects:

ClassName	suffix	creation
CabronConnector	_cc	new CabronConnector();
CabronService	_cs	v_cc.getService('sname',v_cro);
CabronDeserProp	_cdp	new CabronDeserProp();
CabronResponderObject	_cro	new Object(); or new ObjectSubclass();

About the responder objects

The remote method calls in this implementation of remoting (and in the others too) are asynchronous. This means, that they behave exactly like loadVariables(), LoadVars.load() or loadMovie(): the ActionScript does not stop to wait for the completion of the method, but it will continue it's execution. When the requested data is available, a callback function will be invoked.

In this case, you have two possibilities:

you can specify a responder object for the service - this means that all method calls on that service will call the given object's handler methods
you can specify a responder object for a method of a service - this must be passed as the first parameter for the method call, and will override the responder of the service, if any.
The Cabron Connector will look for the onResult or remoteMethodName_Result in the object. If any of these two methods is defined, the object will be considered the responder for the method call, otherwise it will be transmitted as a parameter to the PHP service.

The responder object can have callback methods for the following events:

result callback - this is mandatory, it will be called when the result for a previous method call is available
error (or status) callback - it's not mandatory, but it's a good practice to always define it. It will be called if an error occured during the method's execution.
load callback - it's optional, it will be called when the data is loaded. You should not use this, rely on the result callback instead. However it can be useful if you use timed deserialization (if you suspect that a large amount of data will be loaded, and it's deserialization will block the flash movie, you can set the deserialization to be performed during several frames. This way the movie won't block).
working callback - it will be called each time when deserialization is performed (only if you use timed deserialization).

The syntax of the callback methods is the following:

form1	form2	parameters	comment
onResult	methodName_Result	result
onStatus	methodName_Status	fullErrorMessage, errorCode, shortErrorMessage
onLoaded	methodName_Loaded		You should use it only if timed deserialization is enabled
onWorking	methodName_Working	totalNr, currentNr, atonceNr	You should use it only if timed deserialization is enabled. Can be used for displaying progress during the deserialization process in case of large amount of data.

Predefined error messages/codes

code	shortdesc	comment
1	Can not access gateway	Source: ActionScript
2	Service not found	Source: gateway.php
3	Remote method not defined	Source: gateway.php
4	Empty request	Source: gateway.php
5	No responder	Source: ActionScript Can not be handled, just debugged
6	Can not locate charactermap	Source: gateway.php

Responder example

This is just one example, you will find a lot of in the samples archive, or between the on-line samples

#include "Cabron.as"
#include "CabronDebugger.as"

_global.cc = new CabronConnector();
cc.setGatewayURL("http://your.server.com/cabronconnector/gateway");

var responderObject = new Object();
responderObject.onResult = function(res){
trace("Response:" + res);
}
responderObject.onStatus(errmsg){
trace("Error occured:" + errmsg);
}

helloService = cc.getService("helloService",this);
helloService.helloMethod("Word!");

Timed deserialization

Plase read the "How does it work section" on the Home page to find out why should you use timed deserialization.

If you want the Cabron Gateway to perform timed deserialization when loading data from PHP services, you can specify the following two parameters:

tagAtOnce - how many CDE tags will be deserialized on a single frame - the default is 100
workOnFrame - on which frames should the deserialization be performed - the default is 1, meaning that it will be performed on each frame, while there is available un-deserialized data. Setting to 2 means that it will work on each second frame.

The deserialization options can be set for the CabronConnector instance, or for the service instances. If you don't set it, the deserialization will be performed at once.

Example:

var service = cc.getService("servicefile",this);

var dp = new CabronDeserProp();
dp.deserMode = 'T'; //timed deserialization
dp.tagAtOnce = 20; //20 tags on each frame
dp.workOnFrame = 2; // work on each second frame

service.setDeserProp(dp);

service.methodName();

If the timed deserialization is enabled, there are two new event handlers of the responder object that can be defined: onLoaded and onWorking. The first one is called when the data is loaded, the second one is called each time the deserialization is performed. It takes 3 parameters : totalNr, currentNr, atonceNr.