Best Practices for Visualization Extensions

Even though open sourced extensions are not formally SAP extensions, we request that simple guidelines are followed to ensure a basic level of quality.

1. CSS is name-spaced

CSS should be defined such that conflicts with other extensions do not occur. Please use classes that are prefixed by your extension ID and remember that multiple instances of your extension might appear on the same html page (in a story, report or infographic created in the compose room). For example, instead of “.lines”, “.sap_viz_ext_footballheatmap_lines” is preferred.

This is a very important point to keep in mind because if CSS class names conflict with those in other extensions, Lumira may not be able to identify unique classes and will end up in an overlap of different class definitions. This will most likely result in Lumira crashing or not properly rendering charts. Not following this practice for a particular extensions can affect all other extensions installed in Lumira.

2. No modification of global state
JavaScript code, including libraries, should be defined within your extension as Asynchronous Module Definitions compatible with requirejs. Code should not create top-level objects because this leads to conflicts between extensions. Do not modify the global requirejs context (such as by installing requirejs plugins), but do feel free to require the “require” module, modify its context and then use it for loading resources.

3. No access to DOM outside of container
Extension code must not access or modify the document outside of its assigned container. The DOM is not a public interface and will change between versions.

4. No disallowed dependencies or resource access
Bundles should access only their own resources and external-to-Lumira resources. Accessing or referencing paths within Lumira but outside of the bundle, such as to a different extension, is not safe. Do not hard-code paths to resources within your bundle that reference locations outside of your bundle (like “/sap/bi/bundles/mybundle/myresource”). Assume that the extension’s root location will change and construct the URL dynamically. This can be done by requiring the “require” module and calling its toUrl() function.
Read more on David Dalley‘s blog.

5. Vendor metadata contains either employee’s name or “Community Contribution”
The vendor name in the feature file (extname-feature.json) should either be your own name or “Community Contribution” if you prefer. The vendor name value in this file corresponds to the value that was entered for “Company Name” during project creation in Web IDE. We’re no longer putting “SAP” in this field, since these extensions would show up as ‘created by SAP’ in the extensions manager and thus create an expectation that these extensions are indeed created and supported by SAP. Of course, that is not the case.

6. Avoid hard coupling between the code and data structure

• No direct reference of column name

• Allow dynamic number of measures in a measure set, if applicable (e.g. make use of d3.keys())

• Reference dimension sets and measure sets by their name for better code readability

7. Naming conventions for project files

When creating your Web IDE project, it is very important to use proper naming conventions for different modules of the project:

• Name your dataset(.csv file) uniquely according to your project name. For example, data.csv can be named population_pyramid.csv
• Assign proper names to dimension and measure sets. For example, if there is just one dimension called “Year”, name the dimension set “Year” instead of “Dimension”. If there is a specific order of using measures or dimensions, specify them in the measure/dimension name field.
• It is recommended to provide a short description of the extension to give users more insight.

8. Legend & Title

When creating the Web IDE project, make sure to have Title and Legend checked and included. These can be removed later on, but we want to make sure that they are there in the project so that in case someone wants to modify an existing extension and wants to have them in the project again.

9. Avoid GPL-licensed third party code

If you must make use of third party code or libraries in your extension, make sure they are not licensed under the GPL (GNU Public License), to avoid legal complications later on, in open-sourcing the code.

For us to publish an open source extension, we request that it is accompanied by a blog on SCN. The blog will be your ‘business card’ and should follow certain content recommendations: to increase popularity of both the blog and the extension.

• Section 1
  Short description / summary
  What exactly is this extension, what business need is it addressing? This section can be placed on the left hand side, covering 75% of the width of the blog space.

• Section 2
  Link to GitHub repository
  Preferably at the top right corner of the blog so that people don’t have to scroll down. This section can be placed adjacent to Section 1 on the right hand side, covering the remaining 25% of the total width.

• Section 3
  More details about:
  • Business need / challenge you are addressing. Why this chart, data access extension?
  • Explain the used data set (which is included in github)
  • Demonstrate how to use the chart including Dimensions & Measures used
  • How did you go about developing the extensions – lessons learned, things to avoid

      This section can continue below the first two adjacent sections and cover the entire width of the page.

• In any section
  Screenshots (e.g., of the visualization). Add a video, if you have one (e.g., YouTube)