May
26

Getting Started With the Xcelsius 2008 SDK Topic 1: Common Items to Be Aware Of

In this multi-part series, we will enumerate fundamental pieces of the SDK and how to properly use them, including custom component development, property sheet development, component packaging and advanced component integration topics.

Let’s get started with a few common items to be aware of.

Dynamic Visibility

Although there is not a utility available in Xcelsius that can provide you with this common feature as an  inherent part of your component, it is possible to wire up dynamic visibility (albeit not  true Xcelsius dynamic visibility) to some extent.

You can obviously control your component’s visibility by setting its Boolean visible property, but what if your component should only be visible during design time (i.e. a data connector or something without a runtime UI), and if so,  how do you know when your component is in design mode in Xcelsius or in run time mode in Xcelsius? It’s relatively straightforward as long as you know what to use.  The function below, when queried will return true or false, indicating whether Xcelsius is in design mode or runtime/preview mode. Outside of components that do not have a runtime UI, this function is also helpful because often times developers don’t want their components to be invisible at design time unless they hide them on their own using the Xcelsius object browser. Whatever your case may be, you can leverage this simple function to determine runtime or design time status and then show or hide your component based on any logic and/or key/value pair comparison properties that your component may have.

This function could be simplified; it is pulled directly from the SDK samples as it very clearly illustrates the decision making. If the function returns true, you are in design time mode – if false, you’re in runtime mode.
isincanvas

Dynamic Visibility Caveats

eye

While you can wire up dynamic visibility for your component, it is not true Xcelsius dynamic visibility – i.e.  if you group your custom component with other native Xcelsius components, you may receive a runtime error if you’re trying to use group dynamic visibility. This is because Xcelsius components are inspected for certain dynamic visibility properties, and when your custom component is grouped and it gets checked, it will not have those properties, causing a possible runtime error (you’ll see the error if you’re running a debug version of the Flash Player). I’m not sure if this is going to be addressed/patched or not, but it’s good to be aware of so you can document and workaround as needed.

No Inheritance

I’ve mentioned this before but figured it bears repeating. Currently, it is not possible to inherit from Xcelsius components or to inherit theme colors or styles from your Xcelsius 2008 dashboard.

Watch Your Bindings/ Use Only What You Need

Only mark your component properties as bindable if needed. At design time and runtime, your component will be initialized by Xcelsius, which will cause bindings to fire.

For example, if you have a public property that you have exposed through the property sheet (a string value for instance) and your end user sets that property value at design time – if you have marked the property/variable as bindable in your custom component, the value that the user specified at design time may be replaced at first during runtime with a default or null value if a default value was specified for your property in code. It may sound confusing, but if you think it through it makes sense when you think about Flex bindings and how they operate – however, it can be frustrating (why aren’t my values sticking?!) if it’s not something you expected to happen. So in short, if you’re decorating your public properties with [Bindable], make sure that you need it and test out the effects to ensure that your component/property sheet integration works as you intended.

“Use only what you need” applies when establishing binding directions in your property sheet as well. Use input, output and both binding binding direction parameter values as is neccessary for your component to avoid any unexpected behaviors.

1-to-Many Bindings

It is possible to have 1-to-many bindings for a particular property as illustrated in the familiar chart series property sheet below. This is not yet a well documented feature and we will dive into this in future posts as it is an in-depth topic.
onetomany

Symmetric Public Properties

When establishing public properties in your custom component for property sheet communication, be sure to specify both get and set definitions for every public property you set up. Even if you would normally have it as a write or read-only property, it is advised that you specify both, or you may encounter design and/or run time errors when your component is initialized by Xcelsius.

For example, if you are exposing a simple Boolean property, get into the habit of specifying both a get and set function as illustrated below.

publicpropertyexample

Specify Your Styles

If you are creating a visual component such as a chart, gauge, background or other component with a UI, it is advised that you set all styles associated with that component to either their default values or to desired custom style values. This will help your component avoid gaining any unwanted style values from the dashboard parent application and will ensure that it looks as you intended it to in the Xcelsius environment.

Project Setup

I often see people setting up 2 projects per component – 1 for the property sheet and 1 for the corresponding component; because that is the way the SDK examples are set up for introductory clarity. I recommend that you establish projects and separate your code as it makes sense in your own context. Your Flex project could have 10 property sheets and 10 components; it really doesn’t matter as long as they are intuitively managed.

More tips, tricks and functional project code will be coming along in this series so check back frequently. Hopefully these starters will save you some of your valuable time.

Evan DeLodder is the Senior Software Engineer at Centigon Solutions focused on the development and application of cutting edge Rich Internet Application technologies in the Business Intelligence space. To learn more about him, please visit our new FleXcelsius page.

Tags: , , ,

5 Responses to “Getting Started With the Xcelsius 2008 SDK Topic 1: Common Items to Be Aware Of”

  1. Kalyan Verma says:

    Evan,

    This is super stuff. Keep it coming. How about publishing a book on the same. I’m sure you must be planning for it.

    Thanks Again. Looking forward to the rest of the posts in the series.

    Regards,
    Kalyan Verma

  2. Evan says:

    Hi Kalyan,

    Thanks, this series is something that I’m pleased to be presenting as it will eventually take a path into some more detailed source territory and useful scenarios.

    Based on developer feedback and my experiences as an Xcelsius SDK “ribbon cutter”, I think SDK development is certainly an area that deserves an official guide focused on delivering a deeper and more comprehensive overview of the Xcelsius SDK and its application.

    Regards,
    Evan DeLodder

  3. A book on this subject would be a great idea, and one which I think would be very popular.

    Regards
    Charles

  4. I am exporting a PNG file with a transparent background from photoshop and trying to import using the image component. the background comes up. I then tried doing the same from illustrator and it exports fine. But when importing into xcelsius a background shows up. Any recommendations?

  5. Saurabh Seth says:

    Wow !!! Waiting for 1-to Many Bindings post eagerly……..

Leave a Reply