| Version 5.4
Introduction
Installation
SysAdmin
Network
Objects
Storage
E-mail
Real-Time
Access
Services
Directory
Clusters
Applications
Miscellaneous
Licensing
WebMail
Pronto!
PBX
Pronto! | Module API | History
# Pronto! Module API ProntoCore library ProntoCore requests and messages Providing requests to other modules Managing modules Default Pronto modules `E-Mail module` `IM module` `Calendar module` `Telephony module` `Contacts module` `News module` `Music module` `Video module` `Files module` Extension points and extensions Default extension points `MainNavigator` `Prefs` `NewButton` `FileEditors` `SharingMethods` Preferences Accessing XIMSS channel Strings Properties Log User idle / present ProntoCode data format Quick Start Guide Creating module Debugging module: debugconfig.xml 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:

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

## 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-2012, Stalker Software, Inc.