CommuniGate Pro
Version 6.1
 
Pronto!
 
Module API

Pronto! Module API

The Pronto! Client API is used to extend the application functionality. You can add new modules alongside the Email, Calendar, News and other already existing Pronto! modules.

See the complete Pronto! API documentation for mode details and module examples.

ProntoCore library

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:

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.


ProntoCore requests and messages

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.


Providing requests to other modules

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"));

Managing modules

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.

Default Pronto modules

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.

Extension points and extensions

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).

Default extension points

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.


Preferences

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.

See also: MyModule example.


Accessing XIMSS channel

ximss
Synchronous ProntoCore request. Sends synchronous XIMSS request. XML should be passed as parameter.

Note: you shouldn't set id attribute, it is set automatically.

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;
}
ximss-...
Asynchronous ProntoCore message. Is dispatched each time any asynchronous XIMSS message arrive.
xml:XML
XIMSS XML data.
Example:
ProntoShell.dispatcher.addEventListener("ximss-readIM", readIMHandler);

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

Strings

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.

User idle / present

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.

Properties

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>

Log

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" });

ProntoCore data format

.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.

Creating Module

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

  1. 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.

  2. Module root tag should be <mx:Module> since it is loaded as Flex Framework module.
  3. 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

Debugging module: debugconfig.xml

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.

CommuniGate® Pro Guide. Copyright © 1998-2015, Stalker Software, Inc.