sbo41 dashboards component sdk tutorial 4 – creating a custom property sheet

SAP BusinessObjects Dashboards Component SDK Tutorial 4 - Creatinga custom property sheet■ SAP BusinessObjects 4.1

2013-03-16

© 2013 SAP AG or an SAP affiliate company. All rights reserved.No part of this publication may bereproduced or transmitted in any form or for any purpose without the express permission of SAP AG.

Copyright

The information contained herein may be changed without prior notice. Some software productsmarketed by SAP AG and its distributors contain proprietary software components of other softwarevendors. National product specifications may vary. These materials are provided by SAP AG and itsaffiliated companies ("SAP Group") for informational purposes only, without representation or warrantyof any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials.The only warranties for SAP Group products and services are those that are set forth in the expresswarranty statements accompanying such products and services, if any. Nothing herein should beconstrued as constituting an additional warranty. SAP and other SAP products and services mentionedherein as well as their respective logos are trademarks or registered trademarks of SAP AG inGermany and other countries. Please seehttp://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for additional trademarkinformation and notices.

2013-03-16

Contents

Introduction.............................................................................................................................5Chapter 1

Task 1: Creating a basic Flex project......................................................................................7Chapter 2

Task 2: Designing the layout for the property sheet...............................................................9Chapter 3

Task 3: Creating a CSS File..................................................................................................11Chapter 4

Task 4: Handling communication between property sheet and the component....................13Chapter 5

Subtask 4a: Importing classes and creating local variables.....................................................135.1Subtask 4b: Implementing init() function.................................................................................145.2Subtask 4c: Implementing initValues() function......................................................................145.3Subtask 4d: Implementing getPropertyBindDisplayName and initiateBind functions...............165.4Subtask 4e: Implementing continueBind function....................................................................165.5

2013-03-163

2013-03-164

Contents

Introduction

This tutorial assumes that you have at least some knowledge of Cascading Style Sheet (CSS),ActionScript 3.0, and MXML, the XML-based markup language introduced by Adobe Flex.

The concentration of the tutorial is creating a custom property sheet for those who do not want to usethe default property sheet. We will include Flex controls in the property sheet so that all of the propertiesand styles of the custom component can be exposed. We will also use a sample CSS definition to stylethe property sheet to look more like the Dashboards color scheme. Download the source code for thecustom component so that you could see what properties and styles it has. You will need to referencethe names of the properties/styles inside the property sheet source code.

For demonstration purposes, only the basic controls for the layout of custom property sheet arementioned. Please see the CustomPropSheetHorizontalSlider sample source code for a moreadvanced layout.

2013-03-165

Introduction

2013-03-166

Introduction

Task 1: Creating a basic Flex project

1. Create a basic Flex project for the custom property sheet. .For details on creating a project and adding the framework, refer to the Dashboards ComponentSDK User Guide section Create a visual component.

2. Open the Flex project application MXML file.3. Inside of the <mx:Application> tag, add applicationComplete="init();".

2013-03-167


2013-03-168


Task 2: Designing the layout for the property sheet

1. Switch to Design mode by pressing the Design button located next to the Source button.2. Design the layout of the custom property sheet. Add the following controls to the layout:

• Viewstack: id=viewstack1, creationPolicy=all, left=0, right=0, y=45, height=100%, width=100%,minWidth=268, minHeight=350• Canvas: id=general, label=General, minWidth=268,minHeight=350, width=100%, height=100%

• Label: text=Title, x=23, y=24, width=119• HRule: y=28, height=10, right=28, left=59• TextInput: id=titleEditor, change=proxy.setProperty('title', titleEditor.text), y=52, right=69,

left=37• Label: text=Value, x=23, y=116, width=119• HRule: y=118, height=10, right=28, left=66• TextInput: id=valueEditor, change=proxy.seProperty('value', Number(valueEditor.text)),

y=144, right=69, left=37• Button: click=initiateBind('value'), icon=@Embed('resources/bind to cell.png'), y=143,

right=37, width=24• Canvas: id=appearance, label=Appearance, minWidth=268, minHeight=350, width=100%,

