CommuniGate Pro Pronto! Module API

ProntoCore is an ActionScript 3.0 library and provides means to exchange data with Pronto! and CGP server (using existing XIMSS channel). More information about library structure can be found in ProntoCore ActionScript Documentation (ASDoc).

Modules lifecycle

The Main logical element of Pronto API is "Module". A Module consists of several files in server Skins:

mymodule.swf - a binary Adobe Flash file
mymodule.def - XML text with module metadata
other skin files, such as images

When a user logs into Pronto!, the .def files in current Skin are listed and non-empty well-formed ones are treated as Modules.

All on-login (see .def) Modules are loaded, initialized and launched. On-demand modules are loaded during the session when the Pronto! core or some other loaded Module requests them.

When a user logs out of Pronto!, all Modules are unloaded, custom requests are unregistered and extensions/extension points are removed.

This section describes principles of ProntoCore library. ProntoCore provides several means of interaction: requests and messages. Since ProntoCore is ActionScript 3.0 library all examples are written in ActionScript 3.0.

Instant requests

Instant request is low-typed function call. Result or error (if any) is available immediately after request execution.

var error:Error = new Error(null);
// Retrieve information about selected module - mail, calendar or other one
var selectedExtension:Object = ProntoShell.instantPoll("getSelectedExtension",
    "MainNavigator", error);
// Every request can be executed with error
if (error.message)
    errorTextField.text = error; // show error to use
// Output name of selected section
trace("Selected tab in MainNavigator: " + selectedExtension.name);

Instant request can be made using ProntoShell.instantPoll() in case we need the request result. If we do not need the result or call do not provide any result it is more suitable to use ProntoShell.instantSend():

var error:Error = ProntoShell.instantSend("setSelectedExtensionIndex",
    { extensionPointName: "MainNavigator", index: 0 });
// Every request can be executed with error
if (error.message)
    errorTextField.text = error; // show error to user

Synchronous requests

Synchronous request is low-typed delayed function call. When synchronous request is made, caller may specify two callback functions, that will be called when data and/or response arrives.

Synchronous Pronto API requests work the same way XIMSS synchronous requests do.

ProntoShell.syncPoll("ximss", <fileDirInfo/>, dataCallBack,
    responseCallBack);
 
function dataCallBack(xml:XML)
{
    trace("fileDirInfo data response: " + xml);
}
 
function responseCallBack(object:Object)
{
    var text:String;
    if (object is Error)
        text = Error(object).message;
    else if (object is XML && XML(object).hasOwnProperty("@errorText"))
        text = XML(object).@errorText;
    if (text)
        errorTextField.text = "fileDirInfo has failed: " + text;
}

If synchronous request do not provide any data messages it is more suitable to use ProntoShell.syncSend():

ProntoShell.syncSend("ximss", <fileRename fileName="tasks.txt" newName="oldTasks.txt"/>, responseCallBack);
 
function responseCallBack(object:Object)
{
    var text:String;
    if (object is Error)
        text = Error(object).message;
    else if (object is XML && XML(object).hasOwnProperty("@errorText"))
        text = XML(object).@errorText;
    if (text)
        errorTextField.text = "fileRename has failed: " + text;
}

Asynchronous messages

Asynchronous message is a message, that can arrive at any time.

ProntoShell.dispatcher.addEventListener("ximss-readIM", readIMHandler);

function readIMHandler(event:Object):void
{
    var xml:XML = event.xml;
    trace(xml.@peer + " said: " + xml.toString());
}

ProntoShell.dispatcher.addEventListener("mainNavigatorSelectionChange",
    selectionChangeHandler);

function selectionChangeHandler(event:Object):void
{
    // event object has properties oldIndex, newIndex, oldExtension, newExtension
    var extension:Object = event.newExtension;
    trace("Selected extension name: " + extension.name);
}

Note: unsibscribe from asynchronous events using removeEventListener on "moduleUnloading" event with event.moduleId == "MyModule". Otherwise your module would not be collected by Garbage Collector and objects will recieve events after relogin. Using weak reference does not always help.

For more information on ProntoCore library see it's ASDoc.

Pronto modules can create their own instant, synchronous requests and asynchronous messages. It can be done via static methods ProntoShell.instantRegister, ProntoShell.syncRegister and via dispatching events through static property ProntoShell.dispatcher (IEventDispatcher).

