Design Studio SDK (Community Package): Custom Map (non-geographical)

[Former Member]

Introduction

Hello,

I would like to share with you a new component developed in the SDK Community Package.

It allows you to use an image and create interactive areas on it in Design studio. You can fully customize it, link it to datasource data and show tooltips.

Use cases:

• Display repartition of faulty parts / returns on a car
• Show best selling area of a store
• ...

You can download a test app created with DS 1.6 SP2 P1. If you want to open it with an older version, you'll have to edit xml and .properties file.

I hope this component will be useful for you, and don't hesitate to ask questions in the comment section !

PS: Please raise issues or requests for improvements on the dedicated GitHub section instead of SCN comments.

Component overview and explanations

I created this component because of the lack of really custom map related to non-geographic data, and wanted to streamline the process making those.

The component is based on the Mapster JQuery library and should be well supported on mobile devices.

Here's an example with store areas are coloured depending on the net amounts:

Included features:

• Choose any image as background for the map, either linked with an url or a base64 encoding

• Areas are defined with HTML standard maps areas. Lots of online editing tools are available to create them (I recommend Image Map Tool - On-line Image Map Creator - HTML & CSS | Image-Maps.com)
• Support resizing
• Define base, selected and highlighted areas properties like:
  • Background color and opacity
  • Stroke width opacity and color
• Single, multiple selections with corresponding BIAL events
• Customizable tooltips, either per area, generated and linked to data
• Data binding:
  • Map the ID of the areas to your data
  • Define dynamic range of colors associated to a key figure
  • Dynamic updated when datasource is changed

Events

On Click

The selection of one or more areas triggers this event in Design studio, and you can get the selected areas using the method .getSelectedAreas(), which gives you a string in CSV format: A1,A2,A3 ...

You can directly pass this parameter to the .setFilter() method on another datasource if you split the table on the comma.

OnMouseOverOut

This event is triggers whenever the user hovers an area with its mouse and you can get the area code by using the method .getHighlightedArea().

OnUpdate

When the component gets updated, this event is triggered.

Properties

Data binding

It not mandatory to bind data, but you have the option to do so. The Dynamic colors can be used in this case.

Just select a datasource, avoid to filter the data list on measure if possible.

You should select which measure should be used in "Reference Measure Selection" if you want to associate the areas with the dynamic colors. The first one is used by default.

Display*

Those are mandatory.

• Image: you can either encode your image in base 64 or use an url (for instance to one on the BI platform)
• Map Key Attribute: You need to specify which attribute is the key on the areas. By default, ID is use, but it can be any of the attributes, either custom or standard. Selected areas will be identified by this attribute value
• Associated map: This is where areas gets defined, and I'll explain all about it just below

You could generate this code directly in the application instead of having to create them manually if you have them stored somewhere, in a datasource or a css/text file on the BI platform.

Associated map

It's quite easy to define the areas, you just need to take your image to Image Map Tool - On-line Image Map Creator - HTML & CSS | Image-Maps.com and start mapping !

First, upload the image on the website and start mapping by right clicking on the image. You can create either Rectangles, circles or Polygones (any shape).

In the options, you just need to associate an ID. Other settings are more than optionals, and clic Save

You can create as many areas you want on the image. Don't bother on the style, it will be handled by the component at the runtime.re

The last steps are:

1 - Get the code

Open the HTML code tab and go down to HTML Image Map Code

2 - Copy paste and clean it:

• Keep only "areas" tags
• Remove the "Image Map" default area (before the last area)
• Remove attribute style and target

Now you can take this html code and paste it in the "Associated Map" property in the component.

You should now see the areas on the image in Design studio !

Areas Properties

Several sub tabs enables to customize even further the areas.

Global

This is where you set the different display properties for all the areas. Note the fill color could be overwritten by the dynamic colors if activated.

Selected and Highlighted

Both pane features the same properties.

Selected is applied to all the selected areas whereas Highlighted is for hovered areas.

Those properties are used only if you checked "Activate Special properties" checkbox.

Specific

You can also define specific properties for each areas

The key needs to match the one from the "Map key" attribute of the areas. If a property is empty, it will not be used.

The tooltip content can be either static HTML code, or a template with the JS Render format. You'll need to chose "Evaluate as Template" to get it rendered correctly.

Behaviour

This tab is used to set up the behaviour of the map

