sample xcelsius practical guid

Ray Li and Evan DeLodder

Creating Dashboards with Xcelsius — Practical Guide

Bonn � Boston

5771 Book.indb 3 8/6/10 11:01:51 AM

http://www.sap-press.com

Contents at a Glance

1 Introduction to Xcelsius 2008 ................................................. 17

2 Get Familiar with Xcelsius 2008 ............................................. 31

3 Get Started .............................................................................. 77

4 UI Component Basics .............................................................. 91

5 UI Components – Advanced .................................................... 185

6 Data Connectivity Basics ........................................................ 293

7 Advanced Data Connectivity ................................................... 331

8 Special Features ...................................................................... 393

9 A Comprehensive Hands-On Example .................................... 439

10 Introducion to the Xcelsius SDK ............................................. 461

11 Get Started with Custom Component Basics ......................... 475

12 Implement Advanced Custom Add-On Component Features .................................................................................. 505

13 Hands-On: Develop Your Custom Add-On Component ......... 527

A Tips for Using Xcelsius in SAP BusinessObjects Enterprise or other SAP Environment ..................................... 545

B The Authors ............................................................................. 581

5771 Book.indb 5 8/6/10 11:01:51 AM

www.sap-press.com

7

Contents

Acknowledgments ..................................................................................... 15

1 Introduction to Xcelsius 2008 .................................................. 17

1.1 What’s Xcelsius? ......................................................................... 171.1.1 Installation ..................................................................... 181.1.2 Relationship with Excel .................................................. 191.1.3 History ........................................................................... 19

1.2 What Can Xcelsius 2008 Do? ...................................................... 191.2.1 Data Visualization Capabilities ........................................ 201.2.2 Data Connectivity Capabilities ........................................ 261.2.3 Distribution .................................................................... 27

1.3 Reasons to Choose Xcelsius ........................................................ 271.4 Xcelsius in the SAP BusinessObjects Portfolio .............................. 281.5 Summary .................................................................................... 29

2 Get Familiar with Xcelsius 2008 ............................................... 31

2.1 Menu ......................................................................................... 312.1.1 File ................................................................................. 312.1.2 Edit ................................................................................ 502.1.3 View .............................................................................. 512.1.4 Format ........................................................................... 562.1.5 Data ............................................................................... 592.1.6 Help ............................................................................... 62

2.2 Toolbar ....................................................................................... 642.2.1 Standard ........................................................................ 642.2.2 Export ............................................................................ 652.2.3 Themes .......................................................................... 652.2.4 Format ........................................................................... 662.2.5 Quick Start .................................................................... 662.2.6 Summary ........................................................................ 66

2.3 Components Browser .................................................................. 682.3.1 Category ........................................................................ 682.3.2 Tree ................................................................................ 69

5771 Book.indb 7 8/6/10 11:01:51 AM

www.sap-press.com

8

Contents

2.3.3 List ................................................................................. 702.4 Canvas ........................................................................................ 712.5 Embedded Excel Spreadsheet ...................................................... 712.6 Property Sheet ............................................................................ 722.7 Object Browser ........................................................................... 742.8 Summary .................................................................................... 75

3 Get Started ............................................................................... 77

3.1 Introduction ............................................................................... 773.2 Choose the Right UI Components ............................................... 783.3 Bind Data ................................................................................... 79

3.3.1 Bind Data for Pie Chart .................................................. 803.3.2 Enable Drill-Down for the Pie Chart ............................... 823.3.3 Bind Data for Label ........................................................ 84

3.4 Connect to External Data ............................................................ 853.5 Formatting .................................................................................. 853.6 Distribute the Output ................................................................. 883.7 Summary .................................................................................... 89

4 UI Component Basics ............................................................... 91

4.1 Working with Charts ................................................................... 924.1.1 Pie Chart ........................................................................ 924.1.2 Column Chart ................................................................. 1104.1.3 Line Chart ...................................................................... 1284.1.4 Bar Chart ........................................................................ 1364.1.5 XY Chart ........................................................................ 1374.1.6 Bubble Chart .................................................................. 1414.1.7 Area Chart ...................................................................... 144

4.2 Selectors ..................................................................................... 1474.2.1 Introduction to Xcelsius Selectors ................................... 1474.2.2 Select a Single Item ........................................................ 1474.2.3 Filter .............................................................................. 1534.2.4 Checkbox ....................................................................... 1574.2.5 Toggle Button ................................................................. 1584.2.6 Ticker ............................................................................. 158

5771 Book.indb 8 8/6/10 11:01:51 AM

www.sap-press.com

9

Contents

4.2.7 Picture Menus ................................................................ 1604.2.8 List Builder ..................................................................... 165

4.3 Represent a Single Value ............................................................. 1664.3.1 Introduction to Single-Value Components ...................... 1664.3.2 Slider ............................................................................. 1674.3.3 Progress Bar ................................................................... 1714.3.4 Dial and Gauge .............................................................. 172

4.4 Use Containers to Wrap Several Components .............................. 1764.4.1 When to Use a Container ............................................... 1764.4.2 How to Use a Container ................................................. 177

4.5 Build Backgrounds to Assist Layout ............................................. 1804.5.1 When to Use Backgrounds ............................................. 1804.5.2 How to Use Backgrounds ............................................... 181

4.6 Summary .................................................................................... 184

5 UI Components – Advanced ..................................................... 185

5.1 Advanced Charts ......................................................................... 1855.1.1 Stacked Column Chart .................................................... 1865.1.2 Stacked Bar and Area Chart ............................................ 1895.1.3 Combination Chart ......................................................... 1895.1.4 OHLC Chart .................................................................... 1915.1.5 Candlestick Chart ........................................................... 2025.1.6 Radar Chart .................................................................... 2035.1.7 Filled Radar Chart ........................................................... 2065.1.8 Tree Map ....................................................................... 208

5.2 Advanced Selectors ..................................................................... 2105.2.1 Accordion Menu ............................................................ 2105.2.2 Icon ............................................................................... 2175.2.3 Play Selector .................................................................. 2195.2.4 Calendar ........................................................................ 225

5.3 Advanced Single-Value Components ........................................... 2285.3.1 Dual Slider ..................................................................... 2295.3.2 Spinner .......................................................................... 2305.3.3 Play Control ................................................................... 2315.3.4 Value ............................................................................. 233

5.4 Displaying Data in a Table ........................................................... 2355.4.1 List View ........................................................................ 235

5771 Book.indb 9 8/6/10 11:01:51 AM

www.sap-press.com

10

Contents

5.4.2 Spreadsheet Table .......................................................... 2395.4.3 Grid ............................................................................... 243

5.5 Using Art .................................................................................... 2465.5.1 Image Component ......................................................... 2465.5.2 Shapes ........................................................................... 2485.5.3 Lines .............................................................................. 252

5.6 Use Maps for Geographical Representation ................................. 2535.6.1 Map Components .......................................................... 253

5.7 Web Connectivity ....................................................................... 2625.7.1 Connection Refresh Button ............................................ 2625.7.2 URL Button .................................................................... 2645.7.3 Reporting Services Button .............................................. 2685.7.4 Slide Show ..................................................................... 271

5.8 Others ........................................................................................ 2735.8.1 Local Scenario Button .................................................... 2735.8.2 Trend Icon ...................................................................... 2755.8.3 Trend Analyzer ............................................................... 2775.8.4 History ........................................................................... 2795.8.5 Print Button ................................................................... 2825.8.6 Reset Button .................................................................. 2835.8.7 Source Data ................................................................... 2845.8.8 Panel Set ........................................................................ 287

5.9 Summary .................................................................................... 292