Note: All requests, registered by modules, are unregistered on logout.

Note: If you publish module that provides public request, make sure to maintain backward-compatibility for that requests.

Custom instant request

Example: Register getLatestNews instant request, that provides access to some internal module data

ProntoShell.instantRegister("getLatestNews", getLatestNewsHandler, "News");

function getLatestNewsHandler(request:String, param:Object, error:Error):String
{
    var timePeriod:int = param.hasOwnProperty("timePeriod") ? param.timePeriod : 0;
    if (timePeriod > 0)
    {
        var result:String;
        // custom logic, setting result to some value
        return result;
    }
    else
    {
        // provide error message
        error.message = "timePeriod property is not specified or is incorrect";
        return null;
    }
}

Custom synchronous request

Example: register myService synchronous request

var error:Error = ProntoShell.syncRegister("myService", myServiceHandler, "MyModule");
if (error)
    throw error; // better handle it somehow

function myServiceHandler(request:String, param:Object, dataHandler:Function,
    responseHandler:Function):void
{
    var xml:XML = param as XML;
    if (!xml)
    {
        responseHandler(new Error("myService parameter should be XML"));
        return;
    }
 
    // dataHandler should be called before responseHandler and can be called
    // more than once. responseHandler should be called in any case. All this
    // can be done any time - right now or a minute later.
    dataHandler({ label: "Label 1" });
    dataHandler(new Date());
    responseHandler("All done!");
}

Custom asynchronous message

// code in News module. Notify everybody, that news feeds are loaded
ProntoShell.dispatcher.dispatchEvent(new Event("newsLoaded"));

Pronto! provides the following requests and messages that allow to retrieve information about modules, load and unload modules, etc.

Instant requests

moduleData

Retrieves information about module. Object is returned (see ProntoCore data). Module id should be passed as parameter.

moduleDataList

Retrieves information about all modules. Array is returned.

moduleHas

Checks module existence. String module id should be passed as parameter. Boolean is returned.

moduleLoad

Loads on-demand loading module. String module id should be passed as parameter.

moduleUnload

Unloads already loaded and initialized (or failed to load or initialize) module. String module id should be passed as parameter.

Note: some modules (including all Pronto default modules) do not support second load during use session. This happens because module tries to find extensions, that should be added from .def file, while they were removed during unload.

getInitialized

Returns Boolean value describing if the whole initialization process is complete: all on-login modules are loaded (or failed to load) and initialized (or failed to initialize).

moduleFileURL

Retrieves URL for the given file.

moduleId:String: Id of the module.
fileName:String: Name of the module's file (icon or other asset).

Synchronous

initialized

Each module should call this function after it has finished adding extension points, registering requests and other stuff, that can be used by other modules. Simple module that just adds one tab to MainNavigator usually makes this call first a does not even specify responseHandler.

Response to this request comes simultaneously to all modules when all on-login modules are initialized (or have failed to load or initialize). For on-demand loading modules request comes immediately (if all on-login loading modules are already initialized).

moduleId:String: Module id.
errorText:String: Optional fatal error description. If specified, error is logged in module errors and status property becomes error (see module object format)

If String is passed instead of Object, it is treated as module id.

ProntoShell.syncSend("initialized", "com.myCompany.myModule.MyModule", responseCallBack);

Asynchronous

moduleInitialized

This event is dispatched after Pronto! has called module moduleId response handler for his initialized request.

moduleId:String: Module id.

moduleError

This event is dispatched when module fails to load or if it reports error in initialized request.

moduleId:String: Module id.
errorText:String: Optional. Is specified if module has specified error description in initialized request.

moduleUnloading

This event is dispatched before unloading module moduleId. At that moment no operations (like removing module extensions) are executed yet.

This event can be used to desctruct module: remove extensions and extension points, unsibscribe from ProntoShell.dispatcher, unload data, release some data channels and etc.

moduleId:String: Module id.

moduleUnload

This event is dispatched after module moduleId has been unloaded, all his extension points and extension removed and other cleanup completion.

moduleId:String: Module id.

E-Mail module

E-Mail is not yet a true module, now it is an internal part of Pronto.

Adds Mail extension to MainNavigator with preferredIndex 10.

Adds Folders with preferredIndex 20, Compose with preferredIndex 30, Delete with preferredIndex 40, MailControl with preferredIndex 90 and RPOP with preferredIndex 100 to Prefs.