height=100%• Label: text=Text, x=23, y=23, text=Text, width=119• HRule: y=28, height=10, right=28, left=56• CheckBox: id=showTitleEditor, label=Show Title, change=proxy.setProperty('showTitle',

showTitleEditor.selected), selected=true, x=43, y=54• ComboBox: id=titleFontFamilyEditor, dataProvider={_fontNames},

change=proxy.setStyle('titleFontFamily', titleFontFamilyEditor.value), x=94, y=79, width=129• ComboBox: id=titleFontSizeEditor, dataProvider={_fontSizes},

change=proxy.setStyle('titleFontSize', titleFontSizeEditor.value), x=231 y=79 width=55• Label: text=Color, x=23, y=136, width=119• HRule: y=141, height=10, right=28, left=62• Label: text=Title Color, x=43, y=169, text=Title Color:, width=116• ColorPicker: id=titleColorEditor, change=proxy.setStyle('titleFontColor',

uint(titleColorEditor.selectedColor)), x=137, y=169

• TabBar: dataProvider=viewstack1

3. After laying out the controls, switch to Source mode, you should have the following code:<?xml version="1.0" encoding="utf-8"?><mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" applicationComplete="init();">

<mx:ViewStack id="viewstack1" creationPolicy="all" left="0" right="0" y="45" height="100%" width="100%"minWidth="268" minHeight="350">

<mx:Canvas id="general" label="General" minWidth="268" minHeight="350" width="100%" height="100%">

2013-03-169


<mx:Label x="23" y="24" text="Title" width="119"/><mx:HRule y="28" height="10" right="28" left="59"/><mx:TextInput id="titleEditor" y="52" right="69" left="37" change="proxy.setProperty('ti

tle',titleEditor.text)"/><mx:Label x="23" y="116" text="Value" width="119"/><mx:HRule y="118" height="10" right="28" left="66"/>

<mx:TextInput id="valueEditor" y="144" right="69" left="37" change="proxy.setProperty('value',Number(valueEditor.text))"/>

<mx:Button y="143" right="37" width="24" click="initiateBind('value');" icon="@Embed('resources/bind to cell.png')"/>

</mx:Canvas><mx:Canvas id="appearance" label="Appearance" minWidth="268" minHeight="350" width="100%"

height="100%"><mx:Label x="23" y="23" text="Text" width="119"/><mx:HRule y="28" height="10" right="28" left="56"/><mx:CheckBox id="showTitleEditor" x="43" y="54" label="Show Title" change="proxy.setProper

ty('showTitle', showTitleEditor.selected)" selected="true"/><mx:ComboBox id="titleFontFamilyEditor" dataProvider="{_fontNames}" x="94" y="79" width="129"

change="proxy.setStyle('titleFontFamily', titleFontFamilyEditor.value)" /><mx:ComboBox id="titleFontSizeEditor" dataProvider="{_fontSizes}" x="231" y="79" width="55"

change="proxy.setStyle('titleFontSize', titleFontSizeEditor.value)" /><mx:Label x="23" y="136" text="Color" width="119"/><mx:HRule y="141" height="10" right="28" left="62"/><mx:Label x="43" y="169" text="Title Color:" width="116"/>

<mx:ColorPicker id="titleColorEditor" x="137" y="169" change="proxy.setStyle('titleFontColor',uint(titleColorEditor.selectedColor))" />

</mx:Canvas></mx:ViewStack><mx:TabBar x="0" y="0" dataProvider="viewstack1"></mx:TabBar>

</mx:Application>

2013-03-1610


Task 3: Creating a CSS File

1. Immediately after <mx:Application> and before <mx:ViewStack>, add the following tags:<mx:Style /><mx:Script><![CDATA[

]]></mx:Script>

2. Right click on the project folder in the Navigation window and create a new folder named style;then import PSStyle.css, located in the SDK install folder: SDK\samples\CustomPropSheetHorizontalSlider\CustomPropSheetHorizontalSliderPropertySheet\style\. ThisCSS definition file contains several tags that define the styles for each of them. These styles definitionswere chosen because they closely match Dashboards property sheet styles: background color is#F4F3EE, fontFamily is Tahoma, text color is black, etc.

3. Modify the source of <mx:Style> tag to include PSStyle.css: <mx:Stylesource="style\PSStyle.css"/>