6 Data Connectivity Basics .......................................................... 293

6.1 Embedded Excel Spreadsheet ...................................................... 2946.1.1 How to Use Excel ........................................................... 295

6.2 Import Data from an Excel File .................................................... 2986.2.1 When to Use .................................................................. 2986.2.2 How to Use ................................................................... 298

6.3 Security Issues Related to Accessing External Data ...................... 2996.4 XML Data ................................................................................... 301

6.4.1 When to Use XML Data ................................................. 3046.4.2 How to Use XML Date ................................................... 3056.4.3 Practice .......................................................................... 314

6.5 Web Service Connection ............................................................. 3226.5.1 When to Use a Web Service Connection ........................ 3226.5.2 How to Use a Web Service Connection ........................... 323

5771 Book.indb 10 8/6/10 11:01:52 AM

www.sap-press.com

11

Contents

6.6 Excel XML Map .......................................................................... 3266.6.1 When to Use an Excel XML Map .................................... 3276.6.2 How to Use an Excel XML Map ...................................... 328

6.7 Summary .................................................................................... 330

7 Advanced Data Connectivity .................................................... 331

7.1 Query as a Web Service .............................................................. 3317.1.1 When to Use Query as a Web Service ............................. 3337.1.2 How to Use Query as a Web Service ............................... 334

7.2 Live Office Connection ................................................................ 3397.2.1 When to Use SAP BusinessObjects Live Office

Connection .................................................................... 3407.2.2 How to Insert SAP BusinessObjects Reports to Excel ...... 3427.2.3 How to Use SAP BusinessObjects Live Office

Connection .................................................................... 3437.2.4 Practice .......................................................................... 348

7.3 Crystal Reports Data Consumer ................................................... 3517.3.1 When to Use the Crystal Reports Data Consumer

Connection .................................................................... 3527.3.2 How to Use the Crystal Reports Data Consumer

Connection .................................................................... 3527.3.3 Practice .......................................................................... 359

7.4 Flash Variables ............................................................................ 3627.4.1 When to Use Flash Variables .......................................... 3647.4.2 How to Use Flash Variables ............................................ 364

7.5 FS Command .............................................................................. 3687.5.1 When to Use FS Command ............................................ 3697.5.2 How to Use FS Command ............................................... 3697.5.3 Practice .......................................................................... 372

7.6 External Interface Connection ..................................................... 3757.6.1 When to Use an External Interface Connection ............... 3767.6.2 How to Use and External Interface Connection ............... 3767.6.3 Practice .......................................................................... 378

7.7 LCDS Connection ........................................................................ 3827.7.1 When to Use an LCDS Connection ................................. 3847.7.2 How to Use an LCDS Connection ................................... 384

7.8 Portal Data ................................................................................. 387

5771 Book.indb 11 8/6/10 11:01:52 AM

www.sap-press.com

12

Contents

7.8.1 When to Use Portal Data ................................................ 3877.8.2 How to Use Portal Data .................................................. 388

7.9 Summary .................................................................................... 391

8 Special Features ........................................................................ 393

8.1 Drill-Down ................................................................................. 3938.1.1 When to Use Drill-Down ................................................ 3948.1.2 How to Use Drill-Down .................................................. 3958.1.3 Drill Down from One Chart to Another .......................... 3968.1.4 Drill-Down on the Same Chart ....................................... 399

8.2 Make Smart Use of Dynamic Visibility ......................................... 4058.2.1 When to Use Dynamic Visibility ..................................... 4068.2.2 How to Use Dynamic Visibility ....................................... 4088.2.3 Practice .......................................................................... 411

8.3 Alerts .......................................................................................... 4168.3.1 How to Use Alerts .......................................................... 4178.3.2 Practice .......................................................................... 418

8.4 Export ......................................................................................... 4248.4.1 How to Use the Export Functionality .............................. 425

8.5 Themes and Colors ..................................................................... 4308.5.1 How to Use Themes and Color ....................................... 430

8.6 Summary .................................................................................... 438

9 A Comprehensive Hands-On Example ...................................... 439

9.1 Planning the Dashboard .............................................................. 4419.1.1 Plan the Workflow ......................................................... 4419.1.2 Plan the UI ..................................................................... 442

9.2 Preparing Data ............................................................................ 4439.2.1 The U.S. Map ................................................................. 4449.2.2 The Gauge ...................................................................... 4459.2.3 The Column Chart .......................................................... 4459.2.4 The Line Chart ................................................................ 4479.2.5 The Radio Button ........................................................... 4509.2.6 The Pie Chart ................................................................. 450

9.3 Organizing Data in Excel ............................................................. 4519.4 Designing the Dashboard ............................................................ 455

5771 Book.indb 12 8/6/10 11:01:52 AM

www.sap-press.com

13

Contents

9.4.1 Position the UI Components ........................................... 4569.4.2 Import the Excel File ...................................................... 4569.4.3 Connect to External Data ............................................... 4589.4.4 Adjust the Appearance ................................................... 459

9.5 Summary .................................................................................... 460

10 Introduction to the Xcelsius SDK ............................................. 461

10.1 About the Xcelsius SDK .............................................................. 46110.2 About Flex .................................................................................. 46210.3 When to Use the SDK ................................................................. 46310.4 How to Use the SDK ................................................................... 46410.5 What Can be Done with the SDK? .............................................. 46810.6 SDK Best Practices ...................................................................... 47110.7 Summary .................................................................................... 473

11 Get Started with Custom Component Basics .......................... 475

11.1 Developing Basic Add-On Property Sheets .................................. 47511.1.1 Property Sheet Data Binding .......................................... 47611.1.2 Explicitly Setting Property Values ................................... 47911.1.3 Explicitly Getting Property Values ................................... 48011.1.4 Property Sheet Styling .................................................... 48011.1.5 Basic Property Sheet Overview ...................................... 48011.1.6 Proxy.Bind Explained ...................................................... 490

11.2 Developing Basic Add-On Components ...................................... 49111.2.1 Custom Component Code Walkthrough ......................... 491

11.3 Creating Basic Component Packages ........................................... 50011.4 Summary .................................................................................... 503

12 Implement Advanced Custom Add-On Component Features ................................................................................... 505

12.1 Implementing Advanced Property Sheet Features ....................... 50512.1.1 Sub-Element Binding ...................................................... 50512.1.2 Persisting Property Sheet Values ..................................... 50812.1.3 Retrieving Persisted Property Sheet Values ..................... 50912.1.4 Setting Custom Component Property Values .................. 510

5771 Book.indb 13 8/6/10 11:01:52 AM

www.sap-press.com

14

Contents

12.1.5 Retrieving Custom Component Property Values .............. 51012.1.6 Generating Reusable Property Sheet Patterns ................. 51012.1.7 Communicating with External Data Services ................... 51312.1.8 Implementing Advanced Component Features ............... 51312.1.9 Additional Packaging Features ........................................ 524

12.2 Summary .................................................................................... 526

13 Hands-On: Develop Your Custom Add-On Component .......... 527

13.1 Custom Properties Explained ...................................................... 52713.2 Creating the Flex Component and Property Sheet Project ........... 52813.3 Creating the Flex Property Sheet ................................................. 53413.4 Creating the Flex Component ...................................................... 54013.5 Creating the Flex Test Container .................................................. 54313.6 Creating the Packager and Xcelsius XLX Add-On ......................... 54313.7 Summary .................................................................................... 544

Appendices ..................................................................................... 545

A Tips for Using Xcelsius in SAP BusinessObjects Enterprise or other SAP Environment ........................................................................ 545

B The Authors ......................................................................................... 581

Index ......................................................................................................... 583