Adds Mail extension with preferredIndex 10 and MailNewFolder with preferredIndex 20 to NewButton.

Synchronous requests

mailCompose

Opens mail composing popup.

toValue:String: Content for the "To:" field.
subject:String: Content for the "Subject:" field.
body:String: Mail body.

mailShowNewFolderDialog

Opens new mail folder popup.

addressBookSelect

Opens Address Book and lets user select items from contacts folders.

showPhones:Boolean: Defines whether phone numbers will be shown in the contacts grid or not.
allowMultipleSelection:Boolean: Optional. If set to true, multiple selection is allowed.

Data handler receives object with items:Array property, that contains objects with the following properties:

subject:String: Textual description of contact or contact group.
toValues:Array: Optional. Not empty array of String user E-Mail addresses and phones (if showPhones was set to true).
selectedItem:String: Optional. If user has picked one item from the list of toValues, it is specified here.

Note: Pronto allows only one instance on the Address Book. If it is called (ex. from Dialer) during addressBookSelect execution, request finishes execution without data just like when user closes Address Book popup.

IM module

IM is not yet a true module, now it is an internal part of Pronto.

Adds IM extension with preferredIndex 50 to Prefs.

Synchronous requests

imAdd

Shows adding IM contact dialog with pre-filled fields. If given peer already exists all other properties are ignored and popup opens in edit mode.

peer:String: Optional. Peer, usually an E-Mail address.
realName:String: Optional. Real name.
groups:Array: Optional. User groups. Pronto yet supports only 1 group for user, so the first array item is used.

Calendar module

Calendar is not yet a true module, now it is an internal part of Pronto.

Adds Calendar extension to MainNavigator with preferredIndex 20, to Prefs with preferredIndex 70 and to NewButton with preferredIndex 20.

Synchronous requests

calendarShowNewEventDialog: Shows "Event" dialog to create new event

Telephony module

Telephony is not yet a true module, now it is an internal part of Pronto.

Adds Telephony extension to MainNavigator with preferredIndex 30, CallControl extension with preferredIndex 110 and Dialer extension with preferredIndex 120 to Prefs.

Instant requests

getPhoneStatus

Returns Object with properties:

active:Boolean: Is true if phone is enabled and has at least one active call.
enabled:Boolean: Is true if phone was initialized and is functioning.
calls:Array: Array of objects with properties peer:String with peer address and status:String with description of call status. Status should not be interpreted.

Asynchronous messages

phoneStatus: Is dispatched when phone status changes. This includes enabling / disabling, calls and their statuses changes. Event object has the same properties as getPhoneStatus result.

Contacts module

Contacts are not yet a true module, now it is an internal part of Pronto.

Adds Contacts extension to MainNavigator with preferredIndex 40 and to Prefs with preferredIndex 80. Adds ContactsNewContact extension with preferredIndex 30 and ContactsNewGroup extension with preferredIndex 40 to NewButton.

Synchronous requests

contactsShowNewContactDialog: Shows "Contact" dialog to create new contact.

contactsShowNewGroupDialog: Shows "Contact Group" dialog to create new contact group.

News module

Module id is News.

Adds extension News to MainNavigator and Prefs.

Music module

Module id is Music.

Adds extension Music to MainNavigator and Prefs.

Adds MusicPlayerEmbed and MusicPlayerLink extension to SharingMethods.

Photos module

Module id is Photos.

Adds extension Photos to MainNavigator.

Video module

Module id is Video.

Adds extension Video to MainNavigator.

Files module

Module id is Files.

Adds extension Files to MainNavigator and FilesNewDirectory to NewButton.

Defines FileEditors extension point.

Adds extensions to FileEditors extension point: TextEditor with preferredIndex 10, ImageViewer with preferredIndex 20, MP3Player with preferredIndex 30, HTMLViewer with preferredIndex 40 and VideoPlayer with preferredIndex 50.

Synchronous requests

filesShowNewDirectoryDialog: Shows "Create Directory" dialog.

Pronto API utilizes well-known system of extension points, that are some logical or visual containers and extensions, that are items in that containers.

Modules can create new Extension Points, add, list and remove extensions from existing Extension Points and more.

Typically module define one extension for MainNavigator extension point in def file. This lets Pronto show module in MainNavigator without loading it. When module gets loaded, it should replace def file extensions to add actual content to them because for example MainNavigator specifies progress bar for content property (see examples).

