sap lumira visualization extensions developer guide 1.21

SAP Lumira SDKVersion: 1.21 ( 2014-12-12 )

SAP Lumira Visualization Extensions Developer Guide

Content

1 Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52.1 Who should use this guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Additional Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Technical Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63.1 Restrictions and Workarounds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Introduction to the VizPacker Visualization Extension Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 Creating a New Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.1 Creating a unique name for your extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.2 Generating the extension files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105.3 Modifying the JavaScript code template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.4 Testing the extension in a browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

6 Using a Visualization Extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146.1 Installing the Hello World extension to SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146.2 Using the Hello World extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7 Debugging an Extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167.1 Enabling the debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167.2 Accessing the debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177.3 Finding and debugging your code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

8 Converting a D3 Chart into an SAP Lumira Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198.1 Defining the extension properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208.2 Defining the data feeds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

8.2.1 Uploading the CSV file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218.2.2 Mapping the data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

8.3 Adding the D3 code to the extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228.4 Testing the extension in VizPacker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258.5 Using the Bullet Chart extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268.6 About the modified bullet chart code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

9 Importing Source Code into the Sample HTML File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

10 Updating Visualization Data at Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

11 Updating Extensions for the New Extension Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2 © 2014 SAP SE or an SAP affiliate company. All rights reserved.SAP Lumira Visualization Extensions Developer Guide

Content

11.1 Using the flow API to add chart elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3111.2 Converting the chart type definition to flow API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3211.3 Converting the feed definition to flow API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3311.4 Registering modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3411.5 Registering chart types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

SAP Lumira Visualization Extensions Developer GuideContent © 2014 SAP SE or an SAP affiliate company. All rights reserved. 3

1 Document History

The following table provides an overview of the most important document changes.

Version Date Description

1.21 December 2014 ● Renamed guide● Moved restrictions to the beginning

of the document● Removed large code blocks from

examples, updated example instructions

1.20 October 2014

1.18 July 2014 Added complete code sample to D3 chart example

1.17 June 2014 Added D3 chart example

1.15 April 2014 Minor changes, version update

1.14 December 2013 First release


Document History

2 About This Guide

2.1 Who should use this guide

This guide is a programming agnostic software development kit (SDK) intended for experienced application programmers who wish to create and customize visualization extensions that can be used with SAP Lumira Desktop.

2.2 Additional Resources

You can find more information about SAP Lumira chart extensions on the SAP Community Network (SCN).

The SAP Lumira community on the SCN has product news, blog posts, and samples for downloading. You can discuss specific topics with other users by posting in the community. To access the SAP Lumira community, go to http://scn.sap.com/community/lumira .

You can also view recordings of the SAP Lumira Webinar Series, which provides information about upcoming product features and specific use cases for SAP Lumira. To access these recordings, go to http://scn.sap.com/docs/DOC-52806 .

SAP Lumira Visualization Extensions Developer GuideAbout This Guide © 2014 SAP SE or an SAP affiliate company. All rights reserved. 5

http://help.sap.com/disclaimer?site=http://scn.sap.com/community/lumira

http://help.sap.com/disclaimer?site=http://scn.sap.com/docs/DOC-52806

http://help.sap.com/disclaimer?site=http://scn.sap.com/docs/DOC-52806

3 Technical Requirements

Before you can use VizPacker, you must install the necessary programs, know how to access the SAP Lumira SDK folders, and be familiar with the programming languages that are used in the SDK.

You need to meet the following requirements before creating visualization extensions:

● Install SAP Lumira Desktop on a Microsoft Windows 64-bit OS.You can download a free copy of SAP Lumira Personal Edition from: http://sap.com/buylumira

● Google ChromeVizPacker can only be used in Google Chrome.

● You are familiar with the following languages and libraries:

○ JavaScript○ HTML5○ D3 (Data-Driven Documents)

The SAP Lumira SDK uses D3. For more information about D3, see http://d3js.org/○ jQuery

● You are able to access the SDK folders that are included in an installation of SAP Lumira:

Table 1:

Location Folder name Description

<installdir>\SAP Lumira\Desktop\samples\extensions\charts

charts Contains sample extensions.

<installdir>\SAP Lumira\Desktop\extensions

extensions Contains extensions that have been installed for use in SAP Lumira.

<installdir>\SAP Lumira\Desktop\libs

libs Contains libraries that you can use to test extensions outside of SAP Lumira (for example, in a web browser).

<installdir>\SAP Lumira\Desktop\utilities\VizPacker

VizPacker Contains the VizPacker utility.

NoteBy default, the install directory (<installdir>) for SAP Lumira is C:\Program Files

NoteIf you are having difficulty copying and pasting the code samples in this guide, use Microsoft Word 2013 to open the SAP PDF document and then copy the text from the converted file.


Technical Requirements

http://help.sap.com/disclaimer?site=http://sap.com/buylumira

http://help.sap.com/disclaimer?site=http://d3js.org/

3.1 Restrictions and Workarounds

This section provides you with information on restrictions to be aware of and workarounds you can apply while using the VizPacker utility.

VizPacker only works with Google Chrome

VizPacker is compatible with the latest version of Google Chrome. You can download Google Chrome from here: https://www.google.com/intl/en/chrome/browser/

SAP Lumira must be restarted when you change your extension

SAP Lumira is an HTML5 application; if you make changes to your extension, you will need to quit and restart the program to have it use your modified code.