5771 Book.indb 14 8/6/10 11:01:52 AM

www.sap-press.com

475

This chapter will provide a detailed walkthrough of a full property sheet and corresponding custom Flex component for Xcelsius.

Get Started with Custom 11 Component Basics

In this chapter, we will take a closer look into the core concepts of Xcelsius SDK development. We will cover the foundational pieces that compose a custom com-ponent and step through working concrete examples to get you up to speed and prepared for more advanced topics.

Let’s start by gaining an understanding of the backbone of a custom component integration which facilitates all component data flow and binding communication; the custom component Property Sheet.

Developing Basic Add-On Property Sheets11.1

Conceptually, Property Sheets will seem very similar to a developer who is familiar with Xcelsius and interacting with the Xcelsius components offered in the default component library. A Property Sheet is essentially a self-contained Flex application that serves as both a User Interface control and communication proxy between the Xcelsius design environment and your custom component’s publicly exposed properties that you wish to give users control over.

Property sheets can serve many functions and since they are Flex-based applica-tions, Property Sheets enable the custom component developer to exercise creativ-ity in designing the most effective User Interface(s) that the business users who leverage the custom component will ultimately interact with.

The basic primary Property Sheet features that we will cover before moving to more advanced Property Sheet features are:

Property Data BindingEE

Property Value Setting/GettingEE

5771 Book.indb 475 8/6/10 11:05:27 AM

www.sap-press.com

476

Get Started with Custom Component Basics11

Property Sheet Data Binding11.1.1

Perhaps the most powerful feature exposed by the Xcelsius SDK is the ability to bind to a variety of data ranges in the underlying Xcelsius Excel data model, to public properties that you specify in your custom Flex component. Binding types come in a handful of varieties and enable custom components to read, write or read and write to the Xcelsius Excel model in every way that is needed to funda-mentally communicate with the two-dimensional data model (rows and columns) that is supported by the Xcelsius implementation of the Excel model.

Bindings can be adapted to suit a variety of basic to advanced use cases. In this sec-tion we will review the basic concepts of data binding that a custom component developer is most likely to encounter. Below are the fundamental concepts offered by the Xcelsius SDK binding mechanism.

Binding call example that specifies a read-only 2 dimensional array property bind-ing of a custom component’s xcChartData property:

proxy.bind(“xcChartData”, null, bindingID, BindingDirection.OUTPUT, “”,

OutputBindings.ARRAY2D);

Binding Directions and Data Flow

When establishing a binding between Xcelsius and one of your custom compo-nent’s properties, you are able to specify whether your property should be treated as read-only, write-only, or as both a read and write property.

Reading Values from the Spreadsheet

To specify your component’s property as a read-only property, meaning that your property will be a consumer of data from the Xcelsius model, you will need to specify a binding direction type of “OUTPUT”, as described below. By subscribing to the Xcelsius model through binding as a read-only or OUTPUT consumer, your component’s property value will change any time the range or cell data your cus-tom component is bound to in the Xcelsius data model changes, both at runtime as well as design time in the Xcelsius environment.

To access this binding direction type you may import the xcelsius.binding.BindingDi-rection namespace into your Property Sheet application. Below is the fully qualified path to the OUTPUT type.

xcelsius.binding.BindingDirection.OUTPUT

5771 Book.indb 476 8/6/10 11:05:27 AM

www.sap-press.com

477

Developing Basic Add-On Property Sheets 11.1

Writing Values to the Spreadsheet

To specify your component’s property as a write-only property, meaning that your property will be a provider of data to the Xcelsius model, you will need to specify a binding direction type of “INPUT”, as described below. By subscribing to the Xcel-sius model through binding as a write-only or INPUT consumer, your component’s property value will update the cell or range that it is bound to in the data model any time the data in your bound custom component property changes.

To access this binding direction type you may import the xcelsius.binding.Binding-Direction namespace. Below is the fully qualified path to the INPUT type.

xcelsius.binding.BindingDirection.INPUT

Writing Values to and Reading Values from the Spreadsheet

To specify your component’s property as both a read and write property, meaning that your property will be a provider and consumer of data via the Xcelsius Excel model, you will need to specify a binding direction type of “BOTH”, as described below. By subscribing to the Xcelsius model in this manner, your component’s property value will update the cell or range that it is bound to in the data model any time the data in your custom component property changes, and conversely, your component’s property value will change anytime the Xcelsius Excel model is updated.

To access this binding direction type you may import the xcelsius.binding.Binding-Direction namespace. Below is the fully qualified path to the BOTH type.

xcelsius.binding.BindingDirection.BOTH

Binding Types

Whether your custom component’s property is read, write or both, it will need to specify what type of value it is in the proxy.bind() operation so the SDK can properly handle its data flow.

The options for InputBindings and OutputBindings are as follows in Figures 11.1 and 11.2:

5771 Book.indb 477 8/6/10 11:05:27 AM

www.sap-press.com

478


InputBinding optionsFigure 11.1

OutputBinding optionsFigure 11.2

InputBindings ARRAY EE

A type of ARRAY indicates that your custom component’s property will be bound to and able to write to a set of cells in either a single column or row.

ARRAY2D EE

A type of ARRAY2D indicates that your custom component’s property will be bound to and able to write to a set of cells in a row and column format.

SINGLETON EE

A type of SINGLETON indicates that your custom component’s property will be bound to and able to write to a single cell.

5771 Book.indb 478 8/6/10 11:05:28 AM

www.sap-press.com

479


OutputBindings ARRAY EE

A type of ARRAY indicates that your custom component’s property will be bound to and able to read from a set of cells in either a single column or row.

ARRAY2D EE

A type ofARRAY2D indicates that your custom component’s property will be bound to and able to read from a set of cells in a row and column format.

SINGLETON EE

A type of SINGLETON indicates that your custom component’s property will be bound to and able to read from a single cell.

ARRAY2DXYOBJECTS EE

A type of ARRAY2DXY indicates that your custom component’s property will be bound to and able to read multiple columns or rows of cells output as a 2D array of Objects with x and y properties.

SORTED_OBJECT EE

A type of SORTED_OBJECT indicates that your custom component’s property will be bound to and able to read a sorted object representation of a 2D table.

Explicitly Setting Property Values11.1.2

Aside from the need to bind custom component properties to data in the Xcelsius Excel model, the ability also exists to read and write to a custom component’s property directly through the Property Sheet, thus bypassing the Excel model altogether.

An example of this functionality would be if you have a Flex ColorPicker control on your Property Sheet that is responsible for setting a color property on your component. Assuming you had a custom Flex Canvas component with a public property named “xcBackgroundColor”, you could write a value to that property by using the following command specified inline in the ColorPicker’s “change” event handler, where “cp” represents the ID of your MXML ColorPicker in the Flex Property Sheet.

private var proxy:PropertySheetExternalProxy = new PropertySheetExternalProxy();

<mx:ColorPicker left=”19” top=”175” id=”cp”

change=”proxy.setProperty(‘xcChartColor’,cp.selectedColor)”/>

5771 Book.indb 479 8/6/10 11:05:28 AM

www.sap-press.com

480


Explicitly Getting Property Values11.1.3

The ability to extract values from your custom component at Property Sheet design time exists as well and will be covered in the chapter Implementing Advanced Custom Add-On Component Features.

Property Sheet Styling11.1.4

While certain factors need to be considered for styling custom components, Prop-erty Sheet styling is direct and enables developers to leverage common styling practices in Flex such as style sheet references, inline style directives and embed-ded style sheets.

Basic Property Sheet Overview 11.1.5