Instant requests

extensionsList

Lists current extensions starting from extension with index 0. Array or Object is returned.

extensionPointName:String: Target extension point.
extensionName:String: Optional. If specified, only that extension is returned.

extensionAdd

Adds new extension to existing extension point.

extensionPointName:String: Name of extension point.
extension:Object: Extension.
buffer:Boolean: If true and extension point does not exist, extension will be cached and added as soon, as extension point will be created.
replace:Boolean: It true and extension with specified name already exist in extension point it will be seamlessly replaced with new one.
This option is useful if you replace extension that was added using .def file.

Example:

var error:Error = new Error();
var extension:Object = ProntoShell.instantPoll("extensionsList", 
    { extensionPointName: "MainNavigator", extensionName: "Files" }, error);
if (error.message)
    throw error;
	
var extensionObject:Object = {};
extensionObject.name = "Files";
extensionObject.moduleId = "Files";
extensionObject.preferredIndex = extension.preferredIndex;
extensionObject.localizedLabelId = extension.localizedLabelId;
extensionObject.iconFactory = extension.iconFactory;
extensionObject.contentFactory = new ClassFactory(FilesContent);
extensionObject.navigationFactory = new ClassFactory(FilesNavigation);
extensionObject.toolBarFactory = new ClassFactory(FilesToolBar);
var object:Object = {};
object.extension = extensionObject;
object.extensionPointName = "MainNavigator";
object.replace = true;
error = null;
error = ProntoShell.instantSend("extensionAdd", object);
if (error)
    throw error;

extensionRemove

Removes existing extension from extension point.

extensionPointName:String: Name of the extension point.
extensionName:String: Name of the extension.

extensionHas

Checks extension existence. Boolean is returned.

extensionPointName:String: Name of the extension point.
extensionName:String: Name of the extension.

extensionPointAdd

Adds new extension point. Object extension point should be passed as parameter (see ProntoCore data).

extensionPointRemove

Removes existing extension point. Object extension point object should be passed as parameter.

extensionPointHas

Checks extension point existence. String extension point name should be passed as parameter. Boolean is returned.

getSelectedExtension

This functionality is optional, extension point may not support selecting. Retrieves selected extension. String extension point name should be passed as parameter. Object is returned.

setSelectedExtension

This functionality is optional, extension point may not support selecting. Sets selected extension.

extensionPointName:String: Target extension point.
extensionName:String: Name of the extension to select.

getSelectedExtensionIndex

This functionality is optional, extension point may not support selecting. Retrieves selected extension index. String extension point name should be passed as parameter. int is returned.

setSelectedExtensionIndex

This functionality is optional, extension point may not support selecting. Sets selected extension index.

extensionPointName:String: Target extension point.
index:int: Extension index. -1 removes selection (if supported by the extension point).

MainNavigator

Forms the whole Pronto! visual structure. Mail, Calendar and other sections are extensions in MainNavigator.

Supported extensions properties are standard plus the following.

Extension object properties

iconFileName:String: In additional to standard functionality, more that one file can be specified, for example "icon16.png icon32.png icon64.png". MainNavigator uses most suitable one at the moment.
navigation:IUIComponent and DisplayObject: Similar to content, used as navigation visual object.
navigationFactory:IFactory: Similar to contentFactory for navigation.
toolBar:IUIComponent and DisplayObject: Similar to content, used as toolbar.
toolBarFactory:IFactory: Similar to contentFactory for toolbar.

mainNavigatorSelectionChange

Event, dispatched when selection changes. See selection change event.

Prefs

Extensions from this Extension Point form list of available panels in "Preferences" popup ("Settings" in previous versions).

Supported extensions properties are standard.

Prefs has one difference in content property. Each time the Preferences popup is opened, content is recreated using contentFactory. When popup is closed, content properties of all extension are set back to null, that means you can use only contentFactory property safely.

Contains General extension with preferredIndex 10 and Password extension with preferredIndex 60.

For more information about Prefs extension logic see Preferences.

NewButton

This Extension Point corresponds to "New..." button at the top-left of the screen. It allows to compose letter, create contact and so on. Modules can add custom buttons to dropdown menu and can bind them with MainNavigator extension. Ex. when Files extension is selected in MainNavigator, "New..." button will open file directory creation dialog.

Supported extensions properties are standard excluding content and contentFactory properties.