Some of your style definitions are ignored in SAP Lumira

By default, SAP Lumira applies styles to the SVG elements in the charts. These settings might override your settings. You can use the debugger in SAP Lumira to see which styles are being used or ignored.

As a workaround, add the !important keyword into your style definition, as shown in the following code:

.myclass { font-size:10px !important; }

Including this keyword in your style definition ensures that SAP Lumira does not override it.

Thumbnail view may not correctly show an extension if it uses DIV as root container

This is a known limitation in SAP Lumira that will be fixed in a future release.

Thumbnail view may not correctly show an extension if it uses external css files

This is a known limitation in SAP Lumira that will be fixed in a future release.

SAP Lumira Visualization Extensions Developer GuideTechnical Requirements © 2014 SAP SE or an SAP affiliate company. All rights reserved. 7

http://help.sap.com/disclaimer?site=https://www.google.com/intl/en/chrome/browser/

4 Introduction to the VizPacker Visualization Extension Utility

The SAP Lumira SDK includes the VizPacker visualization extension utility, a utility that lets you create new chart types as extensions and use them in SAP Lumira.

SAP Lumira lets you plot information by using a variety of different charts, including bar charts, line charts, and so on. However, you might need to use other charts that are not included in the program, such as sunburst charts or chord diagrams. VizPacker solves this problem by providing an extension framework with an associated API that lets you develop your own chart and integrate it with SAP Lumira.

This guide focuses on using VizPacker to generate the folder structure, the feed definition, and a JavaScript code template for the extension. Using VizPacker instead of manually creating the files and folders lets you focus on modifying the content of your code.

VizPacker generates these folders:

Table 2:

Folder Description

examples Contains an HTML page for testing the extension.

bundles Contains a JavaScript code template for the extension. This file is used for loading the extension in SAP Lumira, and it can also be used in the HTML test page.

features Contains a JSON file with the metadata of the extension, such as extension name, author, and so on. The JSON file would be used for installation.

VizPacker generates a template version of the render function for you to customize. You use the render function to build, update, or modify the DOM to display the extension and its data.


Introduction to the VizPacker Visualization Extension Utility

5 Creating a New Extension

In this tutorial, you will learn how to create an extension that displays the phrase “Hello World” and test this extension in a browser.

Workflow

Creating and testing the extension involves the following process:

1. Creating a unique name for your extension.2. Using VizPacker to generate the extension files, which include a JavaScript code template file, a JSON

description file, and an HTML test file.3. Modifying the JavaScript code template to complete the extension code.4. Testing the code.

5.1 Creating a unique name for your extension

You must create a unique name for your extension to ensure that your extension does not conflict with another one.

Procedure

1. To create a unique extension name, use the following naming convention:

<company name>.viz.ext.<extension name>

The variables should be replaced with meaningful information:

○ <company name> - the name of your company○ <extension name> - a descriptive short name for the extension

For example:

sap.viz.ext.helloworld

Note○ You must use lower case characters in extension names.○ Extensions that were created before SAP Lumira 1.14 follow a different naming convention, using

slashes (/) instead of periods (.) as separators.For example:

SAP Lumira Visualization Extensions Developer GuideCreating a New Extension © 2014 SAP SE or an SAP affiliate company. All rights reserved. 9

sap/viz/ext/helloworldSAP Lumira supports this naming convention to ensure backwards compatibility. However, it is recommended that you use periods (.) as separators in any new extensions you create.

5.2 Generating the extension files

Use VizPacker to define the properties of the Hello World extension and generate the extension files. Using VizPacker instead of manually writing the code and creating the files simplifies the process of creating extensions.

Procedure

1. To start VizPacker, open the following file in Google Chrome:<installdir>\SAP Lumira\Desktop\utilities\VizPacker\VizPacker.html

2. (optional) If the welcome screen appears, do one of the following:

○ Take the introductory tour and familiarize yourself with the program.○ Close the welcome screen.

3. On the LAYOUT DESIGN tab, set the ID and name of the chart:a. To show the chart properties, click the dark grey layout box outside the Plot Area.

The Property Setting: Chart dialog box appears.b. Change the settings to the following:

○ ID: sap.viz.ext.helloworld○ NAME: Hello World

c. To apply your changes, click an area outside the dialog box.4. Set the ID and name of the plot area:

a. Click Plot Area.The Property Setting: Plot Area dialog box appears.

b. Change the settings to the following:

○ ID: sap.viz.ext.helloworld.helloworldmodule○ NAME: Hello World Module

c. To apply your changes, click an area outside the dialog box.

5. To remove the Title and Legend modules, click the delete icon for each module.You do not need these modules for this extension.

6. Prepare the files for editing:

Option Description

Use the built-in code editor to modify the files.

See Modifying the JavaScript code template [page 11].


Creating a New Extension

Option Description

Create a ZIP file to use in an external editor.

1. In the top right corner, click PACK.A dialog box appears.

2. To download the ZIP file, click the link to the file.Your extension files are downloaded as a file called sap.viz.ext.helloworld.zip.

3. Close the dialog box.

Results

The zip file has a folder that contains the following JS and CSS files (located under the bundles\<company name>\viz\ext\<extension name>\<unique name>-src folder):

Sub-folder File

js dataMapping.js

js flow.js

js module.js

js render.js

js\utils util.js

resources\templates\sample template.js

style default.css

For this extension, you will be using the render.js file.

5.3 Modifying the JavaScript code template