With some basic Property Sheet concepts in mind, let’s take a walk through a func-tional example that highlights some of the fundamental aforementioned features. The full Property Sheet code is listed in breakout form of the code and accompany-ing code explanations in order from top to bottom.

This Property Sheet is designed as a basic example that is used to control a basic Flex AreaChart custom component with a handful of public properties. The full sample source code for the corresponding custom component is listed in the fol-lowing section in this chapter: Developing Basic Add-On Components.

The image below in Figure 11.3 highlights the overall end result of the following Property Sheet and Component walk through by displaying the component, con-nected to data, and the data layout, inside of the Xcelsius designer.

Property Sheet Code Walkthrough

Main property sheet initialization event handlerEE

Fundamental SDK import statementsEE

Private SDK variablesEE

Supporting SDK functionsEE

Proxy.Bind dissectedEE

5771 Book.indb 480 8/6/10 11:05:28 AM

www.sap-press.com

481


Custom Component and Property Sheet End ResultFigure 11.3

Property Sheet in Design ModeFigure 11.4

Property Sheet Application Complete Event Listener<?xml version=”1.0” encoding=”utf-8”?><mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute” applicationComplete=”init();”>

5771 Book.indb 481 8/6/10 11:05:29 AM

www.sap-press.com

482


On line 2 of our Property Sheet which is a basic Flex Application MXML file, we listen for the native Flex Application event of “applicationComplete”. When this event is triggered it calls our init() function. In the init() function, we perform the routine task of initializing and executing the basic Xcelsius SDK event listeners and callback functions needed to perform our custom component data binding and value setting tasks.

Fundamental SDK Import StatementsThe import statements below provide us with a reference to the foundational classes and utilities in the SDK needed for our basic Property Sheet application.