Extension object properties

mainNavigatorExtensionName:String: Name of corresponding extension in MainNavigator extension point.
callBack:String: Name of synchronous request that should be called when button is pressed.

Example: adding FilesNewFolder extension to NewButton in files.def

<extension extensionName="FilesNewFolder" extensionPointName="NewButton" mainNavigatorExtensionName="Files"
    localizedLabelId="DirectoryTag" preferredIndex="5" iconFileName="filesicon16.png" callBack="filesNewFolderDialog"/>

FileEditors

This Extension Point holds editors and viewers that are used in Files module.

Supported extensions properties are standard excluding contentFactory. Apart from them the following properties are valid:

Extension object properties

fileTypes:String: Space-separated extensions, that this viewer / editor can handle. Ex. jpg jpeg gif png for image viewer. Case-insensitive.

Moreover, content property should provide the following properties:

edit:Function - function(object:Object):void: This function is called when editor is added to stage and should show and/or edit given object that is File Storage file object.
get changed():Boolean: Getter method, should return Boolean indicating unsaved changes in current file. If extension is viewer and do not change file itself, this function should always return false.
save:Function - function():void: Calling this function should start file saving.
clean:Function - function():void: Calling this function should cause total editor cleanup (even if there are unsaved changes).

After editor has changed the file on the server it should dispatch fileChanged event so that Pronto! change internal file URLs to present the latest file version to the user.

Note: at this moment it is not allowed to add editors through .def file. content property should be populated.

SharingMethods

This Extension Point contains methods for File Storage objects sharing.

Contains URLSharingMethod extension with preferredIndex 10 and FileBrowserSharingMethod extension with preferredIndex 20.

Supported extensions properties are standard except content and contentFactory properties. Apart from them the following properties are valid:

Extension object properties

textFunction:Function - function(object:Object):String: Function should recieve File Strorage file or directory and return string, that will be shown to user. It can be an url or an embed-code.
If File Storage object can not be shared using this method, null should be returned.

Pronto API allow modules to create, read and remove their own custom preferences and add panels to "Preferences" popup using requests from this section.

Instant handlers

getPref

Returns XML node with given name (if found) from settings of given type.

type:String: Optional. Possible values are custom, default or effective. If not specified, effective settings are meant.
prefName:String: Name of the XML node.

var error:Error = new Error(null);

var pref:XML = ProntoShell.instantPoll("getPref", { prefName: "CalendarBox", type: "effective" }, error);
if (error.message)
{
    errorTextField.text = error.message;
    return;
}
var calendarBox:String = pref ? pref.toString() : "Calendar";

prefName value can be passed as a parameter to simply get effective preference value:

var error:Error = new Error(null);

var pref:XML = ProntoShell.instantPoll("getPref", "CalendarBox", error);
if (error.message)
{
    errorTextField.text = error.message;
    return;
}
var calendarBox:String = pref ? pref.toString() : "Calendar";

setPref

Adds given prefXML to custom preferences XML. To remove custom preference, add node with Default text inside. This will cause preference to remove on next update.

New preferences are not available through getPref immediately. They apply only after next prefsUpdated event.

Does not cause custom preferences to be sent to the server immediately.

prefXML:XML: Preference itself.
relogin:Boolean: Defines, whether this preferences change will be applied immediately or only on next login. Ex. skin can not be changed during the session.

var error:Error = ProntoShell.instantSend("setPref", { prefXML: <myOwnPref><myValue myAtt="1"/></myOwnPref> });
if (error)
    errorTextField.text = error.message;

// removing myOwnPref
var error:Error = ProntoShell.instantSend("setPref", { prefXML: <myOwnPref>Default</myOwnPref> });
if (error)
    errorTextField.text = error.message;

prefsUpdate

Sends custom preferences to the server. prefsUpdating event is dispatched immediately and prefsUpdated is dispatched on success or fail. Note that prefsUpdated is dispatched 2 times, for new effective and custom preferences (in this order).

prefRelogin

Returns Boolean indicating whether there are changes in custom preferences that can be applied only on the next login.

prefsOpen

Opens "Preferences" popup.

selectedExtensionName:String: Optional. Name of extension to be selected.

prefsLoaded

String type can be specified as parameter with possible values default, custom and effective (used by default).

Returns Boolean indicating whether Pronto! has already loaded preferences with a given type.

