Transcript SAP Lumira SDK Getting Started Guide

SAP Lumira SDK
Document Version: 1.15 - 2014-04-02
SAP Lumira SDK Getting Started Guide
Table of Contents
1
SAP Lumira SDK Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1
About the SAP Lumira SDK and VizPacker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2
Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2
Creating a New Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1
Creating a unique name for your extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2
Generating the extension files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
2.3
Modifying the extension file JavaScript code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4
Testing the extension in a browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3
Using an Extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1
Installing the extension to SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
3.2
Testing the extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4
Importing source code into the sample HTML file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5
Updating visualization data at runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6
Debugging the Extension in SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1
Enabling the debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2
Accessing the debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.3
Finding and debugging your code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7
Updating Extensions for the New Extension Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1
Using the flow API to add chart elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.2
Converting the chart type definition to flow API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
7.3
Converting the feed definition to flow API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.4
Registering modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
7.5
Registering chart types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
8
Sample extensions for SAP Lumira. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.1
Flagbar chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
8.2
Sample bar chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
9
Known limitations and workarounds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Table of Contents
1
SAP Lumira SDK Overview
1.1
About the SAP Lumira SDK and VizPacker
The SAP Lumira SDK lets you create new chart types as extensions and use them in SAP Lumira. The SDK
includes the VizPacker utility, which helps you create the files and folders for an extension.
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. The SAP Lumira SDK 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 the VizPacker instead of manually creating the files and folders lets you focus on
modifying the content of your code.
VizPacker generates these folders:
Folder
Description
examples
Contains an HTML page for testing the extension.
bundles
Contains a JavaScript file template for the extension.
This file is used for loading the extension in SAP Lu­
mira, and it can also be used in the HTML test page.
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.
1.2
Prerequisites
Before you can use the 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.
Ensure that the following requirements are met:
●
The following programs have been installed:
○
SAP Lumira 1.15 or later
You can download a free copy of SAP Lumira Personal Edition from: http://sap.com/buylumira
●
○
Google Chrome
VizPacker can only be used in Google Chrome.
○
Notepad++ or another JavaScript editor of your choice.
You are familiar with the following languages and libraries:
○
JavaScript
○
HTML5
SAP Lumira SDK Getting Started Guide
SAP Lumira SDK Overview
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
3
○
D3 (Data Driven Documents)
○
jQuery
The SAP Lumira SDK uses D3. For more information about D3, see http://d3js.org/
●
You can access the SDK folders that are included in an installation of SAP Lumira:
Folder name
Description
Location
vizPacker
Contains the VizPacker utility.
<installdir>\SAP Lumira
\Desktop\utilities\viz­
Packer
extension
Contains extensions that have
been installed for use in SAP Lu­
mira.
<installdir>\SAP Lumira
\Desktop\extensions
charts
Contains sample extensions.
<installdir>\SAP Lumira
\Desktop\samples\exten­
sions\charts
libs
Contains libraries that you can use <installdir>\SAP Lumira
to test extensions outside of SAP
\Desktop\libs
Lumira (for example, in a web
browser).
Note
By default, the install directory for SAP Lumira is C:\Program Files
4
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
SAP Lumira SDK Overview
2
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.
Use VizPacker to generate the extension files, which include a JavaScript code template file and an HTML test file.
After the files have been created, complete the extension by modifying the template file.
2.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.
To create a unique extension name, use the following naming convention:
<company name>.viz.ext.<extension name>
For example:
sap.viz.ext.helloworld
Note
You must use lower case characters in extension names.
Note
Extensions that were created before SAP Lumira 1.14 follow a different naming convention, using slashes
(/) instead of periods (.) as separators.
For example:
sap/viz/ext/helloworld
SAP 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.
2.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.
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.
SAP Lumira SDK Getting Started Guide
Creating a New Extension
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
5
○
3.
Close the welcome screen.
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 of the Plot Area.
The Property Setting: Chart dialog box appears.
b) Change the settings to the following:
○
ID: viz.ext.helloworld
○
NAME: Hello World
c) To apply your changes, click an area outside of 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: viz.ext.helloworld.helloworldmodule
○
NAME: Hello World Module
c) To apply your changes, click an area outside of 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.
Generate all the files and pack them into a single ZIP file:
a) In the top-right corner, 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 viz.ext.helloworld.zip.
c) Close the dialog box.
After generating the extension files, complete the Hello World extension by modifying the code.
Note
This tutorial shows you how to generate the files using VizPacker and then edit them externally, but you can
also edit and preview your code directly inside VizPacker.
2.3
Modifying the extension file JavaScript code
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.
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.
1.
Locate the ZIP file that you downloaded in Generating the extension files.
2.
Create the following folder and extract the ZIP file into it: <installdir>\SAP Lumira\Desktop
\myextensions\viz.ext.helloworld
3.
Launch Notepad++ and open the following file:
6
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Creating a New Extension
<installdir>\SAP Lumira\Desktop\myextensions\viz.ext.helloworld\bundles\viz\ext
\helloworld\helloworld­bundle.js
4.
Move the fdata line (and the two lines of comments preceding it) to the top of the render function.
This line converts the SAP Lumira crosstable data format into a simple JavaScript array that can be used in
the extension.
After moving the fdata code and comments, you will have the following code:
function render(data, vis, width, height, colorPalette, properties, dispatch) {
//fetch data from imported data (in cross table format) and convert them.
//if you are not familiar with cross tables or pivot tables, you can convert
the data to flat table format as follows
var fdata = _util.toFlattenTable(data);
/*
* Start: You can remove all the code in this render function between the
Start and End comments
* and replace it with your own implementation code.
* You can also remove the Start and End comment blocks.
*/
5.
In the render function, delete the template code and the comments surrounding the template code:
a) Select the following comments in the file:
/*
* Start: You can remove all the code in this render function between the
Start and End comments
* and replace it with your own implementation code.
* You can also remove the Start and End comment blocks.
*/
b) Continue selecting lines of text, including the following comments:
/*
* End: You can remove all the code in this render function between the
Start and End comments
* and replace it with your own implementation code.
* You can also remove the Start and End comment blocks.
*/
c) Delete the selected text.
The render function should now look like the following:
function render(data, vis, width, height, colorPalette, properties, dispatch) {
//fetch data from imported data (in cross table format) and convert them.
//if you are not familiar with cross tables or pivot tables, you can convert
the data to flat table format as follows
var fdata = _util.toFlattenTable(data);
}
6.
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 render function:
vis.append("text").text("Hello World").attr("y", 20).attr("font­size", "large");
The render function should now look like the following:
function render(data, vis, width, height, colorPalette, properties, dispatch) {
//fetch data from imported data (in cross table format) and convert them.
//if you are not familiar with cross tables or pivot tables, you can convert
SAP Lumira SDK Getting Started Guide
Creating a New Extension
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
7
the data to flat table format as follows
var fdata = _util.toFlattenTable(data);
vis.append("text").text("Hello World").attr("y", 20).attr("fontsize",
"large");
}
7.
Save the file.
After modifying the code, test it in a browser to ensure that the extension works.
2.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.
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 extension file JavaScript
code, then the HTML file is at the following location:
<installdir>\SAP Lumira\Desktop\myextensions\viz.ext.helloworld\examples\example­
viz.ext.helloworld.html
When 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.
After verifying that the extension works in the browser, install it to SAP Lumira and test it in the program.
8
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Creating a New Extension
3
Using an Extension in SAP Lumira
3.1
Installing the extension to SAP Lumira
Before you can use an extension in SAP Lumira, you must install the extension.
Before you begin, ensure that you have created the Hello World extension. For more information, see Creating
a New Extension.
Copy the contents of your extension folder into this folder:
<installdir>\SAP Lumira\Desktop\extensions
For example, the JavaScript file for your extension should now be in the following location: <installdir>
\SAP Lumira\Desktop\extensions\bundles\viz\ext\helloworld\helloworld­bundle.js
Note
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.
After installing the extension, test it in SAP Lumira.
3.2
Testing the extension in SAP Lumira
To verify that the extension works correctly, try using it in SAP Lumira.
Before you begin, ensure that you have installed the extension.
1.
Start SAP Lumira.
2.
To access the Visualize tab, do one of the following:
3.
4.
○
Open a document.
You can use the built-in sample document, BestRunCorp ­ Margin Analysis.
○
Acquire data.
Select the Visualize tab.
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 will display the following message: Incomplete chart.
Please add more measures or dimensions.
After you add a measure and a dimension, the “Hello World” message displays.
If you do not see the message, then you must debug your code. For more information, see Debugging the
Extension in SAP Lumira [page 13].
SAP Lumira SDK Getting Started Guide
Using an Extension in SAP Lumira
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
9
You have just created and installed your first SAP Lumira extension.
10
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Using an Extension in SAP Lumira
4 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
<script
<script
<script
<script
<!­­ DO
­­>
type="text/javascript" src="../../../libs/require.js"></script>
type="text/javascript" src="../../../libs/d3.v2.js"></script>
type="text/javascript" src="../../../libs/jquery.js"></script>
type="text/javascript" src="../../../libs/json2.js"></script>
type="text/javascript" src="../../../libs/sap.viz.js"></script>
NOT CHANGE THE ORDER OF THE ABOVE SCRIPTS, OR INSERT ANYTHING BETWEEN THEM
For some extensions, you may need to import additional JavaScript files before you can display the extension in
the page. You can import additional files by adding code after the line that imports the CVOM library. By default,
the only additional file that an extension requires is its source JavaScript file. For example, you would use the
following code to import the file for the Hello World extension:
<script id="extension" type="text/javascript" src="../bundles/viz/ext/helloworld/
helloworld­bundle.js"></script>
SAP Lumira SDK Getting Started Guide
Importing source code into the sample HTML file
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
11
5
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 });
12
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Updating visualization data at runtime
6
Debugging the 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.
6.1
Enabling the debugger
Before you can use the debugger, you must enable it by modifying the SAP Lumira initialization file.
1.
Open the SAPLumira.ini file in a text editor, such as Notepad++.
The default location of the file is: <installdir>\SAP Lumira\Desktop\SAPLumira.ini
2.
To enable the debugger, add the following line of code:
­Dhilo.cef.frame.debug=true
3.
Save the file.
After you have enabled the debugger, access it in SAP Lumira.
6.2
Accessing the debugger
You can use the debugger in SAP Lumira to debug your extensions.
Before you begin, ensure that you have created the Hello World extension and enabled the debugger. For more
information, see Creating a New Extension and Enabling the debugger.
1.
Start SAP Lumira.
2.
To access the Visualize tab, do one of the following:
3.
4.
○
Open a document.
You can use the built-in sample document, BestRunCorp ­ Margin Analysis.
○
Acquire data.
Select the Visualize tab.
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 will display 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 of the visualization and select Show DevTools.
The debugger appears in a new window.
SAP Lumira SDK Getting Started Guide
Debugging the Extension in SAP Lumira
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
13
After opening the debugger, find your extension code in the window and debug it.
6.3
Finding and debugging your code
Because SAP Lumira uses HTML5, the debugger shows all the elements and source code of the extension in SAP
Lumira. You must find your extension code before you can start debugging it.
Before you begin, ensure that you have done the following in SAP Lumira:
●
Select the Hello World extension.
●
Add at least one measure and one dimension to the visualization.
●
Open the debugger.
For more information, see Using an Extension in SAP Lumira and Accessing the debugger.
To debug the Hello World extension, you must find its plot area (the DOM) and source code.
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 CtrlF 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.
Note
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 in SAP Lumira.
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/viz/ext/helloworld
d) Select your source file: helloworld­bundle.js
Your code appears in the window, and you can add breakpoints to debug it.
14
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Debugging the Extension in SAP Lumira
7
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.
7.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:
Flow type
Description
SVG
Each flow of this type can contain only one element.
DIV
These flows set the element in the center of the visu­
alization.
BorderSVGFlow
Each flow of this type can contain multiple elements.
BorderDIVFlow
These flows can set elements in these positions:
●
top
●
left
●
bottom
●
right
●
center
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 moduleFunct object:
element.implement('sap.viz.elements.common.BaseGraphic', moduleFunc);
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
15
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:
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',
});
Note
When you reuse an element from CVOM, the flow type must be BorderFlowSVGFlow because CVOM
elements are SVG elements.
7.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 : {
position : 'center',
16
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
};
},
}
}
},
}
}
}
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'
});
7.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*/
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
17
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 revenu
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);
After you add a feed definition to an element, you can bind data to that element.
7.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.
18
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
7.5
Registering chart types
To 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 components'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" bundle
if (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()
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
19
}
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.
Note
To 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);
20
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
};
flowRegisterFunc.id = 'viz.ext.helloworld';
SAP Lumira SDK Getting Started Guide
Updating Extensions for the New Extension Framework
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
21
8
Sample extensions for SAP Lumira
SAP Lumira provides several samples of extensions, including the flag bar (flagbar) chart and the sample bar
chart. You can refer to these examples when you are learning how to create extensions.
The sample extensions are located in this folder:
<installdir>\SAP Lumira\Desktop\samples\extensions\charts
You can also find additional samples on the SAP Community Network (SCN). The SAP Lumira community on the
SCN contains blog posts and sample files from users who created or modified extensions for specific use cases.
For example, users have created custom extensions to display airline statistics, movie statistics, and the paths
between destinations on a map. You can refer to these samples for more information about how you can work
with extensions.
To access the SAP Lumira community, go to http://scn.sap.com/community/lumira
8.1
.
Flagbar chart
The flagbar chart is a highly-customized sample extension for showing the top three medal-winning countries
from the 2004 and 2008 Olympic Games. The flagbar chart resembles a column chart, except that each column is
a dotted line with a country flag, and the label for each medal type displays an image of the corresponding medal.
22
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Sample extensions for SAP Lumira
To use the flagbar chart, you must use the sampledata_flagbar.xls dataset. You can change the data in the
dataset, but the data schema should stay the same. For information about downloading the dataset, see Dataset
for the Lumira flag bar extension
on the SAP Community Network.
Table 1: Extension Information
Field name
Value
Name
Flagbar Sample
ID
viz/ext/flagbar
Table 2: Feeding Information
Type of feed
Value
Dimensions (2)
1.
Medal type (Gold/Silver/Bronze)
2.
Country
Measures (1 or 2)
8.2
Number of medals (in Athens 2004 and/or in Beijing
2008)
Sample bar chart
The sample bar chart is a simple extension that serves as an example for anyone who is learning how to create
CVOM extensions. The sample bar chart resembles a column chart, except that it uses simplified versions of the
axes and the tooltip.
SAP Lumira SDK Getting Started Guide
Sample extensions for SAP Lumira
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
23
Table 3: Extension Information
Field name
Value
Name
Sample Bar Chart
ID
viz/ext/samplesbar
Table 4: Feeding Information
Type of feed
Value
Dimensions (2)
1.
Category group on the X-axis
2.
Category items in the group
Measures (1)
24
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
Value to show on the Y-axis
SAP Lumira SDK Getting Started Guide
Sample extensions for SAP Lumira
9
Known limitations and workarounds
This section provides you with information and workarounds for known limitations that you might encounter while
using SAP Lumira SDK or VizPacker.
VizPacker only works with Google Chrome (version 31.0 or later)
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/
VizPacker supports semicolon-delimited CSV files only
When you upload data in VizPacker, the data must be a CSV file that uses a semicolon (;) as the separator.
VizPacker does not support CSV files that use other separators.
To load extensions, the require.js library must be version 2.0 or later
The require.js library is used to load visualizations. require.js can load extensions only if it is version 2.0 or
later.
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.
All the JavaScript library codes for an extension must be in the same file
Because SAP Lumira loads each extension as a bundle, the extension library codes must be wrapped as one
bundle. To wrap the library codes in one bundle, the codes must be in the same file.
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.
SAP Lumira SDK Getting Started Guide
Known limitations and workarounds
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
25
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.
Integrations of ESRI Maps or Google Maps are not supported
SAP Lumira does not support extensions that use ESRI Maps or Google Maps.
26
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
SAP Lumira SDK Getting Started Guide
Known limitations and workarounds
SAP Lumira SDK Getting Started Guide
Known limitations and workarounds
© 2014 SAP AG or an SAP affiliate company. All rights reserved.
27
www.sap.com/contactsap
© 2014 SAP AG 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 AG.
The information contained herein may be changed without prior
notice.
Some software products marketed by SAP AG and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
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.
SAP 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.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.