• If auto resize is unchecked, the source size of the image will be used and scrollbars will be displayed automatically. You can use that to simulate a zoom for instance
• Hovering areas can also triggers BIAL script if you want. You'll need to check this property if you want it.

Dynamic colors

This feature is only use in combination with data binding. When you have selected a key figure, the component will use the minimum and maximum value of it to change the color of each area (Quantile method) according to the selected color palette.

Some palettes are proposed in the Options button.

The first color is for the minimum, and the last for the maximum.

Tooltips

In this tab, you can choose to display the tooltips, but not only. You can also consider the specific tooltip (see Area properties -> Specific -> tooltip) as a template, or override it with a custom template.

Templates are rendered using JsRender and you can access a lot of information from your datasource, as well create calculations and implement logics; If, For etc are supported, which makes it very powerful.

Each field can be rendered using this syntax: {{:name}}.

The data fields accessibles are matching the pattern detailed below:

• Dimensions:
  • {{:DIM_<TECHNICAL NAME OF THE DIMENSION>_<FIELD_TYPE>}}
  • Only the first dimension is accessible like that, Other dimension after the first need to accessed through the lines
  • Example: {{:DIM_0MATERIAL_KEY}}
• Measures:
  • {{:MES_<TECHNICAL NAME OF THE MEASURE>_<FORMAT>}}
  • <FORMAT> can be either:
    • RAW: Real value, useful to calculate stuff
    • FORMATED: Value formatted according to the datasource
    • UNIT: Unit of the measure, can be either a unit or a currency, extracted from the Formated value
  • Example:  {{:MES_BILLED_QTY_RAW}}
• Overall Results
  • You can access the total of your main characteristic if activated in the datasource (initial view)
  • The field total has the information, where you can access both dimensions and measures according to the format explain before.
  • Example:  {{:total.MES_BILLED_QTY_RAW}}
• Attributes (Array):
  • {{:<DIM_TECHNICAL NAME OF THE DIMENSION>_<FIELD_TYPE>}}
  • All attributes of the first dimension can be accessed from the "attributes" property
  • You can loop on them with {{for attributes}} or directly access it by attributes.nameoftheattribute (see before)
  • Unfortunately, they're not supported on CSV datasource, but work perfectly fine with Bex Queries.
  • Example:  {{:DIM_0VENDOR_KEY}}
• Lines (Array):
  • If you have 2 or more dimensions, the data for all of them after the first will be stored "lines", and you can use {{for lines}} instruction to loop on them.
  • Result lines can be identified with the key "RESULT".
  • Dimensions and measures can be read with the same format as previously mentioned

<FIELD_TYPE> can be either:

• INTERNAL_KEY (Not available for attributes)
• KEY
• TEXT

Here's an exemple of the data accessible in the tooltip template:

And an exemple of dynamic rendering using the JS render Tooltip template, with some local calculation:

Tooltip code

Header 3

{{* vCatPC = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW / data.total.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW * 100; }} <h3>Category:{{:DIM_0D_NW_PRCAT_KEY}} ({{*: vCatPC.toFixed(2);}}%)</h3> {{* vTotal = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW; }} <table class="tableContentTooltip"> {{for lines}} <tr class="tpContHead"><td colspan="2"><strong> {{if DIM_0D_NW_PRID_INTERNAL_KEY == 'RESULT'}}   TOTAL   {{else}} {{:DIM_0D_NW_PRID_TEXT}}   {{/if}}</strong></td></tr> <tr> <td>{{:MES_A83Y2FPNS2H7DCEHG43W741JM_FORMATED}}</td> <td>{{* curPC = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW / vTotal * 100; }} {{*: curPC.toFixed(2);}}%   </td> </tr> {{/for}} </table>

For instance, I am able to calculate the % of contribution of each category with:

{{* vCatPC = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW / data.total.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW * 100; }}

{{*: vCatPC.toFixed(2);}}%

Those tags is interpreted as raw javascript and I can calculate and determine nearly everything using the data as hand, my current net amount and the total net amount.

Same applies for the list of material:

First, I store the total of the category in a javascript variable vTotal:

     {{* vTotal = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW; }}

Secondly, I generate a table and loop on each material:

     <table class="tableContentTooltip">

     {{for lines}}

And for each, I calculate the % of contribution and round it to 2 decimals:

     {{* curPC = data.MES_A83Y2FPNS2H7DCEHG43W741JM_RAW / vTotal * 100; }}

     {{*: curPC.toFixed(2);}}%