Asynchronous messages

prefsUpdating

Is dispatched when custom preferences are being sent to the server. Is typically used to disable preferences-controlling inline (not in "Preferences" popup) controls until prefsUpdated event arrive.

prefsUpdated

Is dispatched when any preferences XML (custom, default or effective) arrive from the server.

xml:XML: Optional. Recieved XML itself. Is defined if errorText is not defined.
errorText:String: Optional. Error during saving custom preferences to the server. Is defined if xml is not defined.

prefsSave

Is dispatched when user presses "Modify" button in "Preferences" popup. When custom preferences tab receives this event it should commit all changes that user have made to Pronto! using setPref request.

prefsClose

Dispatched when "Preferences" popup is closed by user or on logout. Custom preferences tabs should listen this event to destruct itself to avoid problems on next Preferences popup opening and saving.

Instant requests

getStringsXML: Returns current strings XML.
getString: String identifier should be passed as parameter. It can be dot-separated, ex. HeaderNames.EMAIL corresponds E-mail string. If value is not found, identifier itself is returned.

Asynchronous messages

stringsChange: Is dispatched each time getStringsXML call result changes.

Instant requests

getUserPresent: Returns Boolean specifying if user is idle or present based on AIR NativeApplication.timeSinceLastUserInput property and AwayTimer preference. If Pronto! runs not as AIR Application, always returns true.

Asynchronous messages

userIdle: Is dispatched when user is treated as idle. Available only in AIR version.
userPresent: Is dispatched when user is treated as present. Available only in AIR version.

The properties mechanism provides access to common data like session ID, user name and many more. Custom modules can provide their own properties.

Instant requests

getProp

String property name should be passed as parameter. Returns Object property value or undefined if it does not exist.

var error:Error = new Error();
var sessionId:String = ProntoShell.instantPoll("getProp", "sessionID", error) as String;

setProp

Sets property to a specified value. Parameter should have the following properties:

name:String: Name of the property. It is recommended that custom modules use package-like names for their properties, ex. com.myCompany.myModule.myProperty1
value:Object: Value of the property.

ProntoShell.instantSend("setProp", { name: "com.myCompany.myModule.myProperty1", value: 41 });

getProps

Returns Object with all properties.

List of properties

sessonID:String

Session id.

userName:String

User name from <session/> server response.

realName:String

User name from <session/> server response.

secure:Boolean

Is connection secure or not.

host:String

Current host.

knownValues:XML

<knownValues/> node. Example:

<knownValues id="2">

  <tzid name="HostOS"/>
  <tzid name="(+0100) Algeria/Congo"/>
  <tzid name="(+0200) Egypt/South Africa"/>
  ...
  
  <charset name="iso-8859-1"/>
  <charset name="windows-1252"/>
  ...
  
  <mailRuleAllowed name="All But Exec"/>

  <mailRuleAllowed name="Any"/>
  ...
  
  <mailRuleCondition name="From"/>
  <mailRuleCondition name="Sender"/>
  ...
  
  <mailRuleAction name="Store in" allowedSet="Filter Only"/>
  <mailRuleAction name="Mark" allowedSet="Filter Only"/>

  ...
  
  <signalRuleAllowed name="No"/>
  <signalRuleAllowed name="Any"/>
  ...
  
  <signalRuleCondition name="Method"/>
  <signalRuleCondition name="RequestURI"/>
  ...
</knownValues>

The following functionality allows modules to use the Pronto! Log.

Instant requests

log

Adds message to log.

message:String: Log message.
component:String: Component identifier. Usually it is module id.
level:String: Level of log message. Possible values are debug, info, error and fatal.

ProntoShell.instantSend("log", { message: "Starting initialization", 
    component: Model.MODULE_ID, level: "info" });

.def file format

This file is stored in server Skins and holds module metadata. Root tag is module.

Attributes:

moduleId

Unique id of the module

fileName

Name of corresponding binary .swf

version

Not interpreted, is used during composing URLs to module files to avoid caching

loadType

onLogin (loaded immediately after login) or onDemand (loaded on explicit call - when module is selected in some Extension Point or "moduleLoad" request made)

Body:

requirements

Optional. List of options, that should be enabled for account (see currentStatus XIMSS response). Contains requirement nodes with option attribute.

syncHandlers

