Please switch to VizPacker for SAP Web IDE

SAP now recommends using VizPacker for SAP Web IDE for creating extensions. To find out more about the benefits and get started please read: SAP Web IDE – Analytics.

——

older post is below

—–

We have some great news for coders!

Updated for SAP Lumira 1.20 as there were improvements made for creating SAP Lumira  extensions since this was first written.

SAP Lumira (for  desktop) includes the  vizPacker utility that makes it quick and easy to create and package visual extensions for SAP Lumira.

I am going to walk you through every developers favorite example of Hello World using the vizPacker.

Step by step guide

What applications do you need?

You need to install:

  1. SAP Lumira 1.20 or later (which includes vizPacker), you can get your free Personal Edition here
  2. Google Chrome as vizPacker only works with Google Chrome

What languages or libraries do you need to know?

To be able to create visual extensions for SAP Lumira you need to have a good understanding of:

  1. HTML5
  2. JavaScript
  3. D3 (Data Driven Documents)
  4. SVG (Scalable Vector Graphics)

Create the Hello World extension

Follow these steps to create and test your Hello World extension inside the vizPacker:

  1. Using Google Chrome
    Open: <installdir>\SAP Lumira\Desktop\utilities\vizPacker\vizPacker.html
  2. If the welcome screen is displayed you can optionally take the introductory tour.
    When you have finished the tour close the welcome screen.

    Welcome screen.png

  3. The LAYOUT DESIGN tab is where you define the ID, Name and Layout of your extension as well as edit the code
  4. Using the LAYOUT DESIGN tab, turn off the Title and Legend as we do not need them for the hello world extension
    • Click the X to the right of the Title
    • Click the X at the top of Legend
      Layout - Remove title and legend.png
  5. Using the LAYOUT DESIGN tab, set the ID and Name for your extension:
    • Click the outer gray box to display the chart visualization properties:
      Layout - Show Viz properties.png
    • About IDs:
      • The ID naming convention is similar to making unique Java class names
      • You use the reverse of your company web address and then add the name of the extension
        For example: com.sap.sample.helloworld
      • IMPORTANT note:
        • The ID must be all lowercase otherwise it will not work inside SAP Lumira
    • Settings:
      • ID:       sap.viz.ext.helloworld
      • Name: Hello World
    • Note: As you close the properties window or move between fields the vizPacker updates the ID and Name used in the code editor
  6. Using the LAYOUT DESIGN tab, set the ID and Name of the extension plot area:
    • Click the inner plot area gray box to display the chart plot area properties:
      Layout - Show Viz plot properties.png
    • About IDs:
      • Follow the same rules as for the extension ID, but append module to the end
    • Settings:
      • ID:       sap.viz.ext.helloworldmodule
      • Name: Hello World Module
    • Note: As you close the properties window or move between fields the vizPacker updates the ID and Name used in the code editor
  7. Using the LAYOUT DESIGN tab, find the render function and remove the sample code:
    • Scroll to the top of the code editor and find the render function
    • Delete all the code between these two comments:

      // START: sample render code for a column chart

      // END: sample render code

    • Then delete the two comments as well
    • The render function should now look like this:

      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);
      };

    • This render function passes in an SVG container along with its width and height.
    • The extra code then creates an SVG tag and a g tab inside the container and assigns them to the variable vis.
  8. Using the LAYOUT DESIGN tab, edit the render function to say Hello World!:
    • Note: vis is the name of the SVG tag that we can append the hello world text to
    • Use this code in the render function to (1 – append a text element into vis, 2 – set the text to Hello World!, 3 – set the y position to 20 pixels, 4 – set the CSS font size to large):

      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(“font-size”,”large”);
      };

  9. Validate your code inside the vizPacker:
    • Click on Run Code:
      Run code.png
      • If you see this message then your code has been validated without errors.

        Run code change applied.png

      • Otherwise, if you get a JavaScript error message then there is something wrong with your code:
        • Close the JavaScript error message
        • Right-click on code editor and select Inspect Element to enable the Google Chrome developer area
        • Then go to the Console tab and look at the error messages
        • Fix your code in the vizPacker code editor and then click Run Code again
  10. Once your code is validated, preview your extension inside the vizPacker:
    • Click to turn on preview mode:

      Preview mode.png

    • The preview window will appear inside the code editor and you should see your Hello World text:

      hello world in vizPacker.png

  11. Next you are ready to pack (package) and test inside SAP Lumira

Pack (package) and install your extension into SAP Lumira

  1. Click Pack
    /wp-content/uploads/2013/12/pack_346859.png
  2. The extension will be packed into a ZIP file. Click the ZIP file link:

    Packed.png

  3. Google Chrome will download the packed ZIP file.
  4. Select the downloaded ZIP file and select Show in folder

    Download.png

  5. Extract out the the packed extension and install it into SAP Lumira:
    • Extract out all the files and folders from the ZIP file
    • The bundles folder has sub-folders inside it, the sub-folder names are based on the extension ID, which is why the ID is so important as that stops your extension files from clashing with files from somebody else.
      • So sap.viz.ext.helloworld becomes zip/viz/ext/helloworld within the ZIP file.
    • Copy the bundles/sap folder to <installdir>\SAP Lumira\Desktop\extensions\bundles
      For example: <installdir>\SAP Lumira\Desktop\extensions\bundles\sap
    • If you already have an sap folder within bundles you will be asked to merge the folder. That is Okay because the sub-folders will make sure our files do not clash with those from somebody else in the sub-folders.
  6. Next we can test the extension inside SAP Lumira