After you generate the extension files using VizPacker, you can edit the contents of the files. Complete the Hello World extension by removing the template code and adding a text element.

Prerequisites

Before you begin, ensure that you have generated the extension files. For more information, see Generating the extension files [page 10].

If you are using an external text editor to modify the code, do the following:

1. Create the following folder and extract the ZIP file into it: <installdir>\SAP Lumira\Desktop\myextensions\sap.viz.ext.helloworld


2. Launch your text editor program and open the following file: <installdir>\SAP Lumira\Desktop\myextensions\sap.viz.ext.helloworld\bundles\sap\viz\ext\helloworld\sap_viz_ext_helloworld-src\js\render.js


Context

The render function uses D3 and SVG. To make the extension display the phrase “Hello World”, you will create a text element and append it to the vis SVG element, which is inside the plot area of the extension.

Procedure

1. In the render function, delete the template code and the comments surrounding it:

a. Select the following lines in the code:

// START: sample render code for a bar chart// Replace the code below with your own one to develop a new extension

b. Continue selecting lines of text, including the following comments:

*/

// END: sample render code

c. Delete the selected text.The render function should now look as follows:

var render = function(data, container, width, height, colorPalette, properties, dispatch) { //prepare canvas with width and height of container container.selectAll('svg').remove(); var vis = container.append('svg').attr('width', width).attr('height', height) .append('g').attr('class', 'vis').attr('width', width).attr('height', height); vis.append("text").text("Hello World").attr("y", 20).attr("fontsize", "large");

};

2. To display the phrase “Hello World” in the extension, append an SVG text field to the vis element by adding the following D3 code to the end of the render function:

vis.append("text").text("Hello World").attr("y", 20).attr("fontsize", "large");


Creating a New Extension

3. Save the file.

5.4 Testing the extension in a browser

To verify that your extension code is correct, test the extension in Google Chrome before trying to use it in SAP Lumira.

Procedure

1. In Google Chrome, open the HTML file for the extension.If you extracted your extension files to the location that was specified in Modifying the JavaScript code template [page 11], then the HTML file is at the following location:

<installdir>\SAP Lumira\Desktop\myextensions\sap.viz.ext.helloworld\examples\example-sap.viz.ext.helloworld.htmlWhen you open the HTML file, the phrase “Hello World” displays in the browser.

2. If you do not see those words, check the Google Chrome console for errors and correct them:a. Right-click the part of your page that you would like to check, and select Inspect element.

The debugging tools appear at the bottom of the window. The Elements tab displays by default. You can use this tab to navigate and explore the hierarchy of the HTML page.

b. In the Console tab, look for any script errors and correct them.


6 Using a Visualization Extension in SAP Lumira

After you create visualization extensions, you need to add the extensions to SAP Lumira before you can use them.

Workflow

To use your visualization extension in SAP Lumira, you need to do the following:

1. Extract the contents of the ZIP file and add the bundles and features folders to the following SAP Lumira folder:

<installdir>\SAP Lumira\Desktop\extensions\

2. Use the extension in SAP Lumira.

In this tutorial, we will use the “Hello World” extension to demonstrate the process.

6.1 Installing the Hello World extension to SAP Lumira

Before you can use an extension in SAP Lumira, you must install the extension.

Context

It is highly recommended that you keep backup copies of the extensions folder. The contents of this folder are deleted when you update SAP Lumira to a different version.

Procedure

1. Extract the contents of the “Hello World” ZIP file: sap.viz.ext.helloworld.zip2. Copy your extension's bundles and features folders into the following folder:

<installdir>\SAP Lumira\Desktop\extensions\


Using a Visualization Extension in SAP Lumira

6.2 Using the Hello World extension in SAP Lumira

To verify that the installed “Hello World” extension works correctly, try using it in SAP Lumira.

Procedure

1. Start SAP Lumira.2. To access the Visualize tab, use a sample document:

a. Choose Try with Samples.b. Double-click the following document: BestRunCorp - Margin Analysis

3. Select the Visualize tab.

4. In the Chart Builder tab, click the Chart Extensions icon and from the drop list, choose the Hello World extension.

The “Hello World” message displays.

If you do not see the message, then you must debug your code. For more information, see Debugging an Extension in SAP Lumira [page 16].

Results

You have just created and installed your first SAP Lumira extension.

SAP Lumira Visualization Extensions Developer GuideUsing a Visualization Extension in SAP Lumira © 2014 SAP SE or an SAP affiliate company. All rights reserved. 15

7 Debugging an Extension in SAP Lumira

SAP Lumira has a debugger that you can use to debug your extensions. In this tutorial, you will learn how to view your Hello World extension code in the debugger.

Workflow

Debugging an extension in SAP Lumira involves the following process:

1. Enabling the debugger.2. Accessing the debugger in the program.3. Finding and debugging your code.

7.1 Enabling the debugger

Before you can use the debugger, you must enable it by modifying SAPLumira.ini

Procedure

1. Open the SAPLumira.ini file.

The default location of the file is: <installdir>\SAP Lumira\Desktop\SAPLumira.ini2. To enable the debugger, add the following line of code:

-Dhilo.cef.frame.debug=true

Optional: to disable the cache when debugging, change the following text:

-Dhilo.cef.cache.enabled=true

becomes

-Dhilo.cef.cache.enabled=false

3. Save the file.


Debugging an Extension in SAP Lumira

7.2 Accessing the debugger