Optional. Contains child nodes syncHandler with attribute name. List of synchronous handlers that module will register. Meaningful when module loadType is onDemand. List is used to allow clients make synchronous requests without checking if this module is loaded or not. If Pronto API receives synchronous request from this list and this module is not loaded, the module loading starts and request is executed when the module is loaded. If module loading fails, request is finished with the corresponding error code.

extensions

Optional. Contains child nodes extension. Meaningful when module loadType is onDemand. List of extensions, that should be added to extension points on login. Each extension node is transformed to extensionAdd request using the following rules:

extensionPointName attribute - name of target extension point
extensionName attribute - name of this extension
All other extension node attributes are moved to request extension object unchanged and without interpreting
Note: do not specify moduleId, it is set from root XML tag

Example:

<module moduleId="com.pronto.modules.video" fileName="video.swf" version="1" loadType="onDemand">
	
	<requirements>
		<requirement option="HTTP"/>
	</requirements>

	<syncHandlers>
		<syncHandler name="loadVideos"/>
	</syncHandlers>

	<extensions>
		<extension extensionName="Video" extensionPointName="MainNavigator" preferredIndex="11"
			localizedLabelId="MyVideos" iconFileName="videoicon16.png videoicon24.png videoicon32.png videoicon48.png"/>
	</extensions>

</module>

Module object.

This object can be retrieved using moduleData and moduleDataList requests.

moduleId:String

Unique module id.

version:String

Module version.

status:String

Possible values:

notLoaded
loading
error
initializing
initialized

fileName:String

Module .swf file name.

requirements:Array of String

Array of module requirements.

syncHandlers:Array of String

Array of module synchronous handlers

extensionAddRequests:Array of Object

Array of extension add requests

errors:Array of Error

Errors reported by module

bytesLoaded:int

Loaded bytes of the .swf.

bytesTotal:int

Size of module .swf.

Extension object

Pronto API allow custom extension points, so it does not put over any restrictions on extension object properties except name and moduleId. They are the only obligatory properties of extension object. That properties and other commonly used in standard extension points extension properties are listed below.

name:String

Name of the extension, unique in extension point.

moduleId:String

Id of module that has added this extension. When module is unloaded, all his extensions are removed.

content:IUIComponent and DisplayObject

Content that should be added, for example mx.containers.VBox instance.

contentFactory:IFactory

Factory to create content if it is absent.

Note: content will be created only when it is actually needed. Using factories increases performance.

preferredIndex:int

All extensions in point are sorted by this index.

Note: getSelectedExtensionIndex returns real index, not this one

label:String

Extension label. Visual representation depends on extension point. Has lower priority than localizedLabelId

localizedLabelId:String

Id of localized string that should be used as a label. Use "." to separate inherited elements.

Example: the following part in strings XML

<strings skinName="Pronto-">
	...
	<strings name="ACLRights">
		<string name="a">Admin</string>
		...
	</strings>
</strings>

can be addressed as ACLRights.a