Test your Hello World extension inside SAP Lumira

  1. Start SAP Lumira
  2. Go to Home > Try with Samples > BestRunCorp – Margin Analysis

    Note: It doesn’t matter which data set we use with Hello World because we only ever display the text Hello World!

    Try with Samples.png

  3. Click + to add a new visualization:

    New visualization.png

  4. Select the Hello World extension:

    Select Hello World extension.png

    Note: If you do not see the extra extension menu or Hello World is not listed inside it, go back and check that your extension and plot area IDs to make sure they are only using lowercase letters

  5. In SAP Lumira the render function for an extension is only called once you have passed some data to it
  6. So select Quantity sold as the Y Axis measure and Lines as the X Axis dimension
  7. You should now see Hello World! displayed inside SAP Lumira

    Say Hello World.png

    Note: If this does not work, you will need to refer to the SAP Lumira SDK Getting Started Guide on how to debug within SAP Lumira

  8. That’s it, you have created, packaged and tested your first extension using the vizPacker!
  9. Congratulations and happy coding…

More information

Have a look at the:

Resources

You can find all of the Hello World files on GitHub.

To report this post you need to login first.

21 Comments

You must be Logged on to comment or reply to a post.

  1. Christina Obry

    Thanks Matt, great functionality and write up!

    I like to point out that at this point publication of stories, that contain custom charts, to SAP Lumira Cloud is not supported. These charts will not load on Lumira cloud. We are investigating a solution for this, please stay tuned.

    (0) 
    1. Alper Derici

      Hi Budi,

      Unfortunately, upgrading Lumira deletes your existing extensions from the folder, and the icon will not show up when theres no extension installed.

      By the way, the extension structure changed in 1.0.14, so you will have to tweak your files and code to make it work with the new version.

      (0) 
  2. Irshaad Bijan Adatia

    Hey Matt,

    Thanks for sharing this with us!! It’s intriguing to be able to work with all of this~~

    I caught it on Twitter, as it wasn’t posted in the Lumira community, but I’m glad that I did!!

    Just in case anyone needs a really great intro to D3, there’s a great tutorial that even people with little to no coding background can follow HERE.

    Any more tutorials planned? Would love to see what kind of chart types you have in mind for a custom visualization!! 🙂

    Bijan

    (0) 
  3. Hari Srinivasa Reddy

    Hi,

    Can someone please give sample code to create table and fill the values in d3.

    When I use table , td and tr tages it does not work in vizPacker. I can’t see anthing?

    Your help will be appreciated.

    (0) 
    1. Matt Lloyd Post author

      Hi Hari,

      Before Lumira 1.17 you could only use SVG for extensions (because the “vis” container is SVG). In 1.17 you can now choose DIV as the container instead, so then you can choose to use SVG or HTML in your extension, so in 1.17 make sure in Viz Packer to select DIV for the container.

      (0) 
  4. Matt Lloyd Post author

    I updated this for SAP Lumira 1.20 as there were improvements made for creating SAP Lumira  extensions since this was first written.

    (0) 
  5. Zion Chen

    Hi,

    I want to know if it’s possible that integrate Lumira with my web page, such as add a analytic function to in my web page using Lumira

    (0) 
    1. Matt Lloyd Post author

      Hi Zion,

      You can embed a Lumira story in your page, that is what we do with the examples on saplumira.com

      Regards

      Matt

      (0) 
  6. Klaus Reiner

    Hi Matt,

    if I have an already existing solution, like a zip file (e.g. your hello world solution), how to Import it to the VizPacker. Especially in case of minor adjustments.

    I am able to Import files, but only Project files, not *.zip-files. Any idea?

    Kind regards,

    Klaus

    (0) 
    1. Matt Lloyd Post author

      Hi Klaus,

      I’d recommend switching to VizPacker for Web IDE instead (see the top of this blog).

      The local (older) VizPacker cannot import a ZIP file, only the .profile project (as you mentioned).

      What you can do is manually extract the ZIP file, find the render.js and CSS files and copy out the code that you want to keep – you could then paste that code into a new local (older) VizPacker project or a new VizPacker with Web IDE project (recommended).

      Regards

      Matt

      (0) 
  7. Klaus Reiner

    Hi Matt,

    now I understand what you meant. Thanks!

    btw: I expected Exlipse to be the new development Environment for all

    new SAP Tools. Why is the VizPacker for Web IDE not included there

    and needs to be installed separatelly?

    Or is this planned in later Releases?

    Kind regards,

    Klaus

    (0) 
    1. Matt Lloyd Post author

      Hi Klaus,

      SAP Web IDE is a cloud-based IDE which is why it is not part of Eclipse.

      Eclipse could make sense if you are building a full app, but as an extension is a smaller JavaScript component, creating a plug-in for Eclipse would have been a lot more intensive so the VizPacker team opted to support Web IDE.

      Regards

      Matt

      (0) 

Leave a Reply