Tweak Existing Lumira Viz Extensions - Episode 7: Adding Images

Greetings, folks! We are now on episode 7 of our mini blog series on tweaking existing Lumira visualization extensions to suit your needs. This episode is to add the finishing touches to the other tweaking tricks to extensions that I described in the previous blogs. In other words, we have hit our season finalé of this mini blog series. But it's not over! Please feel free to submit new ideas and suggestions in the comments section, for future blogs on what you'd like to modify for yourself, on an existing Lumira visualization. Once we get a couple of ideas or suggestions, we will begin season 2 of our series. How exciting!

Let's move on to our season finalé: add images to your extensions! For this example, we will use the same bubble chart we have been using in Episode 5 and 6.

As a reference, you can also refer to the existing extension with custom images: The Country Visas Chart with Tooltip and Image

The process of achieving our goal, i.e. to append images to the data points in our chart, is very simple. It is literally one statement of JavaScript code. Like, seriously!

Step 1: Append images

We first select our bubble elements (data points) and append image elements to them.

     bubbles.append("image")

We don't end the statement yet, so no semicolon there. We still have to assign various other attributes to it. But don't forget your semicolon at the end of it all!

Step 2: Require images via image URL

Now let us add our first and most important attribute that requires/acquires our images. Before we do that, we want to make sure that our images are in the project file. Let us start by creating an "Images" folder in the main project directory. This folder needs to be in the same space as the project bundle.js file.

Now that we have this folder in this space, we start importing images one by one by Right Click on Image folder --> Import --> From File System

After importing all the images, we can proceed to adding our code snippet after what we've written in Step 1.

    .attr("xlink:href", function(d) {

          var imgUrl = require.toUrl("Images/" + d[dim] + ".png");

          return imgUrl;

     })

In the require.toUrl reference, we have "Images/" which is the directory path of the image folder. Here we call it so because the name of the folder we create earlier is called Images. If the folder name were secrets, we would have "secrets/".

d[dim] is the name of the dimension or data point that we want to get from our dataset. This is how your data links to the images.

".png" is the image file extension we are using.

What we want to do here is basically, get the URL for each image, so for that we use this function to acquire those URLs for each image/data point so that each image corresponds to the relevant data point in the dataset. The idea of this require URL is to get something that looks like

Image-folder-path/data-point-name.png which we break down as "Images/" + d[dim] + ".png"

*****Please NOTE: Important points to keep in mind when dealing with images:

1. Make sure there are no white spaces in your image names.
2. The name of each image must correspond to, and be the same as each data point (dimension) in your dataset. Any conflict will cause images to not load.
3. JavaScript is case sensitive. Make sure that image names, data point names and image file extension names are accurate down to the letter case.
4. Image file extensions must be uniform. Make sure all your images are all of the same type and letter case. .PNG and .png are not the same! Neither are .png and .jpg. The extension that you use will be what you enter here:
   
   For example, if you use .JPEG, you will have ("Images/" + d[dim] + ".JPEG");
   
   
5. Your image URL depends on where you place your images folder. If you have it parallel to your project bundle.js file, you can call it as we have above. If you have it somewhere else, let's say in the resources folder, your images will be in sap_viz_ext_bubblechart-src/resources/Images/ and you will have to change the require URL accordingly.

     In this case, we can then have

   var imgUrl = require.toUrl("sap_viz_ext_bubblechart-src/resources/Images/" + d[dim] + ".png");

Step 3: Positioning and size

Now that we've loaded our images into our project, we just have to determine where to place them on our chart. Since we have a bubble chart, let's say we want the images to be inside the bubbles. For better readability, we have rounded images. We need to determine the X and Y positions of each image, and also the width and height. Even though our images are rounded, we cannot possibly define an image with a radius! Add the following attributes to our code:

    .attr("x", function(d) {

          return x(d[measure1]);

     })

     .attr("y", function(d) {

          return y(d[measure2]);

     })

     .attr("width", function(d) {

          return d[measure3] / 2;

     })

     .attr("height", function(d) {

          return d[measure3] / 2;

     });      

We define the width and height of our images to be half of that of the bubbles, just so we can see both the images as well as the bubbles. d[measure3] represents the diameter of the bubbles, which is why we divide it by 2 to get half of that to be the width and height of the images.

We get the appropriate size for each image. However, our positioning doesn't quite look right yet. They all seem to be off by about a half of the width of the images.

Now if the width of the images is  d[measure3] / 2, half of that will be d[measure3] / 4. This is what we need to subtract from the X and Y positions respectively. Subtracting, because we need to descrease the X and Y distances from the respective axes. We have our modified code snippet:

      .attr("x", function(d) {

          return x(d[measure1]) - (d[measure3] / 4);

     })

     .attr("y", function(d) {

          return y(d[measure2]) - (d[measure3] / 4);

     })

Finally, we have:

Know that this is absolutely possible for any kind of chart! Go ahead and try it out!

And with this, we come to end of our season finale of our mini blog series: Tweak Existing Lumira Viz Extensions to cater to your needs!

As I mentioned earlier, please feel free to comment and suggest new blog ideas to tweak Lumira extensions and change/add different properties.

Thank you all again for being part of this series of mini blogs!

Looking forward to season 2 !!