Currently available localized labels and their ids can be viewed on your CGP server, for example at /SkinFiles/mydomain.com/*/strings.xdata

iconFactory:IFactory

Factory should produce DisplayObject instances that will be treated as icons.

Note: Pronto loads icons for on-demand modules, so when actual module code is loaded it can reuse the existing iconFactory value

iconFileName:String

Name of image in server Skins. Checked if iconFactory is not defined.

Extension point object.

Each function is called during executing corresponding instant request. param is passed untouched.

name:String: Unique name of the extension point.
extensionsList:Function functionName(param:Object, error:Error):Array: Lists current extensions.
extensionAdd:Function functionName(param:Object, error:Error):void: Adds new extension to extension point. param is passed untouched.
extensionRemove:Function functionName(param:Object, error:Error):void: Remove extension. param is passed untouched.
extensionHas:Function functionName(param:Object, error:Error):Boolean: Check extension existence. param is passed untouched.
remove:Function functionName(param:Object, error:Error):void: Remove extension point. Is called when extension point is removed (for example, on logout). Should not remove extensions and dispatch events about their removal. Instead of it whole extension point must be removed.
getSelectedExtension:Function functionName(param:Object, error:Error):Object: Optional. Some extension point do not support selection due their nature. Retrieves currently selected extension, null is nothing is selected.
setSelectedExtension:Function functionName(param:Object, error:Error):void: Optional. Some extension point do not support selection due their nature. Sets selection to a given extension, null to deselect.
getSelectedExtensionIndex:Function functionName(param:Object, error:Error):int: Optional. Some extension point do not support selection due their nature. Retrieves currently selected index, -1 if nothing is selected.
setSelectedExtensionIndex:Function functionName(param:Object, error:Error):void: Optional. Some extension point do not support selection due their nature. Sets currently selected index, -1 to deselect.

Extension Point selection change event properties

This asynchronous event is dispatched when some Extension Point selection changes. This can happen when user, module or Pronto change selected extension, remove or add new extension.

oldExtension:Object: Previously selected extension. null if nothing was selected.
newExtension:Object: Currently selected extension.
oldIndex:int: Previously selected index.
newIndex:int: Currently selected index.

File Storage object

This is description of abstract File Storage object. This object is used to describe common properties of file and directory in File Storage. Each File Storage file object and File Storage directory object has these properties:

type:String: directory or file
name:String: Name of the object, ex. myphotos or john.jpg
directory:String: Parent directory, ex. private/myphotos
path:String: Full object path, ex. private/myphotos/john.jpg
size:int: Size of the object
publicURL:String: Optional. Is available if file or directory is not inside private directory or if it has special .meta file with key.
sessionURL:String: URL to the object that is valid during current XIMSS session.

File Storage file

File Storage file has the following additional properties:

extension:String: Extension of this file, ex. mp3. If file does not have extension - null.

File Storage directory

File Storage directory has the following additional properties:

publicFileBrowserURL:String: Optional. Is available if file or directory is not inside private directory or if it has special .meta file with key. URL to the page, that shows directory content and allow to navigate inside it. URL targets filebrowser.wcgp.

For a complete step-by-step module creating instructions see Quick Start Guide. This section will provide only module requirements:

Module should be created using Flex SDK 3.2.0.
Note: Flex Builder 3 use older version of SDK by default, you have to make it use Flex SDK 3.2.0.
Module root tag should be <mx:Module> since it is loaded as Flex Framework module.
When module .swf is loaded into Pronto, all module classes with the names (com.package.ClassName) that already exist in Pronto will be discarded and Pronto! classes will be used instead. This causes the following issues:
- Module should use the same version of SDK as Pronto uses.
- Module can exclude ProntoCore and Flex SDK from .swf to reduce file size
- Module can not make changes to classes that exist in Pronto or Flex SDK (ex. change mx.controls.Button) because those changes will be discarded.
- Module should not include custom classes inside the following packages, that are used by Pronto:
  - com.pronto.*
  - com.stalker.*
  - com.adobe.*
  - com.flextoolbox.*
  - com.qs.*
  - com.sho.*
  - org.gif.*
  - org.xif.*
  - Text Layout Framework packages

Pronto! loads its modules from server skins, which is far from convenient if you're developing a module. In that case you have to upload each and every version you want to try inside server skin.

Test versions of Pronto! can be executed locally with the help of debugconfig.xml file, which should be placed near pronto.swf on your hard drive.

debugconfig.xml is intended to simplify the process of module development and makes it possible to run web version of Pronto! on developer's computer. It allows setting the server Pronto! should use, adding local modules and configuring remote modules to be loaded from local folders.

A typical debugconfig.xml file:

<debug>
    <!-- defaults: port="8100" secure="no" -->
    <server host="localhost" port="8100" secure="no" />
    <modules>
        <!-- Load .swf, and icons for module, already existing on server, from local path -->
        <module id="com.myCompany.releasedModule" basePath="com/myCompany/releasedModule" />
		
        <!-- Load .def, swf and icons for module that is not on server yet -->
        <module src="C:/Workspace/newmodule/bin-debug/newmodule.def" 
            basePath="C:/Workspace/newmodule/bin-debug" />
    </modules>
</debug>

Root node should contain server and can contain modules nodes.

server

Sets the server domain name Pronto! should connect to. It can have the following properties:

host: Server host
port: Optional. Server port. Default is 8100
secure: Optional. If you want to use secure connection, set it to yes, otherwise - to no. Default value is no.

modules

Optional. The list of local base paths for every module that should be loaded - both local and remote.
Can contain any number of module tags, with the following attributes:

id: Module id. If not specified, src should be specified. If specified, src can not be specified.
src: .def file relative path. If not specified, id should be specified. If specified, id can not be specified.
basePath: Relative path to the folder which contains module .swf, icons and other assets.