SAP BusinessObjects Dashboard Design Component SDK Tutorial 4 - Creating a custom property. sheet

Transcription

1 SAP BusinessObjects Dashboard Design Component SDK Tutorial 4 - Creating a custom property sheet SAP BusinessObjects Dashboard Design Component SDK Tutorial 4 - Creating a custom property sheet

2 Copyright 2011 SAP AG. All rights reserved.sap, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company.sybase and Adaptive Server, ianywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase, Inc. Sybase is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.these materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of 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 express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

3 Contents Chapter 1 Introduction...5 Chapter 2 Task 1: Creating a basic Flex project...7 Chapter 3 Task 2: Designing the layout for the property sheet...9 Chapter 4 Task 3: Creating a CSS File...11 Chapter Task 4: Handling communication between property sheet and the component...13 Subtask 4a: Importing classes and creating local variables...13 Subtask 4b: Implementing init() function...14 Subtask 4c: Implementing initvalues() function...14 Subtask 4d: Implementing getpropertybinddisplayname and initiatebind functions...16 Subtask 4e: Implementing continuebind function

4 Contents 4

5 Introduction 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 use the default property sheet. We will include Flex controls in the property sheet so that all of the properties and styles of the custom component can be exposed. We will also use a sample CSS definition to style the property sheet to look more like the Dashboard Design color scheme. Download the source code for the custom component so that you could see what properties and styles it has. You will need to reference the 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 are mentioned. Please see the CustomPropSheetHorizontalSlider sample source code for a more advanced layout. 5

6 Introduction 6

7 Task 1: Creating a basic Flex project 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 Dashboard Design Component SDK SP1 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();". 7

8 Task 1: Creating a basic Flex project 8

9 Task 2: Designing the layout for the property sheet 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'), 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=" 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%"> 9

10 Task 2: Designing the layout for the property sheet <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');" sources/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> 10

11 Task 3: Creating a CSS File 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\CustomPropSheetHo rizontalslider\custompropsheethorizontalsliderpropertysheet\style\. This CSS definition file contains several tags that define the styles for each of them. These styles definitions were chosen because they closely match Dashboard Design 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:style source="style\psstyle.css"/> 11

12 Task 3: Creating a CSS File 12

13 Task 4: Handling communication between property sheet and the component Task 4: Handling communication between property sheet and the component Task 4 is divided into five subtasks, 4a through 4e. In the first subtask, you will import classes from the Dashboard Design 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 Dashboard Design custom component 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 = []; "22"); [Bindable] protected var _fontsizes:array = new Array("8", "9", "10", "11", "12", "14", "16", "18", "20", protected var proxy:propertysheetexternalproxy = new PropertySheetExternalProxy(); protected var propertytobind:string; protected var currentbindingid:string; 13

14 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 combo boxes on the "Appearance" tab. Variable proxy is the Dashboard Design proxy that enables communication between the property sheet and the custom component. The package xcelsius.propertysheets.impl.propertyshee texternalproxy for the proxy is the implementation of the interface xcelsius.propertysheets.in terfaces.ipropertysheetproxy, which are both included in the xcelsiusframework.swc. Variable propertytobind stores the name of the property that the user is binding, and current BindingID 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 continuebind method when the user is picking Excel cell(s) to bind to, and then notifies Dashboard Design that it has finished loading the property sheet. Refer to the API Documentation for the list of function name constants. The retrieval of the list of system fonts is implemented here. Lastly, it makes a call to initvalues method that initializes the property sheet on load 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 Dashboard Design custom component properties using 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, and either displaying that value to the corresponding control's default value or the cell address(es) if bound 14

15 Task 4: Handling communication between property sheet and the component to the Excel spreadsheet. If a property has binding capability, make use of getpropertybinddis playname 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); case "value": bindingtext = getpropertybinddisplayname(propertyname); if (bindingtext!= null) valueeditor.enabled = false; valueeditor.text = bindingtext; else valueeditor.text = propertyvalue; case "showtitle": showtitleeditor.selected = Boolean(propertyValue); default: Size"]); // Process the array of values for the custom component styles. var stylevalues:array = proxy.getstyles(["titlefontfamily", "titlefontcolor", "titlefont 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); case "titlefontfamily": titlefontfamilyeditor.selectedindex = _fontnames.indexof(stylevalue); 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; default: 15

16 Task 4: Handling communication between property sheet and the component 5.4 Subtask 4d: Implementing getpropertybinddisplayname and initiatebind functions Given a property name, getpropertybinddisplayname gets the array of bindings for that property by calling proxy.getbindings method. If we have at least one binding for that property then pick the first one. > 0)) protected function getpropertybinddisplayname(propertyname:string):string var propertybindings:array = proxy.getbindings([propertyname]); if ((propertybindings!= null) && (propertybindings.length > 0) && (propertybindings[0].length 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 bind to an Dashboard Design custom component property. If there is an existing binding for that property, show that in the Excel binding selection window and store the currentbindingid (null if there is no current binding) in case we "continuebinding". Use the function proxy.requestuserselection method to let 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 bind to or cleared the binding. Again, we process through each property that has binding capability to do the following: 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, displaying the range address, and the actual binding using proxy.bind method. BindingDirection.BOTH updates the custom component property when the spreadsheet changes and also updates the spreadsheet when the custom component changes. InputBindings.SINGLETON writes to a single cell in the spreadsheet. OutputBindings.SINGLETON reads a single cell in the spreadsheet. 16

17 Task 4: Handling communication between property sheet and the component For more information on bindings and the custom property sheet API, refer to Appendix B in the Dashboard Design 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); default: Save and build. 17

18 Task 4: Handling communication between property sheet and the component 18