After you enable the debugger, you can access it in SAP Lumira.

Prerequisites

Before you begin, ensure that you have done the following:

● Created the Hello World extension.For more information, see Creating a New Extension [page 9].

● Installed the extension to SAP Lumira.For more information, see Installing the Hello World extension to SAP Lumira [page 14].

● Enabled the debugger.For more information, see Enabling the debugger [page 16].

Procedure

1. Start SAP Lumira.2. To access the Visualize tab, do one of the following:

○ Open a document.You can use the built-in sample document, BestRunCorp - Margin Analysis.

○ Acquire data.3. Select the Visualize tab.

4. In the side panel, click the Chart Extensions icon and select the Hello World extension from the list that appears.

5. In the same panel, add one measure and one dimension.

If there is no data in the panel, the extension displays the following message:

Incomplete chart. Please add more measures or dimensions.

After you add a measure and a dimension, the “Hello World” message displays.6. Right-click an area outside the visualization and select Show DevTools.

The debugger appears in a new window.

Next Steps

After opening the debugger, find your extension code in the window and debug it.

SAP Lumira Visualization Extensions Developer GuideDebugging an Extension in SAP Lumira © 2014 SAP SE or an SAP affiliate company. All rights reserved. 17

7.3 Finding and debugging your code

Because SAP Lumira uses HTML5, the debugger shows some of the SAP Lumira code with your extension code. After you load the Hello World extension and open the debugger, you must find the extension code before you can start debugging it.

Context

To debug the Hello World extension, you must find its plot area (the DOM) and source code.

Procedure

1. To find the plot area element (the part of the DOM that you customized), do the following:a. Select the Elements tab.b. Press Ctrl + F and search for v-m-plot

v-m-plot is the ID of the plot area that VizPacker generated. The element that you added is inside the v-m-plot element.

Tip

You can also find elements in your code by clicking the magnifier icon in the bottom-left corner of the debugger and then selecting the element.

2. To find your source code, do the following:a. Select the Sources tab.

b. To show the source file navigator, click the icon in the top-left corner.

c. Navigate to the following folder: 127.0.0.1:<port number> sap/bi bundles sap viz exthelloworld sap_viz_ext_helloworld-src js

d. Select your source file: render.jsYour code appears in the window, and you can add breakpoints to debug it.


Debugging an Extension in SAP Lumira

8 Converting a D3 Chart into an SAP Lumira Extension

In this tutorial, you will learn how to convert a D3 bullet chart into a visualization extension. The conversion process is similar for all D3-based visualizations.

You will use VizPacker to generate the files for the Bullet Chart extension. The process is similar to creating the Hello World extension, except you define data feeds and add a modified version of the D3 bullet chart code.

Before you proceed with this tutorial, review the following blog post on the SAP Community Network (SCN): How to add a D3 extension for SAP Lumira .

TipThe blog post contains a video of the tutorial. You may find it helpful to watch the video before you start the tutorial, or refer to it as you work through the steps.

You can download the CSV file and text files from the following GitHub location: https://github.com/SAP/lumira-viz-library/tree/master/BulletChart

You will need the following files from GitHub:

Location File

BulletChart bullets.csv

BulletChart d3_gallery_modified bullet.js

BulletChart d3_gallery_modified index.html

Workflow

Converting the D3 bullet chart into an extension involves the following process:

1. Defining the extension properties.2. Defining the data feeds.3. Adding the D3 code to the extension.4. Testing the code.5. Generating the extension from VizPacker and using it in SAP Lumira.

Related Information

Bullet Charts

SAP Lumira Visualization Extensions Developer GuideConverting a D3 Chart into an SAP Lumira Extension © 2014 SAP SE or an SAP affiliate company. All rights reserved. 19

http://help.sap.com/disclaimer?site=http://scn.sap.com/community/lumira/blog/2014/02/19/how-to-add-a-d3-extension-for-sap-lumira


http://help.sap.com/disclaimer?site=https://github.com/SAP/lumira-viz-library/tree/master/BulletChart

http://help.sap.com/disclaimer?site=https://github.com/SAP/lumira-viz-library/tree/master/BulletChart

http://help.sap.com/disclaimer?site=http://bl.ocks.org/mbostock/4061961

8.1 Defining the extension properties

Use VizPacker to define the properties of the Bullet Chart extension.

Procedure

1. To start VizPacker, open the following file in Google Chrome:<installdir>\SAP Lumira\Desktop\utilities\VizPacker\VizPacker.html

2. (Optional) If the welcome screen appears, close it.3. On the LAYOUT DESIGN tab, set the ID and name of the chart:

a. To show the chart properties, click the dark grey layout box outside the Plot Area.The Property Setting: Chart dialog box appears.


○ ID: sap.viz.ext.bulletchart○ NAME: Bullet Chart

c. To apply your changes, click an area outside the dialog box.4. Set the ID and name of the plot area:

a. Click Plot Area.The Property Setting: Plot Area dialog box appears.


○ ID: sap.viz.ext.bulletchart.module○ NAME: Bullet Chart Module

c. To apply your changes, click an area outside the dialog box.

5. To remove the Legend module, click the delete icon at the top of the module.You do not need a legend for this extension.

8.2 Defining the data feeds

Use VizPacker to define the data feeds for the extension.

To define data feeds, upload the chart data as a CSV file and then map the data to dimension sets and measure sets.


Converting a D3 Chart into an SAP Lumira Extension