2013-03-1611


2013-03-1612


Task 4: Handling communication between property sheetand the component

Task 4 is divided into five subtasks, 4a through 4e. In the first subtask, you will import classes from theDashboards SDK framework. In the remaining subtasks, you will implement the following functions:• init():void

initializes the property sheet on load

• getPropertyBindDisplayName(propertyName:String):String

returns the bind display name or null if not Bound.

• initiateBind(propertyName:String):void

allows the user of the component to bind the Excel spreadsheet cell to an Dashboards customcomponent property/style.

• continueBind(bindingID:String):void

completes the binding when the user has finished selecting the cell to bind to or cleared the binding.

5.1 Subtask 4a: Importing classes and creating local variables

Inside CData section, include the following segments of code: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;

[Bindable]private var _fontNames:Array = [];

[Bindable]protected var _fontSizes:Array = new Array("8", "9", "10", "11", "12", "14", "16", "18", "20",

"22");

protected var proxy:PropertySheetExternalProxy = new PropertySheetExternalProxy();

protected var propertyToBind:String;

protected var currentBindingID:String;

2013-03-1613

Task 4: Handling communication between property sheet and the component

• _fontNames will contain system fonts that the user can choose from.• _fontSizes is the list of selectable font sizes.Both of these variables need to be bindable since we bind them to the data providers of the comboboxes on the "Appearance" tab.

Variable proxy is the Dashboards proxy that enables communication between the property sheet andthe custom component. The package xcelsius.propertySheets.impl.PropertySheetExternalProxy for the proxy is the implementation of the interface xcelsius.propertySheets.interfaces.IPropertySheetProxy, which are both included in the xcelsiusframework.swc.

Variable propertyToBind stores the name of the property that the user is binding, and currentBindingID stores the current binding id (null if there's no binding) for the property.

5.2 Subtask 4b: Implementing init() function

The function init() sets the callback to continueBindmethod when the user is picking Excel cell(s)to bind to, and then notifies Dashboards that it has finished loading the property sheet. Refer to the APIDocumentation for the list of function name constants. The retrieval of the list of system fonts isimplemented here. Lastly, it makes a call to initValues method that initializes the property sheet onload with default property/style values.

protected function init():void{

proxy.addCallback(PropertySheetFunctionNamesSDK.RESPONSE_BINDING_ID, this.continueBind);proxy.callContainer(PropertySheetFunctionNamesSDK.INIT_COMPLETE_FUNCTION);var allFonts:Array = Font.enumerateFonts(true);allFonts.sortOn("fontName", Array.CASEINSENSITIVE);var numFonts:int = allFonts.length;for (var i:int=0; i<numFonts; i++){

var font:Font = allFonts[i];_fontNames.push(font.fontName);

}initValues();

}

5.3 Subtask 4c: Implementing initValues() function

In initValues(), we first get the array of values for the Dashboards custom component propertiesusing proxy.getProperties method, then the array of values for the styles using proxy. getStyles method. Both methods need a list of property or style names passed in as an array of strings.

Next, we process through the arrays retrieving the name and value of each property and style, andeither displaying that value to the corresponding control's default value or the cell address(es) if bound

2013-03-1614


to the Excel spreadsheet. If a property has binding capability, make use of getPropertyBindDisplayName method and add an if-else statement to handle that correctly.

protected function initValues():void{

// Process the array of values for the Xcelsius custom component properties.var propertyValues:Array = proxy.getProperties(["title", "value","showTitle"]);var propertyValuesLength:int = (propertyValues != null ? propertyValues.length : 0);for (var i:int=0; i < propertyValuesLength; i++){

var propertyObject:Object = propertyValues[i];var propertyName:String = propertyObject.name;var propertyValue:* = propertyObject.value;var bindingText:String = "";switch (propertyName){

case "title":titleEditor.text = String(propertyValue);break;

case "value":bindingText = getPropertyBindDisplayName(propertyName);if (bindingText != null){

valueEditor.enabled = false;valueEditor.text = bindingText;

}else{

valueEditor.text = propertyValue;}break;

case "showTitle":showTitleEditor.selected = Boolean(propertyValue);break;

default:break;

}}

// Process the array of values for the custom component styles.var styleValues:Array = proxy.getStyles(["titleFontFamily", "titleFontColor", "titleFont

Size"]);var styleValuesLength:int = (styleValues != null ? styleValues.length : 0);for (var j:int=0; j < styleValuesLength; j++){

var styleObject:Object = styleValues[j];var styleName:String = styleObject.name;var styleValue:* = styleObject.value;var bindingTextStyle:String = "";switch (styleName){

case "titleFontColor":titleColorEditor.selectedColor = uint(styleValue);break;

case "titleFontFamily":titleFontFamilyEditor.selectedIndex = _fontNames.indexOf(styleValue);break;

case "titleFontSize":titleFontSizeEditor.selectedIndex = _fontSizes.indexOf(styleValue);var index:int;index = _fontSizes.indexOf(styleValue.toString());if (index != -1){

titleFontSizeEditor.selectedIndex = index;}else if (!isNaN(styleValue)){

titleFontSizeEditor.text = styleValue.toString();}else{

titleFontSizeEditor.selectedIndex = -1;}break;

default:break;

}}

}

