Probably the most important thing to be mentioned is that custom flex components designed to be used as Xcelsius add-ons require to be compiled against Flex 2 SDK, latest being Flex 2.0.1 SDK with HotFix 3. You can’t use Flex 3/4 SDK and this haven’t changed with the latest Xcelsius 2008 SP3 version. I have no idea when this will change… Also Flex 2 SDK is not supported in the upcoming Flash Builder replacing Flex Builder.
Each Xcelsius add-on is based on two separate swf files:
1. Custom component within an Application container.
The actual flex component. It needs to be the only child of your main Application with both width and height set to 100%. All properties should be declared either as component styles or public variables inside this custom component. Application should be clean of any other mxml tags or actionscript code.
Timeline Chart component is a bit more complex than a regular chart because it has to handle coordination between two separate charts. Because of this a basic Caingorm framework was implemented. It doesn’t follow Adobe guidelines by the book nor does it use an external pre-built framework library but it has the same overall structure and logic: central model and controller, commands and views.
It also makes sense to check whether or not the component is displayed as a standalone published version or is part of the Xcelsius working canvas. If it’s on Xcelsius canvas, some functionality needs to be disabled like receiving end user events, disabling dynamic tooltips and so on. Otherwise the end user may try to resize the component on the canvas only to found himself interacting with the chart instead of controlling its size. You can check if a component is on Xcelsius canvas by checking for “inCanvas” global style.
2. Custom component interface within an Application container.
Contains all Xcelsius add-on interface logic. The interface will handle end-user interaction for customizing the component within Xcelsius. Possible actions are updating chart values and labels, changing font styles, colors, fills, etc. It is also called the add-on property sheet. This is the only place where Xcelsius SDK is being used to allow two-way communication between the component property sheet and the component itself.
In the beginning, the property sheet values are bind to the component values via a PropertySheetExternalProxy. Initial property sheet values are populated based on component default property and style values. Changes initiated by the user within the component interface are reflected in the component via the established bindings.
It’s up to the component itself to handle style changes by overriding existing UIComponent functions like styleChanged and updateDisplayList functions. Changes in public variables can be be handled via setter functions.
Testing the component.
Obviously you want to test the component in Xcelsius as late as possible. You don’t want to compile the component, build the add-on, re-install the add-on, finally test the add-on in Xcelsius. So chart data labels and values need to have an alternative source. In the case of Timeline Chart, ChartDataLoadCommand is responsible for loading an external XML file with some sample data when the component determines is not being used in an Xcelsius related environment.
Xcelsius add-on packager.
This small utility combines the custom component and custom component interface (both swf files) into an Xcelsius add-on xlx file. It also lets you define add-on properties like add-on name, details, author, license agreement, etc. Installing the add-on is only a matter of selecting File -> Manage Add-Ons -> Install Add-On within Xcelsius.