8.2.1 Uploading the CSV file

Use the data from the bullets.csv file to define the data feeds for the Bullet Chart extension.

Procedure

1. In VizPacker, select the Data Model tab.2. Click UPLOAD.3. Locate the bullets.csv file and upload it.

You'll be prompted with a reminder that you need at least one measure and one dimension in your data set.4. Click OK to close the prompt.

8.2.2 Mapping the data

After uploading the CSV file in VizPacker, map the data columns to dimension sets and measure sets.

Context

The following dimension and measure sets will become the data feeds in SAP Lumira: Actuals, Ranges, Target, and Titles

Procedure

1. Map the Title data column to a dimension set by expanding <Title> Dimension and selecting the first set.The first set may be labeled Entity or X axis or some other value.

a. Double-click the label and rename the dimension to Titles2. Map the Subtitle column to the same dimension.3. Using the same procedure, map the remaining data columns into measures:

Option Description

Range 1 Measure Set 3 ; rename to Ranges

Range 2 Measure Ranges

Range 3 Measure Ranges


Option Description

Actual Measure Y axis ; rename to Actuals

Pace Measure Actuals

Target Measure Set 2 ; rename to Target

After completing these steps, you should have two dimensions and six measures.

4. To apply the data model to the code, click APPLY.

8.3 Adding the D3 code to the extension

After defining the properties and data feeds, complete the Bullet Chart extension by adding the modified D3 code.

Context

This tutorial shows how to edit and preview your code directly inside VizPacker, but you can also generate the files and then edit them externally.

NoteThere are long code samples in the following procedure. There are comments to denote the beginning and end of the code samples.


Procedure

1. In VizPacker, in the render function, delete the template code and the comments surrounding it:

a. Select the following lines in the code:

// START: sample render code for a bar chart// Replace the code below with your own one to develop a new extension

b. Continue selecting lines of text, including the following comments:

*/

// END: sample render code



c. Delete the selected text.The render function should now look as follows:

var render = function(data, container, width, height, colorPalette, properties, dispatch) { //prepare canvas with width and height of container container.selectAll('svg').remove(); var vis = container.append('svg').attr('width', width).attr('height', height) .append('g').attr('class', 'vis').attr('width', width).attr('height', height);

};

return render; });

2. Add the following code block within the render function, below the vis definition:

var dset1 = data.meta.dimensions(0), // Titles

dim_title = dset1[0], dim_subtitle = dset1[1];

var mset1 = data.meta.measures(0), // Actuals

ms_actual = mset1[0], ms_pace = mset1[1];

var mset2 = data.meta.measures(1), // Ranges

ms_range1 = mset2[0], ms_range2 = mset2[1], ms_range3 = mset2[2];

var mset3 = data.meta.measures(2), // Target

ms_target = mset3[0];

3. Open the bullet.js file and append all the lines of the function (excluding the function header and its closing last line) below the following line:

ms_target = mset3[0];

4. Find the following lines and change them as indicated:

Original Updated