<mx:Script><![CDATA[import mx.containers.*;import mx.controls.*;import mx.core.Container;import mx.events.FlexEvent;import xcelsius.binding.BindingDirection;import xcelsius.binding.tableMaps.input.InputBindings;import xcelsius.binding.tableMaps.output.OutputBindings;import xcelsius.propertySheets.impl.PropertySheetExternalProxy;import xcelsius.propertySheets.interfaces.PropertySheetFunctionNamesSDK;

Below, we call out and explain the import statements that are specifically related to the SDK.

import xcelsius.binding.BindingDirection;

The BindingDirection import statement enables you to call on Binding Direction constants from the Xcelsius SDK. The Binding Direction options (INPUT, OUT-PUT, BOTH) specify the direction of data flow between your Xcelsius component properties and the Xcelsius Excel data model when performing a bind operation through the SDK.

import xcelsius.binding.tableMaps.input.InputBindings;

The InputBindings import statement enables you to call on Input Binding con-stants from the Xcelsius SDK. The Input Binding options (ARRAY, ARRAY2D, SIN-GLETON) specify the type of data range you wish to bind to between your Xcelsius component properties and the Xcelsius Excel data model when performing a bind operation through the SDK. InputBindings should be specified when a custom component property needs to input values into the Xcelsius Excel model.

5771 Book.indb 482 8/6/10 11:05:29 AM

www.sap-press.com

483


import xcelsius.binding.tableMaps.output.OutputBindings;

The OutputBindings import statement enables you to call on Output Binding con-stants from the Xcelsius SDK. The Output Binding options (ARRAY, ARRAY2D, SIN-GLETON) specify the type of data range you wish to bind to between your Xcelsius component properties and the Xcelsius Excel data model when performing a bind operation through the SDK. OutputBindings should be specified when a custom component property needs to read values from the Xcelsius Excel model.

import xcelsius.propertySheets.impl.PropertySheetExternalProxy;

The PropertySheetExternalProxy import statement provides access to the Prop-ertySheetExternalProxy class which is the backbone of the SDK integration per-forming all binding and value operations between the Property Sheet and custom component.

import xcelsius.propertySheets.interfaces.PropertySheetFunctionNamesSDK;

The PropertySheetFunctionNamesSDK import statement provides access to a set of constants that tie to Xcelsius SDK function names.

Basic Private SDK VariablesThe 3 private variables defined in this section are key to managing custom compo-nent property data binding and property value setting through the SDK.

private var proxy:PropertySheetExternalProxy = new PropertySheetExternalProxy(); private var propertyToBind:String;

private var currentBindingID:String;

Below, we call out and explain the primary private variables related to the SDK.

private var proxy:PropertySheetExternalProxy

The proxy variable is responsible for performing the job that its class name indi-cates; to serve as a proxy between the custom component’s properties and the Property Sheet. This variable is responsible for all key communication, property data binding and value setting in a custom component Property Sheet.

private var propertyToBind:String;

The propertyToBind variable serves as a string value that is responsible for holding the name of the custom component property that is currently being bound to dur-ing user-initiated binding operations. This value allows the developer to manage

5771 Book.indb 483 8/6/10 11:05:29 AM

www.sap-press.com

484


UI controls, data binding for the given property, and any other housekeeping or special functionality associated with the property. This variable is used primarily in the initiateBind and continueBind functions listed in the following section Sup-porting SDK functions.

private var currentBindingID:String;

The currentBindingID variable serves as a string value that is responsible for hold-ing the binding id of the custom component property that is currently being bound to during binding operations. This value allows the proxy to manage data bindings for the given property. This variable is used primarily in the initiateBind and con-tinueBind functions listed in the following section Supporting SDK functions.

Supporting SDK FunctionsA few common functions can be found across the majority of Property Sheet implementations. Those common functions are also included in this particular source code walkthrough as follows.

Initialize ValuesThe initValues function is responsible for retrieving the custom component’s prop-erty values at property sheet initialization time and populating the Property Sheet’s User Interface controls with their respective property values. In this particular implementation, we retrieve the 3 values exposed by our custom component and loop through them to initialize their corresponding property sheet controls. Listed below is the function code.

// Initializes Property Sheet on load to show the current Xcelsius custom component property/style value.private function initValues():void{ //Process the array of values for the Xcelsius custom //component properties. var propertyValues:Array = proxy.getProperties( [“xcChartData”, “xcChartSeries”, “xcChartColor”]); var propertyValuesLength:int = (propertyValues != null ? propertyValues.length : 0); for (var i:int=0; i < propertyValuesLength; i++) { // Get the property name and value. var propertyObject:Object = propertyValues[i]; var propertyName:String = propertyObject.name;

5771 Book.indb 484 8/6/10 11:05:29 AM

www.sap-press.com

485


var propertyValue:* = propertyObject.value;

// Process the property by name, either show the //value or show the cell address if bound to the //Excel spreadsheet. var bindingText:String = “”; switch (propertyName) { case “xcChartData”: bindingText= getPropertyBindDisplayName(propertyName); if (bindingText != null) { // When bound the user cannot edit the value. tiChartData.enabled = false; // Show the address we are bound to. tiChartData.text = bindingText; } else { tiChartData.text = “”; } break; case “xcChartSeries”: bindingText = getPropertyBindDisplayName(propertyName); if (bindingText != null) { tiChartSeries.enabled = false; tiChartSeries.text = bindingText; } else { tiChartSeries.text = “”; } break; case “xcChartColor”: cpChartColor.selectedColor = propertyValue; break; default: break; } }}

5771 Book.indb 485 8/6/10 11:05:30 AM

www.sap-press.com

486


Get Bound Property Display Names The getPropertyBindDisplayName function is a utility function that is responsible for returning the Excel range address that a given custom component property is bound to once a user-initiated binding operation has been completed. This cell address value is traditionally used in all custom Xcelsius components to visually indicate to the user through a text input control, where in the Excel model the property is bound to. Listed below is the function code.

// Returns the bind display name or null if not bound.private function getPropertyBindDisplayName(propertyName:String):String{ // Get the array of bindings for this property. var propertyBindings:Array = proxy.getBindings([propertyName]); if ((propertyBindings != null) && (propertyBindings.length > 0) && (propertyBindings[0].length > 0)) { // We have at least one binding for this //property so pick the 1st one. // Note: [0][0] is 1st property in the array, //then 1st binding for that property. var bindingID:String = propertyBindings[0][0]; return proxy.getBindingDisplayName(bindingID); } return null;}

Initiating End-User Interaction Binding Operations The initiateBind function is a utility function that is responsible for launching the Xcelsius Binding Window as shown in Figure 11.5 and Excel range address that a given custom component property is bound to when the binding button for a particular property is clicked. This function allows the user to select or modify the range that a custom component’s property is bound to. Listed below is the func-tion code needed to launch this utility to initiate data binding operations for a given custom component property.

Initiate Bind WindowFigure 11.5

5771 Book.indb 486 8/6/10 11:05:30 AM

www.sap-press.com

487


// Allows the user to select the Excel spreadsheet cell //to bind to an Xcelsius custom component property.private function initiateBind(propertyName:String):void{ //If there is an existing binding for this property //show that in the Excel binding selection window. //Store the currentBindingID (null if there is no //current binding), we need this for “continueBinding”.

currentBindingID = null; var propertyBindings:Array = proxy.getBindings([propertyName]); if ((propertyBindings != null) && (propertyBindings.length > 0)) { //Use the 1st binding address for the property. currentBindingID = propertyBindings[0]; }

//Store the name of the property that we are binding, //we need this when we “continueBinding”. propertyToBind = propertyName;

//Let the user choose where to bind to in the //Excel spreadsheet. proxy.requestUserSelection(currentBindingID);}

Finalizing User-Initiated Binding OperationsThe continueBind function is a function called as a result of the user clicking the “OK” button in the Xcelsius binding control in Figure 11.6 once they have selected the desired range they would like to bind the custom component property to. This function performs the fi nal steps via the “proxy” variable, needed to establish a binding of any type between the Xcelsius Excel model and a custom component property. Listed below is the function code needed to fi nalize or commit a data binding operation for a given custom component property. The remainder of the MXML code for this source code example is listed below the continueBind func-tion code as well.

Clicking OK to Finalize Binding OperationFigure 11.6

5771 Book.indb 487 8/6/10 11:05:30 AM

www.sap-press.com

488


// Completes the binding when the user has finished selecting //the cell to bind to or cleared the binding.private function continueBind(bindingID:String):void{ // Define common variables here. var propertyName:String = propertyToBind; var propertyValues:Array; var propertyObject:Object; var bindingAddresses:Array; // Clear any existing bindings - so we can re-bind. if (currentBindingID != null) { proxy.unbind(currentBindingID); currentBindingID = null; }

// Process the property binding. switch (propertyName) { case “xcChartData”: //User explicitly cleared binding, //do not create another. if ((bindingID == null) || (bindingID == “”)) { //Fill the chart with an empty dataset propertyValues = proxy.getProperties([propertyName]); propertyObject = propertyValues[0]; //Make sure we set the property //on the component as well. proxy.setProperty(propertyName, propertyObject.value); return; } //Display the range address. tiChartData.text = proxy.getBindingDisplayName(bindingID);

proxy.bind(“xcChartData”, null, bindingID,

5771 Book.indb 488 8/6/10 11:05:30 AM

www.sap-press.com

489


BindingDirection.OUTPUT, “”, OutputBindings.ARRAY2D); break; case “xcChartSeries”: //User explicitly cleared binding, //do not create another. if ((bindingID == null) || (bindingID == “”)) { propertyValues = proxy.getProperties([propertyName]); propertyObject = propertyValues[0]; proxy.setProperty(propertyName, propertyObject.value); return; }

// Display the range address. tiChartSeries.text = proxy.getBindingDisplayName(bindingID); proxy.bind(“xcChartSeries”, null, bindingID, BindingDirection.OUTPUT, “”, OutputBindings.ARRAY2D); break; default: break; } }]]></mx:Script> <mx:Canvas minWidth=”268” minHeight=”350” width=”100%” height=”100%” backgroundColor=”#FFFFFF”> <mx:Label x=”10” y=”22” text=”Chart Data”/> <mx:HRule y=”39” height=”10” right=”10” left=”10”/> <mx:TextInput id=”tiChartData” y=”57” right=”42” left=”10”/> <mx:Button y=”56” right=”10” width=”24” click=”initiateBind(‘xcChartData’);” icon=”@Embed(‘com/assets/bind to cell.png’)”/> <mx:Label x=”10” y=”87” text=”Chart Series”/> <mx:Label x=”10” y=”152” text=”Chart Color”/> <mx:HRule y=”104” height=”10” right=”10” left=”10”/>

5771 Book.indb 489 8/6/10 11:05:30 AM

www.sap-press.com

490


<mx:TextInput id=”tiChartSeries” y=”122” right=”42” left=”10”/> <mx:Button y=”121” right=”10” width=”24” click=”initiateBind(‘xcChartSeries’);” icon=”@Embed(‘com/assets/bind to cell.png’)”/> <mx:ColorPicker left=”19” top=”175” id=”cpChartColor” change=”proxy.setProperty(‘xcChartColor’, cpChartColor.selectedColor)”/> </mx:Canvas></mx:Application>

Proxy.Bind11.1.6 Explained

The Xcelsius SDK bind function currently accepts 10 parameters, the last 5 of which are optional. Let’s take a look at the fundamental first 5 parameters, in order.

Property1.

Chain2.

BindingID3.

Direction4.

InputMap5.

OutputMap6.

proxy.bind(“xcChartData”, <- Propertynull, <- ChainbindingID, <- BindingIDBindingDirection.OUTPUT, <- Direction“”, <- InputMapOutputBindings.ARRAY2D <- OutputMap);

Property EE

The name of the custom component property to be bound

ChainEE An alternate array argument usually left blank for normal binding scenarios. This chain is usually reserved for Sub Element Binding.

BindingIDEE The Xcelsius-generated BindingID of the custom component property to be bound

5771 Book.indb 490 8/6/10 11:05:30 AM

www.sap-press.com

491

Developing Basic Add-On Components 11.2

Direction EE

The BindingDirection constant that indicates whether the property is read, write, or read and write

InputMapEE The InputBindings constant that indicates whether the property is:

SINGLETON, ARRAY OR ARRAY2D

OutputMap EE

The OutputBindings constant that indicates whether the property is:

SINGLETON, ARRAY, ARRAY2D, ARRAY2DXYOBJECTS or SORTED_OBJECT

Developing Basic Add-On Components11.2

With a basic Property Sheet implemented and connecting to our properties exposed by our custom component, we will take a look at how the custom component’s public properties are exposed, consumed, set, and how they process their data output flow from Xcelsius, where applicable. The full component code is listed in breakout form of the code and accompanying code explanations in order from top to bottom.

This particular custom component is designed as a basic example that leverages a base Flex charting component, CartesianChart, to expose a simple yet powerful and highly adaptable chart that allows for multiple series types to be combined in a single chart implementation.

Custom Component Code Walkthrough11.2.1

Main component initialization event handlerEE

Private VariablesEE

Public Chart Color VariableEE

Public Chart Series VariableEE

Public Chart Data VariableEE

Chart Building FunctionEE

Tooltip FunctionEE

MXML MarkupEE

5771 Book.indb 491 8/6/10 11:05:30 AM

www.sap-press.com

492


Main Component Initialization Event Handler and Import Statements

On line 2 below, we listen for the native Flex Canvas event of “creationComplete”. When this event is triggered, in the function buildSeries() we perform the fun-damental operation of the component, which is to build up the Chart’s data and series. Listed below is the complete import code.

<?xml version=”1.0” encoding=”utf-8”?><mx:Canvas verticalScrollPolicy=”off” creationPolicy=”all” creationComplete=”buildSeries()” horizontalScrollPolicy=”off” xmlns:mx=”http://www.adobe.com/2006/mxml” width=”400” height=”400”> <mx:Script> <![CDATA[ import mx.charts.series.ColumnSet; import mx.graphics.RadialGradient; import mx.graphics.LinearGradient; import mx.managers.ToolTipManager; import mx.charts.renderers.LineRenderer; import mx.charts.renderers.CircleItemRenderer; import mx.charts.series.AreaSeries; import mx.charts.series.LineSeries; import mx.graphics.Stroke; import mx.charts.series.ColumnSeries; import mx.graphics.GradientEntry; import mx.collections.ArrayCollection;

Private Variables

The private variable _columnSet is responsible for clustering any specified Col-umnSeries for our Cartesian Chart. The private variable _xcChartData is a Bindable ArrayCollection which serves as our Cartesian Chart’s data provider. In the MXML code listed lastly in this section under MXML Markup: Grid Lines and Cartesian Chart, the Cartesian Chart’s dataProvider property is bound to the _xcChartData variable. Listed below are the private variables for our basic component.

private var _columnSet:ColumnSet = new ColumnSet();

[Bindable]private var _xcChartData:ArrayCollection = new ArrayCollection();

Public Chart Color Variable- xcChartColor

The public variable xcChartColor is set up as a read and write variable and in each operation, it is responsible for setting or getting our Bindable internal variable _

5771 Book.indb 492 8/6/10 11:05:30 AM

www.sap-press.com

493


xcChartColor. In the MXML code listed lastly in this section under MXML Markup: Grid Lines and Cartesian Chart, our Cartesian Chart’s color property is bound to this private variable which controls the color property of the chart. Listed below is the public property function code.

[Bindable]private var _xcChartColor:Number = 0x000000; public function get xcChartColor():Number { return _xcChartColor; } public function set xcChartColor(value:Number):void { _xcChartColor = value;; }

Public Chart Series Variable

The public variable xcChartSeries is set up as a read and write variable and in each operation, it is responsible for setting or getting our internal variable _ xcChart-Series. In our Property Sheet, we have this variable defined as a 2D Array con-sumer and each time the public variable is set, we cycle through this 2D Array variable to build the chart series for our Cartesian Chart. Note that the function buildSeries() is called every time the xcChartSeries public set function is called, enabling the chart to completely redesign itself at Xcelsius runtime anytime the Xcelsius dashboard designer decides it should be redesigned, making it highly adaptable. Listed below is the function code.

private var _xcChartSeries:Array = new Array(); public function get xcChartSeries():Array { return _xcChartSeries; }

public function set xcChartSeries(value:Array):void { try { _xcChartSeries = value; buildSeries(); } catch(e:Error) { trace(e.getStackTrace());

5771 Book.indb 493 8/6/10 11:05:30 AM

www.sap-press.com

494


} }

Public Chart Data Variable

The public variable xcChartData is set up as a read and write variable and in each operation, it is responsible for setting or getting our internal variable _ xcChart-Data. In our Property Sheet, we have this variable defined as a 2D Array con-sumer and each time the public variable is set, we cycle through this 2D Array variable to build the data for our Cartesian Chart. Note that the building of the data is called every time the xcChartData public set function is called. Notice that we treat a 2D Array of data output from Xcelsius exactly like any other 2D Array would be treated in ActionScript. We access the data in Xcelsius by looping over the data, referencing rows and invidual cells by using their ordinal position, i.e. _ xcChartData[rowPosition][columnPosition] = a single cell in the Xcelsius Excel data model.

In this particular case, we always extract the user-specified series name for a given set of data, at position 0 on each row in the data. For brevity’s sake, we then dynamically roll through each cell in any given row from position 1-N, to extract data values and associated tooltips. The data and tooltips values are specified as colon-separated in each given cell in the Xcelsius Excel model, i.e. [data:tooltip] or 5,000:My Tooltip. Listed below is the function code.

public function get xcChartData():Array{ return [];}/***Cycle through the 2D data Array, *building data for each series***/public function set xcChartData(value:Array):void{ //Row[0]=SeriesName //Row[0-N]=Data:HTMLTooltip _xcChartData.removeAll(); try { var columnStart:int = 0; var columnEnd:int = value[0].length; //Append each dataset to a

5771 Book.indb 494 8/6/10 11:05:30 AM

www.sap-press.com

495


//given month (month = key to each row) for (var i:int=columnStart; i<columnEnd; i++) { var data:Object = new Object(); data.yLabel = value[0][i]; if(data.yLabel == “” || data.yLabel == null) continue; //Build data for each month for (var i2:int = 1;i2<value.length;i2++) { //cell content format = //[dataValue : toolTip]; var cell:String = String(value[i2][i]); var seriesName:String = value[i2][0]; var dataValue:Number = Number(cell.substring( 0,cell.indexOf(“:”))); var toolTip:String = cell.substring( cell.indexOf(“:”) + 1, cell.length); data[seriesName]= dataValue; data[seriesName + data.yLabel] = toolTip; } _xcChartData.addItem(data); } } catch(e:Error) { trace(e.getStackTrace()); }}

Chart Building Function

The buildSeries function is responsible for looping through our publicly set private variable, xcChartSeries. In our Property Sheet, we have this variable defined as a 2D Array consumer and each time the public variable is set, we cycle through this 2D Array variable to build the series for our Cartesian Chart.

Notice that we treat a 2D Array of data output from Xcelsius exactly like any other 2D Array would be treated in ActionScript. We access the data in Xcelsius by loop-ing over the data, referencing rows and individual cells by using their ordinal

5771 Book.indb 495 8/6/10 11:05:31 AM

www.sap-press.com

496


position, i.e. _ xcChartSeries [rowPosition][columnPosition] = a single cell in the Xcelsius Excel data model.

For readability’s sake, we have created an intermediary variable, called “series” that is an Array. Essentially, the series variable represents a row of data from the Xcelsius model and each cell in the row provides us with a singular piece of infor-mation about the type of series the user wants to see on the chart and how they want that series to be named and represented through the CartesianChart. In this particular case, we require the user to place the series type in position 0, the series name in position 1, the series color in position 2 and the series alpha in position 3 as show below.

var series:Array = _xcChartSeries[i]; RA row of data from Xcelsius

var seriesType:String = series[0]; RA cell (#1) of data from Xcelsius

var seriesName:String = series[1]; RA cell (#2) of data from Xcelsius

var seriesColor:Number = series[2]; RA cell (#3) of data from Xcelsius

var seriesAlpha:Number = series[3]; RA cell (#4) of data from Xcelsius

As we cycle through this data, in the switch statement below, we determine the type of series specified, style the series accordingly, and add the series on to the Cartesian Chart. Listed below is the function code.

/*** *Cycle through the 2D series Array, *styling and adding specified series types***/private function buildSeries():void{ if(chart == null) return; chart.series=new Array(); columnSet = new ColumnSet(); columnSet.type = “clustered”; var st:Stroke; for(var i:int=0;i<_xcChartSeries.length;i++) { var series:Array = _xcChartSeries[i]; var seriesType:String = series[0]; var seriesName:String = series[1]; var seriesColor:Number = series[2];

5771 Book.indb 496 8/6/10 11:05:31 AM

www.sap-press.com

497


var seriesAlpha:Number = series[3]; //Add the correct series based on the //specified seriesType switch (seriesType.toLowerCase()) { case “line”: var ls:LineSeries = new LineSeries(); ls.yField = seriesName; ls.name = seriesName; ls.displayName= seriesName; st = new Stroke(); st.color=seriesColor; st.alpha=seriesAlpha; st.weight=2; st.pixelHinting=false; var linePointFill:RadialGradient = new RadialGradient(); linePointFill.entries = [new GradientEntry(seriesColor, 0.33, .5), new GradientEntry(seriesColor, 0.65, seriesAlpha)] ls.setStyle(“fill”,linePointFill); ls.setStyle(“lineStroke”,st); ls.setStyle(“stroke”,st); ls.setStyle(“radius”,3); ls.setStyle(“form”,”curve”); ls.setStyle(“itemRenderer”, new ClassFactory( mx.charts.renderers.CircleItemRenderer)); ls.setStyle (“lineSegmentRenderer”, new ClassFactory( mx.charts.renderers.LineRenderer)); //Add the series chart.series.push(ls); break; case “column”: var cs:ColumnSeries = new ColumnSeries(); cs.yField = seriesName;

5771 Book.indb 497 8/6/10 11:05:31 AM

www.sap-press.com

498


cs.name = seriesName; cs.displayName= seriesName; var columnFill:LinearGradient = new LinearGradient(); columnFill.entries = [new GradientEntry(seriesColor, 0.33, seriesAlpha), new GradientEntry(seriesColor, 0.65, seriesAlpha)] cs.setStyle(“fill”,columnFill); cs.alpha=seriesAlpha; //Add the series columnSet.series.push(cs); break; case “area”: var ar:AreaSeries = new AreaSeries(); ar.yField = seriesName; ar.name = seriesName; ar.displayName= seriesName; st = new Stroke(); st.color=seriesColor; st.alpha=1; st.weight=1; st.pixelHinting=false; var areaFill:LinearGradient = new LinearGradient(); areaFill.entries = [new GradientEntry(seriesColor, 0.33, .5), new GradientEntry(seriesColor, 0.65, .6)] ar.setStyle(“areaFill”,areaFill); ar.setStyle(“areaStroke”,st); ar.setStyle(“stroke”,st); ar.setStyle(“form”,”curve”); //Add the series chart.series.push(ar); break;

5771 Book.indb 498 8/6/10 11:05:31 AM

www.sap-press.com

499


} chart.series.push(columnSet); }}

private function formatDataTip(obj:Object):String { return obj.item[obj.element.displayName + obj.item.yLabel];}

Tooltip Function

The ability to finely control the information that an end user sees when they mouse over a given data point in an Xcelsius chart is an extremely important fea-ture. By leveraging some standard Flex capabilities, we are able to return custom tooltips to our end users via this simple function which extracts information from the obj:Object parameter and returns our user-specified tooltip content, which may contain normal text as well as HTML. Listed below is the function code.

private function formatDataTip(obj:Object):String {return obj.item[obj.element.displayName + obj.item.yLabel]; }

MXML Markup: Grid Lines and Cartesian Chart

The MXML specified in this part of the component provides us with the type of Grid Lines we want to use for our chart as well as the basic implementation of our Cartesian Chart’s shell.

<mx:Array id=”chartBg”> <mx:GridLines alpha=”.65” direction=”both”/></mx:Array><mx:CartesianChart id=”chart” width=”100%” height=”100%” showDataTips=”true” color=”{_xcChartColor}” dataTipFunction=”formatDataTip” dataProvider=”{_xcChartData}” backgroundElements=”{chartBg}”> <mx:horizontalAxis>

5771 Book.indb 499 8/6/10 11:05:31 AM

www.sap-press.com

500


<mx:CategoryAxis dataProvider=”{_xcChartData}” categoryField=”yLabel”/> </mx:horizontalAxis> </mx:CartesianChart></mx:Canvas>

Creating Basic Component Packages11.3

As a continuation of the custom chart component highlighted in this chapter, let’s build a packager for it as our fi nal step in preparing it for consumption by Xcelsius.

Basic Component Packaging Steps

Open the Packager.exe application contained in the Xcelsius SDK install direc-1. tory {Program Files}/BusinessObjects/Xcelsius/SDK.

Type in details related to your component as shown in Figure 11.7, including 2. the component name.

Enter your Component DetailsFigure 11.7

5771 Book.indb 500 8/6/10 11:05:31 AM

www.sap-press.com

501

Creating Basic Component Packages 11.3

Select the Visual Components tab and click Add New Component.3.

Enter the component’s class name, including its full package path, as well as 4. any additional information about the component, including the path to the Property Sheet swf fi le, component swf fi le and optional images you may defi ne to represent the component in the Xcelsius Object Browser and Component List as shown in Figure 11.8.

Enter your Component Class Name and SWF File DetailsFigure 11.8

Save your packager fi le.5.

Build your XLX installer fi le and install it using the Xcelsius add-on manager (In 6. Xcelsius, File -> Manage Add-Ons) as shown in Figure 11.9.

5771 Book.indb 501 8/6/10 11:05:32 AM

www.sap-press.com

502


Build Your Component XLX Installer FileFigure 11.9

Packaging for Special Components

If your component is not a visual component and is a data connection or a func-tion component, use the Connection and Function tabs accordingly to establish and build your component’s installer fi le as shown in Figure 11.10.

Packaging Best Practices

While the packaging process is a simple act on the home stretch of creating your custom component, there are a handful of best practices that should be adhered to during this very important process.

Use relative paths when linking assets (swf fi les, image fi les, text fi les) to your EE

package.

Use only one package per component to avoid installation confl icts in Xcelsius. EE

Each package contains a unique ID value that Xcelsius inspects at install time and expects to be unique on a per-component basis.

Do not copy components to avoid the confl ict behavior described above.EE

Save and backup your packages especially if you are developing products EE

because if a package is lost or corrupted, you will once again run into the instal-

5771 Book.indb 502 8/6/10 11:05:33 AM

www.sap-press.com

503

Summary 11,4

lation issue outlined above if you attempt to recreate the lost or corrupted pack-age from the ground up.

Connections TabFigure 11.10

Summary11.4

In this chapter, we stepped through, in detail, a full Property Sheet and corre-sponding custom Flex component for Xcelsius. We also dived deeper into the details of certain core pieces of SDK functionality, highlighted common functions where the SDK can be implemented, and gave an overview of how to develop a basic custom component for your Xcelsius environment. With a functional com-ponent under our belts, in the following chapter Implementing Advanced Custom Add-On Component Features, we will take a tour of some more advanced yet less advertised, very powerful concepts and utilities exposed by the SDK.

5771 Book.indb 503 8/6/10 11:05:33 AM

www.sap-press.com

583

A

About Xcelsius, 63Accordion Menu, 210ActionScript 3, 462, 465Add-On Manager, 544Ad-Hoc Query Designer, 28Adjust the Appearance, 459Adobe AIR runtime, 462Adobe Flash, 17Adobeís Flex, 461Adobe LifeCycle Data Service, 391Advanced Charts, 185Advanced Component Features, 513Advanced Custom Add-On Component Features , 505, 472Advanced Data Connectivity, 331Advanced Selectors, 210Advanced Single-Value Components, 228Alerts, 416Alert Thresholds, 126Align, 56Appearance, 102Area Chart, 144Auto Play, 220

B

Backgrounds, 180Bar Chart, 136Behavior, 99, 114Bindable Chart Data, 527Bindable Selected Data, 528Bindable Selected Tooltip, 528Bindable Series Color, 527Bind Data, 79Binding Directions , 471Binding Directions and Data Flow, 476

BindingID, 490Binding Types, 477Bubble Chart, 141BubbleChartBase.mxml, 540By Range, 111

C

Calendar, 225Candlestick Chart, 202Canvas, 71, 420, 468Canvas and Spreadsheet, 54Canvas Sizing, 38, 54Cell, 81Chain, 490chartSeriesData, 506Checkbox, 157Column Chart, 110, 442Combination Chart, 189Common users, 18Communicating with External Data Services, 505Comparison, 23Component Browser, 68Component Code, 521Components., 91Components Browser, 31Connections, 61Connect to External Data, 458Containers, 176, 410Copy and Paste, 297Copy/Paste/Cut/Delete/Select All, 51Crystal Reports, 28CSV files, 463Currency, 107Custom add-on component, 527Custom Component Property Values, 510

Index

5771 Book.indb 583 8/6/10 11:05:55 AM

www.sap-press.com

584

Index

Custom Components , 475Custom Properties, 527

D

Data binding, 31, 53Data Connectivity Basics, 293Data Connectivity Capabilities, 26Data Consumer Connection, 352Data menu, 33Data meters, 469Data Point, 105Data Visualization Capabilities, 20Default Selection, 99Description, 39Developers, 18Developing Basic Add-On Components, 480Device Fonts, 40Dial and Gauge, 172Displaying Data in a Table, 235Distribute the Output, 88Distribution, 27Divisions, 119Document Properties, 38Drill Down, 82, 83, 96, 393Dual Slider, 229Dynamic Visibility, 100, 405

E

Embedded Excel Spreadsheet, 71, 294Enable Data Animation, 101Encrypted data repositories, 463Enterprise users, 18Entry Effect, 101Excel , 19, 31Excel formulas, 54Excel Options, 44Excel XML Map, 326

Explicitly Getting Property Values, 480Explicitly Setting Property Values, 479Export, 46, 60, 424Export Preview, 46Export Settings, 47External Data, 85External Data Services, 513External Interface Connection, 375

F

File, 31Filled Radar Chart, 206Filter, 153Flash, 49Flash Variables, 358Flex applications , 462Flex Builder , 462Flex Component and Property Sheet Project, 528Flex framework, 462Flex Property Sheet, 534Flex Test Container, 543Font, 39Format, 56, 66Formatting, 85FS Command, 368Fundamental SDK import statements, 482

G

Gannt Charts, 464Gauge, 442Generating Reusable Property Sheet Patterns, 505Get Bound Property Display Names, 486Grid, 51Grid Lines and Cartesian Chart, 499

5771 Book.indb 584 8/6/10 11:05:55 AM

www.sap-press.com

585

Index

H

Hierarchical pie charts, 468Hotfix 3 SDK, 467HTML, 49HTTPService, 524HTTPService Result, 523Hyperion Essbase, 332

I

Icon, 217IDE, 463Image Component, 246Implementing Advanced Custom Add-On Component Features , 505Import, 59Import Data from an Excel File, 298Initialize Values, 484Initiating End-User Interaction Binding Operations, 486InputBindings, 478InputMap, 491Installation, 18integrated development environment (IDE), 31Interaction Options, 99Interactivity, 24

J

JavaScript code, 379Javascript Maps, 464

L

Languages, 43LCDS Connection, 382Legend, 104License Manager, 63Line Chart, 128, 442

Lines, 106, 252List, 70List Builder, 165Live Office Compatibility, 45Live Office Connection, 339

M

Manage Add-Ons, 49Manual (Y) Axis, 117Map, 442MDX querying capabilities, 470Menu, 31Metadata, 411Microsoft SQL Server, Access and Analysis Server, 332Mouse Tracking, 173Multi-dial Gauges, 468Multi-Select , 409MXML, 462MXML Markup, 499MySQL, 332My workspace, 54

N

New command , 32

O

Object Browser, 52, 74Object Elasticity, 173OHLC Chart, 191One-Dimensional Cell Range, 81Open from Enterprise/Save To Enterprise, 34Open/Save/Save As, 33Oracle, 332Organizing Data in Excel, 451Outlook, 49OutputBindings, 479

5771 Book.indb 585 8/6/10 11:05:55 AM

www.sap-press.com

586

Index

P

Packager and Xcelsius XLX Add-On, 543Packaging best practices, 502Panel Container, 177, 415Percent, 108Percentage, 22Persisting Property Sheet Values, 505, 507Picture Menus, 160Pie Chart, 80, 92, 442Planning the Dashboard, 441Plan the UI, 442Plan the Workflow, 441Play Control, 231Play Selector, 219Plot Area, 103Portal Data, 387Position, 97PowerPoint Slide, 49Preferences, 41Preparing Data, 443Preview, 46Private SDK variables, 480Private Variables, 491Progress Bar, 171Properties, 52Properties Panel, 329Property Data Binding, 475Property Sheet, 31, 72, 466, 475Property Sheet Data Binding, 476Property Sheet Styling, 480Property Value Setting/Getting, 475Proxy.Bind, 490Proxy.Bind dissected, 480proxy.getPersist function , 509Public Chart Color Variable, 491Public Chart Data Variable, 491

Q

Query as a Web Service, 331Quick Start, 62

Quick Views, 52

R

Radar Chart, 203Reading values from the spreadsheet, 476Resize, 297Retrieving Custom Component Property Values, 505Retrieving Property Sheet Values, 507Reusable Property Sheet Patterns, 510Row/Column, 98Run Locally, 300Run on a Web Server, 300

S

Samples, 36SAP BusinessObjects, 17SAP BusinessObjects Enterprise, 34, 331SAP BusinessObjects Live Office, 28SAP BusinessObjects Portfolio, 28SAP BusinessObjects Universe Designer, 28SAP BusinessObjects Web Intelligence, 28SAP NetWeaver BW (Business Warehouse), 332Scale, 116Security Issues Related to Accessing External Data, 299Security Restriction, 340Selectors, 147Set Appearance, 135Setting Custom Component Property Values, 505Shapes, 248Single Cell, 81Slider, 167Snapshot, 48Space Evenly, 56

5771 Book.indb 586 8/6/10 11:05:55 AM

www.sap-press.com

587

Index

Spinner, 230Spreadsheet, 81Spreadsheet Table, 239Stacked Column Chart, 186Standard, 64Status List, 97Sub Element Array Tricks, 514Sub-element binding, 505Sub Element Binding , 514Supporting SDK functions, 484.swc file, 461

T

Tab Set, 178Templates, 34The Column Chart, 445The Gauge, 445The Line Chart, 447Themes, 65Themes and Colors, 430The Pie Chart, 450The Radio Button, 450Ticker, 158Title Area, 103Toggle Button, 158Toolbar, 56, 64Tooltip Function, 491, 499Transparency, 106Tree Map, 208Two-Dimensional Cell Range, 82

U

UI Components, 78, 393UI controls, 20UI elements, 20

Undo/Redo, 50Use Current Excel Data, 48User Interface, 475Using Art, 246

V

Value, 97

W

Web Connectivity, 262Web Service Connection, 20, 322, 323Working with Charts, 92Wrap Several Components, 176Writing values to the spreadsheet, 477

X

Xcelsius, 17, 461Xcelsius Column Chart , 506Xcelsius SDK, 461Xcelsius Workspace, 32.xlf, 34.xls, 32.xlsx, 32XML-based syntax, 462XML, 462XML Data, 301XML File, 304XML layout and controls, 539XY Chart, 137

Y

(Y) Axis Scale, 118

5771 Book.indb 587 8/6/10 11:05:55 AM

www.sap-press.com

sample xcelsius practical guid

Documents