2013-03-1615


5.4 Subtask 4d: Implementing getPropertyBindDisplayName and initiateBindfunctions

Given a property name, getPropertyBindDisplayName gets the array of bindings for that propertyby calling proxy.getBindings method. If we have at least one binding for that property then pickthe first one.

protected function getPropertyBindDisplayName(propertyName:String):String{

var propertyBindings:Array = proxy.getBindings([propertyName]);if ((propertyBindings != null) && (propertyBindings.length > 0) && (propertyBindings[0].length

> 0)){

var bindingID:String = propertyBindings[0][0];return proxy.getBindingDisplayName(bindingID);

}return null;

}

Given a property name, initiateBind allows the user to select the Excel spreadsheet cell(s) to bindto an Dashboards custom component property. If there is an existing binding for that property, showthat in the Excel binding selection window and store the currentBindingID (null if there is no currentbinding) in case we "continueBinding". Use the function proxy.requestUserSelectionmethod tolet the user choose where to bind to in the Excel spreadsheet.

protected function initiateBind(propertyName:String):void{

currentBindingID = null;var propertyBindings:Array = proxy.getBindings([propertyName]);if ((propertyBindings != null) && (propertyBindings.length > 0)){

currentBindingID = propertyBindings[0];}propertyToBind = propertyName;proxy.requestUserSelection(currentBindingID);

}

5.5 Subtask 4e: Implementing continueBind function

continueBind method completes the binding when the user has finished selecting the cell(s) to bindto or cleared the binding. Again, we process through each property that has binding capability to do thefollowing: filling the control with current value and set property when the user explicitly clears binding,disabling the option to manually enter a value once the component if the property is bound, displayingthe range address, and the actual binding using proxy.bind method. BindingDirection.BOTHupdates the custom component property when the spreadsheet changes and also updates thespreadsheet when the custom component changes. InputBindings.SINGLETON writes to a singlecell in the spreadsheet. OutputBindings.SINGLETON reads a single cell in the spreadsheet.

2013-03-1616


For more information on bindings and the custom property sheet API, refer to Appendix B in theDashboards Component SDK SP1 User Guide.

protected function continueBind(bindingID:String):void{

var propertyName:String = propertyToBind;var propertyValues:Array;var propertyObject:Object;var bindingAddresses:Array;

if (currentBindingID != null){

proxy.unbind(currentBindingID);currentBindingID = null;

}

switch (propertyName){

case "value":if ((bindingID == null) || (bindingID == "")){

valueEditor.enabled = true;propertyValues = proxy.getProperties([propertyName]);propertyObject = propertyValues[0];valueEditor.text = propertyObject.value;proxy.setProperty(propertyName, propertyObject.value);return;

}valueEditor.enabled = false;valueEditor.text = proxy.getBindingDisplayName(bindingID);

proxy.bind("value", null, bindingID, BindingDirection.BOTH, InputBindings.SINGLETON,OutputBindings.SINGLETON);

break;default:

break;}

}

Save and build.

2013-03-1617


2013-03-1618


sbo41 dashboards component sdk tutorial 4 – creating a custom property sheet

Documents