d3.bullet = function () { var d3_bullet = function () {var w0 = bulletWidth(x0), var w0 = calcbulletWidth(x0),w1 = bulletWidth(x1);) w1 = calcbulletWidth(x1);

5. Find the following return values and update as specified:


Original return value Updated return value

return (d.Ranges ? d.Ranges : []); return (mset2 ? [d[ms_range1], d[ms_range2], d[ms_range3]] : []);

return (d.Target ? d.Target : []); return (mset3 ? [d[ms_target]] : []);return (d.Actuals ? d.Actuals : []); return (mset1 ? [d[ms_actual], d[ms_pace]] :

[]);

6. Append the code from index.html to the end of the render function, beginning with the following two lines and ending before the </script> line:

// MDL: Added bullet width to make it easier to adapt to the page width.// MDL: Added bullet height so can calculate the y-position for each bullet SVG.

7. Find the following lines and change them as indicated:

Original Updated

var chart = d3.bullet() var chart = d3_bullet()function bulletWidth(x) { function calcbulletWidth(x) {.data(fdata) .data(data).text(function(d) { return (d.Titles && d.Titles.length > 0 ? d.Titles[0] : ""); });

.text(function(d) { return (dset1 && dset1.length > 0 ? d[dim_title] : ""); });

.text(function(d) { return (d.Titles && d.Titles.length > 1 ? d.Titles[1] : ""); });

.text(function(d) { return (dset1 && dset1.length > 1 ? d[dim_subtitle] : ""); });

var bulletWidth = 960; var bulletWidth = width;

8. In the style.css file, delete the default code and add the following:

.bullet { font: 10px sans-serif; }

.bullet .marker { stroke: #000; stroke-width: 2px; }

.bullet .tick line { stroke: #666; stroke-width: .5px; }

.bullet .range.s0 { fill: #eee; }

.bullet .range.s1 { fill: #ddd; }

.bullet .range.s2 { fill: #ccc; }

.bullet .measure.s0 { fill: lightsteelblue; }

.bullet .measure.s1 { fill: steelblue; }

.bullet .title { font-size: 14px; font-weight: bold; }

.bullet .subtitle { fill: #999; }

9. Click Run Code and check for errors.If there are errors, you will need to correct them.

Results

The Bullet Chart extension code is complete. You can generate the extension files and use them to create a bullet chart in SAP Lumira.



8.4 Testing the extension in VizPacker

To verify that you have converted the bullet chart correctly, test the extension code in VizPacker.

Context

Test the bullet chart extension code in VizPacker. When you have verified that there are no errors, you can generate the package that will be used in SAP Lumira.

Procedure

1. To validate your code and apply it to Preview Mode, click RUN CODE.If your code is correct, VizPacker does not display any messages. If there is a problem in your code, VizPacker displays an error message.

2. (Optional) If an error message appears, debug your code by doing the following:a. Close the error message.b. Right-click in the code editor and select Inspect element.

The debugging tools appear at the bottom of the window.c. Select the Console tab and check the error messages.d. Fix your code and click RUN CODE again to validate it.

3. To display Preview Mode, click the icon.The Preview Mode pane appears and displays the bullet chart.

4. When there are no more errors, generate the Bullet Chart extension files and pack them into a single ZIP file:a. In the top-right corner of VizPacker, click PACK.

A dialog box appears.b. To download the ZIP file, click the link to the file.

Your extension files are downloaded as a file called sap.viz.ext.bulletchart.zip.c. Close the dialog box.


8.5 Using the Bullet Chart extension in SAP Lumira

Add the visualization extension files to SAP Lumira and create the bullet chart.

Context

This procedure uses the bullet chart ZIP file (sap.viz.ext.bulletchart.zip) that you created and the bullet.csv file that you downloaded.

Procedure

1. From the ZIP file, copy the bundles and features folders into this folder:<installdir>\SAP Lumira\Desktop\extensions\

2. Start SAP Lumira.3. In SAP Lumira, acquire the data for the bullet chart:

a. Click File New .The New Dataset dialog box appears.

b. In the Select a Source section, double-click Text.c. Browse to the bullets.csv file and open it.d. Click Create.The data from bullets.csv is acquired as a dataset, and SAP Lumira displays the Visualize tab.

4. In the Chart Builder tab, click the Chart Extensions icon and select the Bullet Chart extension from the list that appears.

5. Add measures and dimensions to the data feeds as follows:

Table 3:

Data Feed Data to add to the feed

Actuals ○ Actual○ Pace

Target ○ Target

Ranges ○ Range 1○ Range 2○ Range 3

Titles ○ Title○ Subtitle

After you add the data, the bullet chart displays.



If the chart does not display correctly, you must debug your code. For more information, see Debugging an Extension in SAP Lumira [page 16]. These debugging instructions are written for the Hello World extension, but you can follow the same process to debug the bullet chart.

Results

You have successfully converted a D3 chart into an SAP Lumira extension and used it to create a visualization.

8.6 About the modified bullet chart code

The D3 bullet chart code must be modified to be compatible with VizPacker and dynamic data. In the tutorial, you downloaded a version of the code that was modified for you. This section explains the differences between the original code and the modified code.

The original bullet chart code consists of three files: index.html, bullet.js, and bullets.json. The modified version only has two files because the bullets.json code is embedded into the index.html file.

Changes made to index.html

In the index.html file, changes are denoted by comments that start with // MDL

The following changes were made to the code:

● Added the following SVG element:

<svg id="vis"></svg>

This element is used as the visualization container.● Added the following variable:

var vis = d3.select("#vis");

This variable is used in the render function to specify the visualization container.● Added the following attribute:

.attr("y", function(d, idx) { return bulletHeight * idx;})

This attribute determines the Y-axis position of each bar in the bullet chart and ensures that each bar appears on a new line on the page. The original bullet chart did not need this attribute because the chart used a DIV container instead of a SVG container, so each bar automatically appeared on a new line.

● Embedded the test data from the bullet.json file.Embedding the data lets you test the bullet chart files on a local machine. By default, Google Chrome won't let you load an external JSON file unless you run the files from a Web server.


● Renamed and combined the properties from the bullet.json file to match the names of the data feeds that you'll use in SAP Lumira:

○ Renamed the measures property to Actuals.○ Renamed the markers property to Target.○ Renamed the ranges property to Ranges.○ Combined the title and subtitle properties into a property called Titles.

● Removed the code for the Update button, the randomize function, and the randomizer function.You do not need this data randomization feature in SAP Lumira.

Changes made to bullet.js

In the bullet.js file, changes are denoted by comments that start with // MDL

The following changes were made to the code:

● Renamed three properties to match the names of the data feeds that you'll use in SAP Lumira:

○ Renamed the measures property to Actuals.○ Renamed the markers property to Target.○ Renamed the ranges property to Ranges.

● Added code to enable the bullet chart to display even when there is no data for Ranges or Target.

Related Information

How to add a D3 extension for SAP LumiraBullet Charts




http://help.sap.com/disclaimer?site=http://bl.ocks.org/mbostock/4061961

9 Importing Source Code into the Sample HTML File

VizPacker generates a sample HTML page that you can use with sample data to debug your extension. The page includes several JavaScript files by default, but some extensions may require you to import additional JavaScript files.

By default, the HTML page imports several JavaScript files that are required for all visualizations. In the following code, the first four files are open-source libraries that the charting engine (SAP CVOM) requires, and the last file (sap.viz.js) is the CVOM library:

<script type="text/javascript" src="../../../libs/require.js"></script><script type="text/javascript" src="../../../libs/d3.v2.js"></script><script type="text/javascript" src="../../../libs/jquery.js"></script>

<script type="text/javascript" src="../../../libs/sap.viz.js"></script>

To load the Hello World extension, verify that the following code is in the HTML page:

requirejs.config({ baseUrl : '../bundles/sap/viz/ext/helloworld' }); require([ 'helloworld-bundle' ], function() {

SAP Lumira Visualization Extensions Developer GuideImporting Source Code into the Sample HTML File © 2014 SAP SE or an SAP affiliate company. All rights reserved. 29

10 Updating Visualization Data at Runtime

If the data is changed after the visualization is initialized, you can update the visualization to display the new data by calling the update API.

For example, in the following code, the data is stored in a JSON object called dataset:

var crosstabDataset = new sap.viz.api.data.CrosstableDataset();crosstabDataset.data(dataset);var vizInstance = sap.viz.api.core.createViz({ type : 'viz.ext.helloworld', data : crosstabDataset, container : $("#chart"), properties : chartProperties, feeding : feeding });

You can update the data at runtime by making the necessary modifications to dataset and then calling the update API:

crosstabDataset.data(dataset);vizInstance.update({data: crosstabDataset });


Updating Visualization Data at Runtime

11 Updating Extensions for the New Extension Framework

As of SAP Lumira 1.14, the program uses a new extension framework. To use an extension that was created before SAP Lumira 1.14, you must convert the code to use the flow API.

Extensions do not use the MANIFEST file anymore, and the definitions in the extension code use the flow API instead of a JSON format.

11.1 Using the flow API to add chart elements

Use the flow API to create a flow, which lets you add elements to a chart and arrange them.

There are four types of flows:

Table 4:

Flow type Description

SVG Each flow of this type can contain only one element. These flows set the element in the center of the visualization.DIV

BorderSVGFlow Each flow of this type can contain multiple elements.

These flows can set elements in these positions:

● top● left● bottom● right● center

BorderDIVFlow

Using common functions

Chart elements can inherit and use common functions from the BaseGraphic class, which is provided by the charting engine (SAP CVOM). For example, in the following code, the element inherits functions from BaseGraphic and also uses any functions that you write in the moduleFunc object:

element.implement('sap.viz.elements.common.BaseGraphic', moduleFunc);

SAP Lumira Visualization Extensions Developer GuideUpdating Extensions for the New Extension Framework © 2014 SAP SE or an SAP affiliate company. All rights reserved. 31

Reusing elements from CVOM

You can reuse the title and legend elements from CVOM by creating an element that uses the ID of the CVOM element. The following table shows the IDs of these elements:

Table 5:

CVOM element ID

Title sap.viz.chart.elements.Title

Legend sap.viz.chart.elements.ColorLegend

For example, to reuse the legend, you would create the following element in your chart:

var legendElement = sap.viz.extapi.Flow.createElement({ id : 'sap.viz.chart.elements.ColorLegend', name : 'Legend',});

NoteWhen you reuse an element from CVOM, the flow type must be BorderSVGFlow because CVOM elements are SVG elements.

11.2 Converting the chart type definition to flow API

To use an extension from an earlier version of SAP Lumira, you may need to replace the chart type definition with flow API code.

In extensions that were created before SAP Lumira 1.14, the chart type definition was written in a JSON format, as shown in the following code:

/*Chart Type Definition*/var chart = { id : 'viz/ext/elect', name : 'Electrical Chart', modules : { root : { id : 'sap.viz.modules.rootContainer', modules : { main : { id : { 'sap.viz.modules.xycontainer', modules : { plot: { id : 'viz.ext.modules.elect', configure : { propertyCategory : 'elect' } } }, configure : { properties : { layout : {


Updating Extensions for the New Extension Framework

position : 'center', priority : 1 } } } }, } } },};

To make this definition compatible with the newer versions of SAP Lumira, you must convert the definition to use the flow API, as shown in the following code:

var flow = sap.viz.extapi.Flow.createFlow({ id : 'viz/ext/elect', name : 'Electrical Chart', dataModel : 'sap.viz.api.data.CrosstableDataset', type : 'BorderSVGFlow'});var element = sap.viz.extapi.Flow.createElement({ id : 'viz.ext.module.elect', name : 'Elect Module', place: 'center'});element.implement('sap.viz.elements.common.BaseGraphic', moduleFunc);flow.addElement ({ 'element': element, 'propertyCategory' : 'elect'});

11.3 Converting the feed definition to flow API

To use an extension from an earlier version of SAP Lumira, you may need to replace the feed definition with flow API code.

In extensions that were created before SAP Lumira 1.14, the feed definition was written in the following format:

/*Feed Definition*/var valueFeed = { 'id' : 'sap.viz.modules.elect.valueaxis1', 'name' : 'Primary Values', 'type' : 'Measure', 'min' : 1, 'max' : Number.POSITIVE_INFINITY, 'mgIndex' : 1};

var entityFeed = { 'id' : 'sap.viz.modules.elect.entity', 'name' : 'Entity', 'type' : 'Dimension', //'minStackedDims': 3, //'maxStackedDims': 3, 'min' : 1, 'max' : Number.POSITIVE_INFINITY, 'acceptMND' : false, 'aaIndex' : 1};


/*Module Definition*/var module = { 'id' : 'viz.ext.modules.elect', 'type' : 'CHART', 'name' : 'Electrical', 'datastructure' : 'DATA STRUCTURE DOC', 'properties' : {}, 'events' : {}, 'feeds' : [valueFeed, entityFeed], 'css' : null, 'configure' : null, 'fn' : moduleFunc};

To make this definition compatible with the newer versions of SAP Lumira, you must convert the definition to use the flow API, as shown in the following code:

var ds1 = { "id" : "viz.ext.module.HelloWorldModule.DS1", "name" : "Entity", "type" : "Dimension", "min" : 0, "max" : 2, "aaIndex":1};//ms1: Margin, Quantity sold, Sales revenuvar ms1 = { "id" : "viz.ext.module.HelloWorldModule.MS1", "name" : "Sales Data", "type" : "Measure", "min" : 0, "max" : Infinity, "mgIndex" : 1};element.addFeed(ds1);element.addFeed(ms1);

After you add a feed definition to an element, you can bind data to that element.

11.4 Registering modules

To use an extension from an earlier version of SAP Lumira, you may need to replace the module definition with flow API code. If you use the flow API, then you do not need to register the module.

In extensions that were created before SAP Lumira 1.14, modules had to be registered before you could use them in a chart. The following code was used to register modules:

sap.viz.extapi.manifest.Module.register(module);

In the newer versions of SAP Lumira, you do not need to register the module. To create a module for your chart, all you need to do is use the flow API to create the module as an element.



11.5 Registering chart typesTo use an extension from an earlier version of SAP Lumira, you may need to replace the chart registration code with flow API code.

In extensions that were created before SAP Lumira 1.14, chart types had to be registered before you could use them. The following code was used to register chart types:

sap.viz.extapi.manifest.Viz.register(chart);

In the newer versions of SAP Lumira, you create a flow to represent the chart type, and then use the following code to register the flow:

sap.viz.extapi.Flow.registerFlow(flow);

However, making your extension compatible with the updated extension framework requires more than just replacing the function. When the extension framework is loaded, it will load each bundle by ID. You must write additional code so that when the bundle is loaded, the component's instance is called to register the bundle.

In the following code, a flow definition bundle is added into vizExtBundle, which is then registered into the global BI extension framework. The component instance that is called is vizExtImpl.

var flowDefinition = { id : flowRegisterFunc.id, init : flowRegisterFunc};

/*<<bundle*/var vizExtImp1 = { vix : [flowDefinition], module : [], feeds : []};var vizExtBundle = sap.bi.framework.declareBundle({ "id" : "viz.ext.helloworld", "loadAfter" : ["sap.viz.aio"], "components" : [{ "id" : "viz.ext.helloworld", "provide" : "sap.viz.impls", "instance" : vizExtImp1, "customProperties" : { "name" : "Hello World", "Description" : "Hello World", "icon" : {"path" : ""}, "category" : [], "resources" : [] } }]});// sap.bi.framework.getService is defined in BundleLoader, which is// always available at this timeframe// in standalone mode sap.viz.js will force load and activate the// "sap.viz.aio" bundleif (sap.bi.framework.getService("sap.viz.aio", "sap.viz.extapi")) { // if in standalone mode, sap.viz.loadBundle will be available, // and we load the bundle directly sap.bi.framework.getService("sap.viz.aio", "sap.viz.extapi").core.registerBundle(vizExtBundle);} else { // if loaded by the extensionf ramework, return the "sap.viz.impls" //provider component via define()


define(function() { return vizExtBundle; });}

To ensure that the extension bundle can register the flow by calling the init method that is in flowDefinition, put the entire flow definition into a bundle in the init method.

In the preceding code, the bundle in the init method is called flowRegisterFunc. The following code shows how the entire flow definition code is placed into this bundle.

NoteTo ensure that the extension framework registers the correct flow, the flowRegisterFunc bundle must have the same ID as the flow.

/*flow Definition*/var flowRegisterFunc = function(){ var flow = sap.viz.extapi.Flow.createFlow({ id : 'viz.ext.helloworld', name : 'Hello World', dataModel : 'sap.viz.api.data.CrosstableDataset', type : 'BorderSVGFlow' }); var legendElement = sap.viz.extapi.Flow.createElement({ id : 'sap.viz.chart.elements.ColorLegend', name : 'Legend', }); flow.addElement({ 'element':legendElement, 'propertyCategory':'legend', 'place':'right' }); var element = sap.viz.extapi.Flow.createElement({ id : 'viz.ext.module.HelloWorldModule', name : 'Hello World Module', }); element.implement('sap.viz.elements.common.BaseGraphic', moduleFunc); /*Feeds Definition*/ //ds1: City, Year var ds1 = { "id": "viz.ext.module.HelloWorldModule.DS1", "name": "Entity", "type": "Dimension", "min": 0, "max": 2, "aaIndex": 1 }; //ms1: Margin, Quantity sold, Sales revenue var ms1 = { "id": "viz.ext.module.HelloWorldModule.MS1", "name": "Sales Data", "type": "Measure", "min": 0, "max": Infinity, "mgIndex": 1 }; element.addFeed(ds1); element.addFeed(ms1); flow.addElement({ 'element':element, 'propertyCategory' : 'viz.ext.helloworld' }); sap.viz.extapi.Flow.registerFlow(flow);



};flowRegisterFunc.id = 'viz.ext.helloworld';


Important Disclaimers and Legal Information

Coding SamplesAny software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral LanguageAs far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet HyperlinksThe SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer).


Important Disclaimers and Legal Information

http://help.sap.com/disclaimer/

www.sap.com/contactsap

© 2014 SAP SE or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company 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.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

http://www.sap.com/contactsap

http://www.sap.com/corporate-en/legal/copyright/index.epx

http://www.sap.com/corporate-en/legal/copyright/index.epx