Visualization Extension Plugin Version: 1.0.0-2014-12-04 Visualization Extension Plugin for SAP Web IDE
Content 1 Visualization Extension Plugin Overview....3 1.1 About the visualization extension plugin.... 3 1.2 Restrictions for the visualization extension plugin....3 2 Enabling the Vizpacker plugin....4 3 Creating a Visualization Extension.... 5 3.1 Creating the visualization extension project....5 3.2 Editing the visualization extension render.js file....8 3.3 Adding the extension to SAP Lumira....9 3.4 Using the extension in SAP Lumira.... 10 4 Examples: Creating Visualization Extensions.... 11 4.1 Additional examples in SCN....11 4.2 Creating a population pyramid extension.... 11 4.2.1 Preparing the population pyramid D3 code....11 4.2.2 Setting up the population pyramid project....12 4.2.3 Editing the population pyramid render.js and default.css files....14 2 2014 SAP SE or an SAP affiliate company. All rights reserved. Content
1 Visualization Extension Plugin Overview Learn how to use the Visualization Extension (Vizpacker) plugin in SAP Web IDE. 1.1 About the visualization extension plugin The Visualization Extension plugin (Vizpacker) is used in SAP Web IDE to create chart extension packages that can be used within Lumira and other products. Vizpacker provides an extension framework with an associated API that lets you customize existing visualizations or develop your own visualization extensions and integrate them with SAP Lumira or other products. Workflow Creating and testing the extension involves the following process: 1. Creating the visualization extension project. 2. Modifying the JavaScript code template (render.js) to complete the extension code. 3. Preparing the extension for use in SAP Lumira. 1.2 Restrictions for the visualization extension plugin This section provides you with information on restrictions to be aware of and workarounds you can apply while using the Visualization Extension plugin for SAP Web IDE. Supported languages The Visualization Extension plugin for SAP Web IDE supports English only. Safari browser is not supported The Visualization Extension plugin for SAP Web IDE does not support the Safari (Mac) browser, because Safari does not support downloads for the BLOB type. Visualization Extension Plugin Overview 2014 SAP SE or an SAP affiliate company. All rights reserved. 3
2 Enabling the Vizpacker plugin Before you can use the Vizpacker plugin, you need to enable it. Context The vizpacker plugin is one of several plugins for SAP Web IDE. Procedure 1. Open SAP Web IDE. 2. Choose Tools External Plugins. 3. From the Plugin Repository list, choose SAP Plugins. 4. Find the vizpacker plugin and enable it. 5. Choose OK. Results The vizpacker plugin is enabled and the icon is displayed in SAP Web IDE. 4 2014 SAP SE or an SAP affiliate company. All rights reserved. Enabling the Vizpacker plugin
3 Creating a Visualization Extension This tutorial will show you how to create your own extension using the Vizpacker plugin in SAP Web IDE. The first project that you will create using the Vizpacker plugin will just display the words Hello World! instead of actual data. The purpose of this exercise is to get familiar with the plugin. Creating and testing Vizpacker involves the following process: 1. Create a project. 2. For the data source for your project, upload a CSV file. 3. Customize the code and style options. 4. Prepare the extension for use in SAP Lumira. 5. Extract the contents of the ZIP file and deploy to SAP Lumira. 3.1 Creating the visualization extension project Set up the project, including uploading the CSV file and configuring the data structure and data binding options. Procedure 1. Choose File New Project from Template. 2. In the Select a Template page, in the categories list, choose Visualization Extension and then choose Next. Tip To see all the available templates, choose All Categories. 3. Type a Project Name for your project: Hello_World Note Project names may contain upper and lower case characters (a-z, A-Z), digits 0-9, periods, dashes, and underscores. Example Incorrect project ID: Project with spaces & special chars Correct project ID: Project_no-spaces27 Creating a Visualization Extension 2014 SAP SE or an SAP affiliate company. All rights reserved. 5
4. Choose Next. The Visualization Extension Profile page appears. 5. Type an Extension Name: Hello World test 6. Type an Extension ID; the extension ID may contain lower case characters (a-z), digits 0-9, and periods. To avoid naming conflicts, use the following naming convention for your ID: <your_company_name>.viz.ext.<extension_name> Example sap.viz.ext.helloworld 7. Choose Next. The Quick Layout Configuration page appears. 8. In the Select re-usable modules section, choose your configuration options: Option Description Plot Area Technique: using SVG using DIV - use DIV if you will be embedding HTML elements in your project Title Title text - Enter a title. Position - Top or Bottom Alignment - Center aligned Left aligned Right aligned Legend Position - Left or Right a. For Plot Area, choose Using DIV. b. Enter a title: Hello World test c. For Legend, clear the checkbox. 9. Choose Next. The Upload Sample Data page appears. 10. Upload your CSV file. Numeric data is uploaded as Measure and all other data is uploaded as Dimension. Change the type for each column by choosing the data label name. Example We have no specific data for this example, so we will use the provided CSV file. 11. Choose Next. 6 2014 SAP SE or an SAP affiliate company. All rights reserved. Creating a Visualization Extension
The Configure Data Structure & Data Binding page appears. 12. Provide names for your Measure Set and Dimension Set. If relevant, you can add more sets. 13. Add your measures and dimensions to the appropriate sets. Example For this example, we do not need to add any measures or dimensions. 14. Choose Next and then choose Finish. Creating a Visualization Extension 2014 SAP SE or an SAP affiliate company. All rights reserved. 7
Results Your visualization extension project is created. The project is displayed and the render.js file is opened. 3.2 Editing the visualization extension render.js file Modify the default render.js file to work with the visualization extension. Context Remove the default placeholder code and add in your code. For the Hello World example extension, the code just displays the text Hello World!. 8 2014 SAP SE or an SAP affiliate company. All rights reserved. Creating a Visualization Extension
Procedure 1. Delete the line of code that begins with //TODO and type the following lines of code: container.selectall("p").remove(); container.append("p").text("hello World!"); 2. Save the file. Choose Refresh to see the result of the changes. 3. To create a ZIP file, choose Pack. Save the file to a convenient location. Results Your ZIP file contains two folders: bundles and features. These folders contain the files that you need to use the extension in SAP Lumira. 3.3 Adding the extension to SAP Lumira Add the visualization extension to SAP Lumira. Prerequisites If SAP Lumira is running, exit the program. Procedure 1. Copy the extension ZIP file to the machine that has SAP Lumira installed. You should also copy your dataset to the same machine. 2. Extract the contents of the ZIP file. 3. Copy the bundles and features folders to <installdir>\lumira\desktop\extensions\ Creating a Visualization Extension 2014 SAP SE or an SAP affiliate company. All rights reserved. 9
3.4 Using the extension in SAP Lumira After you create your extension, use it in SAP Lumira. Context The examples in this procedure refer to the Hello World sample project. Procedure 1. Launch SAP Lumira. 2. To start a new file, choose File New. 3. In the New Dataset dialog, double-click Text. 4. Upload your dataset and then choose Create. Example Select any dataset on your computer and then choose Create. 5. In the Visualize room, choose your extension and then add measures and dimensions. Example 1. In the Chart Builder tab, choose Chart Extensions and then choose Hello World test. 2. Add one measure and one dimension. Results You will see your visualization. 10 2014 SAP SE or an SAP affiliate company. All rights reserved. Creating a Visualization Extension
4 Examples: Creating Visualization Extensions Use existing charts or extensions - with modifications - to learn how to create visualizations. To help demonstrate how to use the visualization extension plugin, this section has some examples that you can set up in SAP Web IDE and import into SAP Lumira. 4.1 Additional examples in SCN You can find more information about visualization extensions on the SAP Community Network (SCN). The SAP Lumira community pages contain visualization extension examples, including examples that are written for the Vizpacker plugin for SAP Web IDE. 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/content. 4.2 Creating a population pyramid extension Creating and testing the population pyramid extension involves the following process: 1. Retrieve and prepare the existing D3 code for the population pyramid. 2. Create the project. 3. Edit the code and style options. 4. Extract the contents of the ZIP file and deploy to Lumira. 4.2.1 Preparing the population pyramid D3 code Context The original D3 code for the Population Pyramid is at the following location: http://bl.ocks.org/mbostock/ 4062085 Examples: Creating Visualization Extensions 2014 SAP SE or an SAP affiliate company. All rights reserved. 11
Procedure 1. Copy the contents of the Population CSV section (population.csv ) to a text editor. a. Save the text file as population.csv 2. Copy the contents of index.html to a text editor. a. Save the text file as population.html This code will be used after you create your project. 4.2.2 Setting up the population pyramid project Create a population pyramid project in SAP Web IDE using the Visualization Extension plugin. Procedure 1. Start SAP Web IDE. 2. Choose File New Project from Template. 3. In the Select a Template page, in the categories list, choose Visualization Extension and then choose Next. Tip To see all the available templates, choose All Categories. 4. In the Project Name field, type PopulPyramid 5. Choose Next. The Visualization Extension Profile page appears. 6. For the Extension Name, type Population Pyramid. 7. For the Extension ID, type sap.viz.ext.populpyramid 8. Choose Next. The Quick Layout Configuration page appears. 9. In the Select re-usable modules section, set your configuration options: Plot area: using SVG Title: Title - Enter Population Pyramid Position - choose Top Alignment - choose Center aligned Legend: clear the checkbox 10. Choose Next. The Upload Sample Data page appears. 11. Upload population.csv. 12. Choose the heading in the following fields and change the type to Dimension: year, age, sex 13. Choose Next. 12 2014 SAP SE or an SAP affiliate company. All rights reserved. Examples: Creating Visualization Extensions
The Configure Data Structure & Data Binding page appears. 14. Change the Measure Set heading to People 15. Change the Dimension Set heading to Year/Age/Sex 16. In the measure set, add people 17. In the dimension set add year, age, and sex 18. Choose Next. 19. Choose Finish. Results The Population Pyramid project is created, and render.js is opened in the code editor. Examples: Creating Visualization Extensions 2014 SAP SE or an SAP affiliate company. All rights reserved. 13
Figure 1: Default render.js file created for the Visualization Extension plugin Next Steps Modify the code in render.js 4.2.3 Editing the population pyramid render.js and default.css files Modify the default render.js file to work with the population pyramid visualization extension. Prerequisites Open the population.html code in a text editor. 14 2014 SAP SE or an SAP affiliate company. All rights reserved. Examples: Creating Visualization Extensions
Procedure 1. Type the following code in the render function: var measet = data.meta.measures("people"); var mpeople = measet[0]; var dimset = data.meta.dimensions("year/age/sex"); var dyear = dimset[0]; var dage = dimset[1]; 2. In the population.html file, select all the text between the script tags and append it in the render function below the code from the previous step. 3. Update the <width> and <height> values. a. Delete the following lines: width = 960 - margin.left - margin.right, height = 500 - margin.top - margin.bottom, b. Add the following lines: 4. Update the SVG variable. Change the following lines: width = this.width() - margin.left - margin.right, height = this.height() - margin.top - margin.bottom, var svg = d3.select("body").append("svg").attr("width", width + margin.left + margin.right) to the following lines: container.selectall("g").remove(); var svg = container.attr("width", width + margin.left + margin.right) 5. Delete the population.csv line and its closing brackets. Delete this line: d3.csv("population.csv", function(error, data) { The closing brackets are the last line in the following block of text: } birthyear.selectall("rect").data(function(birthyear) { return data[year][birthyear] [0, 0]; }).transition().duration(750).attr("y", y).attr("height", function(value) { return height - y(value); }); }); Examples: Creating Visualization Extensions 2014 SAP SE or an SAP affiliate company. All rights reserved. 15
6. Replace the following values: Old value d.people d.year d.age New value d[mpeople] d[dyear] d[dage] 7. To prevent the visualization extension from impacting other extensions, add a class called rectbars Original code section: birthyear.selectall("rect").data(function(birthyear) { return data[year][birthyear] [0, 0]; }).enter().append("rect").attr("x", -barwidth / 2).attr("width", barwidth).attr("y", y).attr("height", function(value) { return height - y(value); }); Revised code section (fourth line was added): birthyear.selectall("rect").data(function(birthyear) { return data[year][birthyear] [0, 0]; }).enter().append("rect").attr("class", "rectbars").attr("x", -barwidth / 2).attr("width", barwidth).attr("y", y).attr("height", function(value) { return height - y(value); }); 8. Save the file. 9. Open the CSS stye file (style/default.css) 10. In the population.html file, select all the text between the style tags and append it to default.css. 11. Change the two lines that contain the value rect to now be rect.rectbars 12. Save the file. Choose Refresh to see the result of the changes. 13. To create a ZIP file that you can use with SAP Lumira, choose Pack. Save the file to a convenient location. Results You are now ready to use the extension in SAP Lumira. Related Information Using the extension in SAP Lumira [page 10] 16 2014 SAP SE or an SAP affiliate company. All rights reserved. Examples: Creating Visualization Extensions
Important Disclaimers and Legal Information Coding Samples Any 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. Accessibility The 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 Language As 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 Hyperlinks The 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 2014 SAP SE or an SAP affiliate company. All rights reserved. 17
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.