Quick Start Guide: developing custom module

Note: this document provides step-by-step guide for simple custom module creation. For a complete information about Pronto API see Pronto documentation.

Pronto provides API that allows to add custom blocks of functionality into it. This blocks are called modules. Basic Pronto module consists of several files and resides in CommuniGate Pro server Skins (usually in "Pronto-" skin).

This guide provides instructions about how to create basic custom module, develop, debug and deploy it.

Note: all files used in this guide like debug build of Pronto can be found at http://communigate.com/CommuniGatePro/ProntoModuleAPI.html.

Note: make sure to use Flex SDK 3.2.0. More on module restrictions.

It is recommended to install Eclipse IDE 3.3 or higher and then install Abode Flex Builder as a plug-in.

Install Eclipse IDE

Visit downloads page on eclipse.org, download and install suitable package (now it is Eclipse Classic 3.5.0).

Install Flex Builder

Visit Flex Builder page on abode.com, download Flex Builder as Eclipse plug-in (try or buy it) and install.

Create new Flex Project:

1. Set project name:
   
2. Change main application file name to lowercase, here it is billing.mxml and add assets as a source folder:
   
3. Click Finish.

Open project properties and disable HTML wrapper generation:

Now close your project and open system file browser (ex. Explorer for Windows). Locate docs.tar.gz\Admin\API\Examples.tar.gz:

1. Copy all folders from Examples\MyModule example into our new project (ex. C:\Workspace\Billing\) (assets, libs, src)
2. Remove src/billing.mxml that was created by Flex Builder
3. Rename all files and packages according to the new project name:
   • mymodule.mxml to billing.mxml
   • mymodule.def to billing.def
   • com\myCompany\myModule to com\companyAbc\billing
   • com\myCompany\myModule\model\MyModuleModel.as to com\companyAbc\billing\model\BillingModel.as
   • and so on
4. Open "Billing" project in Flex Builder and refresh it:
   
5. Edit billing.def, billing.mxml and other files and replace all occurencies of "myCompany", "MyCompany", "myModule" and "MyModule" with new values. Note: all strings are case-sensitive.

   The fastest way to do this is to use "Replace All" option in "Search" tool (Ctrl + H).

Flex Builder will report several compiling errors. They all are about wrong naming, fix them.

At this moment your project should compile without errors and have the following structure:

In order to debug Pronto with your custom local module "Billing" inside:

1. Unpack files from Admin/API/Debug.tar.gz archive into new folder pronto in your project. It should contain default.html, pronto.swf and other files and folders. It is debug build of Pronto.
2. Find Flash Player system folder FlashPlayerTrust. Possible location of this folder is C:\Documents and Settings\Administrator\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust but it usually vary. Create text file with any name (ex. pronto.modules.txt) inside it and place pronto folder absolute path inside it:
   C:\Workspace\Billing\pronto
3. Open "Billing" project debug dialog:
   
4. Double-click on "Flex Application".
5. Create debug configuration:
   

Now check key issues:

1. C:\Workspace\Billing\pronto\debugconfig.xml - should specify correct server and <module>< node for your module:

   <debug>
       <!-- Change server to your own -->
   	<server host="talktoip.com" port="8100" secure="no"/>
   	<modules>
   	    <!-- List modules that you want to debug here -->
   	    
   	    <module src="C:/Workspace/Billing/bin-debug/billing.def" 
   			basePath="C:/Workspace/Billing/bin-debug/" />
   	</modules>
   </debug>

2. C:\Workspace\Billing\bin-debug\billing.def - should contain correct information:

   <module moduleId="com.companyAbc.billing.Billing" fileName="billing.swf" version="1" loadType="onDemand">
   	
   	<requirements>
   		<requirement option="HTTP"/>
   	</requirements>
   
   	<extensions>
   		<extension extensionName="com.companyAbc.billing.Billing"
   			extensionPointName="MainNavigator" preferredIndex="33" 
   			iconFileName="billingicon.png" label="Billing"/>
   	</extensions>
   
   </module>

Now you can start "Billing" project debug.

Troubleshooting

Internet Explorer shows toolbar each time debug starts.

It is security of IE. To avoide this problem in debug mode: Tools -> Internet options -> Advanced -> Security -> Allow active content to run in files on My Computer.

I do not see my module in navigation menu.

Check debugconfig.xml and .def files.

 Pronto logs most important actions during initialization in it's own log, click somewhere inside Pronto and press Ctrl + F12 to open "Log" window.

• Access XIMSS channel to work with user mail, IM, etc.
• Integrate your module into Pronto using extensions as you already did with MainNavigator extension point (see billing.mxml).
• You can use ProntoLib open-source library that is located in Admin\API\ProntoLib (see it's ASDoc) since it contains a lot of XIMSS and Pronto specific utilities.
• And many more in Pronto documentation.

Working with strings

Server provides dictionary of localized strings for many languages. You can view english strings using URL like http://server.com/SkinFiles/server.com/Pronto-/strings.xdata, for other languages strings.xdata should be changed to the language name ex. arabic.xdata.

Module usually access strings using getString() function from ProntoLib library.

Utilities

ProntoLib class Utils.as contains methods to work with dates and many more.

Export release build of your project. Upload billing.swf, billing.def, icons and other assets (if any) to CommuniGate Pro server skins. It can be done via WebAdmin or FTP, please consult your server administrator.