Adding an existing D3 Visualization

 Edit 0 1…

Using an Existing D3 Visualization

You can use the Visualization Builder tool to customize an existing D3 visualization and integrate it with MicroStrategy.

In this example, we describe how to customize a D3 Waterfall Chart, a publicly available visualization created by RSloan. You can get the code for this visualization from the public website, http://bl.ocks.org/rsloan/7123450, but to make the process as simple as possible, we have provided a zip file with the CSS, javascript and data files that are used by this visualization.

Once you have walked through the process of customizing the D3 Waterfall Chart, you can extrapolate from the instructions in this topic to customize other D3 visualizations.

1. Install the Visualization Builder tool, if you have not already done so.
   
2. Download the zip file that holds the CSS, javascript and data files used by the D3 Waterfall Chart visualization. Unzip the contents and save the following files in a location where they are easily accessible.
   
   
   • WaterfallChartJS.js
     
   • WaterfallCSS.css
     
   • data.csv
     
3. Open MicroStrategy Web. In this example, use a Google Chrome browser because the instructions include ways to use Google Chrome Developer Tools to help understand and debug your visualization.
   
4. Click the Visualization Builder link on the navigation pane to open the Visualization Builder tool.
   
   
   
5. Click the Configuration tab.
   
   
   
   
   
   
   1. For Visualization name, enter a descriptive name for the custom visualization you are building.
      
      
      
   2. Configure the required external libraries. You can get these from the D3 visualization code. One at a time, enter the URL for each library that you want to add in the text box at the bottom of the panel and click Add Library. In this example, you add the following D3 libraries:
      
      http://code.jquery.com/jquery-latest.js
      http://d3js.org/d3.v3.min.js
      
      
      
   3. Click Apply.
      
6. From the File menu, choose Save As.
   
   
   1. For Folder name, enter the name of the plug-in folder for your custom visualization. This is generally the same name as the visualization.
      
      
      
   2. Click OK. The plug-in folder for the custom visualization you created is saved under your plugins folder.
      
      
      
7. Click OK.
   
8. Close the Visualization Builder, and then re-open it.
   
9. From the File menu, click Open. Select your custom visualization.
   
   
   
   
   1. The Code Editor tab should be open. Copy the code for the D3 visualization you are using. Paste the CSS for the style and the javascript code into the Code Editor tab. In this example, you copy and paste the contents of WaterfallCSS.css under Style , and you copy and paste the contents of WaterfallChartJS.js under Plot Code. Don't be concerned about the warnings.
      
      Note: While you are working on your visualization, the size and placement of the Style and Code sections on the Code Editor tab may vary, depending on factors such as whether Developer Tools are open, if you expanded a section, etc. In some cases, there is a large space between the Style and Code sections and you need to scroll down to see the code.
      
      
      
   2. In the javascript code, find the D3 statement that adds the visualization to the body of the page. This is usually d3.select("body"). Replace it with d3.select(this.domNode).
      
      In this example, you change:
      var svg = d3.select("body").append("svg")
      
      to:
      var svg = d3.select(this.domNode).append("svg")
      
   3. Open the Google Chrome Developer Tools and disable caches by selecting Disable cache on the Network tab.
      
      
      
   4. Click Apply in Visualization Builder.
      
   5. In the Google Chrome Developer Tools Console, an error will be displayed, saying that a resource was not found.
      
      
      
      This error is displayed in the Console because the code you pasted uses a data.csv file to load the data, and that file does not exist.
      
      
      
   6. Most D3 sample visualizations have an example of the data that is being used. In this case, the following data has been provided by the author.
      
      
      
      
      
   7. To have a better understanding of this visualization, add the data.csv file to the same folder in your plug-in where the javascript files are located—for example, ../plugins/MyCustomD3WaterfallChart/javascript/mojo/js/source/data.csv.
      
      
   8. After you add the data.csv file to the folder mentioned above, click Apply in the Visualization Builder again. The visualization should now display in the right panel.
      
      
      
      
      
   9. You can use debugger to pause the execution of your code and inspect what is being done. This is a useful way to understand how the visualization gets and manipulates the data. Add debugger; after the data from data.csv has been retrieved.
      
      
      
   10. Click Apply again. Notice that debugger stops the code execution.
       
       
       
   11. On the Console tab, type "data" and press Enter. Expand each of the data objects on the console to see additional details about the data parameters that are being passed to the csv method.
       
       
       
       
       
       This is a useful way to understand the format of the data. When data is retrieved from MicroStrategy using the API, the format might or might not be the same as the format expected by your visualization. Understanding this helps you to determine if you need to further manipulate the data in order for the visualization to work as expected with data coming from MicroStrategy.
       
       
       Remove debugger: from the code and save the file.
       
       
   12. Now you need to add your MicroStrategy data to your custom D3 visualization. You must do this before you add debugging code; otherwise, the code is deleted.
       
       
       1. To add data to the visualization in this example, you use an existing dataset in the MicroStrategy Tutorial project. You choose Select Existing Dataset, navigate to Shared Reports -> Subject Areas -> Customer Analysis -> Customers Summary, and click Select. If you are using an external dataset, you would choose Add External Data and import the data you are using.
          
          
          
       2. Open the Editor tab.
          
          
          
       3. Drag the attributes and metrics you want to use for your visualization onto the Editor tab. In this example, you use:
          
          
          • Attribute: Month
            
          • Metrics: Customer Count, Customer Count Forecast, Last Month’s Customer Count
            
          
   13. Now, you must replace the statement that pulls the sample data for the D3 visualization with a statement that pulls the data from MicroStrategy. In this example, the D3 visualization expects tabular data.
       
       Usually there are two types of data:
       
       
       • Tabular data
         
         
         • Typically represented by d3.csv("filename.csv",function(error,csv)){}
           
         • Since the visualization in this example expects tabular data, open the Code Editor and add:
           var csv = this.dataInterface.getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.ROWS_ADV);
           before:
           d3.csv("data.csv",function(error,csv)){}
           
       • Tree data
         
         
         • Typically represented by d3.json("filename.json",function(error,json)){}
           
         • If a visualization expects tree data, you would use::
           var json = this.dataInterface.getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.TREE);
       Note: In some cases, it is not simple to replace the csv method with the MicroStrategy API. For these cases, make sure that the data variable has the MicroStrategy data and not the data being retrieved from the CSV file.
   14. Add debugger under var csv = this.dataInterface.getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.ROWS_ADV);and click Apply again.
       
       Note: You must have added a dataset before adding the debugger code described above. If you add the debugger code first and then add a dataset, the code is deleted.
       
       
       
   15. You can use the Console to find the format of the data that is being retrieved from MicroStrategy as follows:
       
       
       When you clicked Apply, the execution is stopped by debugger after the data was retrieved from MicroStrategy:
       
       
       
       
       
       On the Console tab, type "csv", and then press Enter. The MicroStrategy data objects are displayed.
       
       
       In this example, you will see that the data being retrieved from MicroStrategy has a different format from the data being used by the author of this visualization:
       
       
       Format of MicroStrategy data:
       
       
       
       
       
       Format of visualization (D3 Waterall Chart) data:
       
       
       
       
       
       The main difference is that the MicroStrategy data has an object with the metric value. The visualization data does not have an object for the metric.
       
       
       Remove debugger: from the code and save the file.
       
       
   16. You need to add additional logic to modify the MicroStrategy data so that it looks more like the data expected by the visualization. In this example, you add the following code after the line of code that pulls the MicroStrategy data:
       
       var gridData = this.dataInterface;
       var rowHeaders = gridData.getRowHeaders();
       var attributeName = rowHeaders.titles[0].n;
       for (var i = 0; i < csv.length; i++) {
       for (var key in csv[i]) {
       if (key !== attributeName) {
       csv[i][key] = csv[i][key]["rv"] + "";
       }
       }
       }
       
       If the object key does not match the attribute name, then you set that property to be the value of the metric. Note that the value of the metric in this visualization data is a string. That is why an empty string is being added to the value: csv[i][key] = csv[i][key]["rv"] + "";

1. After you add the code with the additional logic, add debugger; after the new block of code to check how the data looks now.
   
   
   
   Click Apply. When the execution stops, open the Console, and type "csv". The csv variables now look more like the data coming from data.csv.
   
   
   
   Remove debugger: from the code and save the file.
   
2. Now that the format of the data matches, you can replace the content of the data variable with the MicroStrategy data. After the code that gets the data, add data = csv;.
   
   
   
   
   
   Now data refers to the variable you added earlier to pull MicroStrategy data:
   
   var csv = this.dataInterface.getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.ROWS_ADV);
   
   
   To confirm that the correct data is being retrieved, add debugger; after data=csv;and click Apply. When the processing stops, open the Console and type "data". The data should look like MicroStrategy data.
   
   
   
   
   Remove debugger; and save your file. Stop and start the Visualization Builder.
   
   
3. Many of the visualizations available on the Internet are created exclusively for the data the author references. In this example, the author uses the attribute called “period”, which is hard-coded in three places in the JavaScript code. You must replace all instances of the string "period" with the name of your attribute variable, attributeName.
   In the additional code you added, you get the attribute, called attributeName, by using:
   
   
   var gridData = this.dataInterface;
   var rowHeaders = gridData.getRowHeaders();
   var attributeName = rowHeaders.titles[0].n;
   
   In this example, you are using the attribute name. If you wanted to get the metric name, you would use the following line of code:
   
   
   var gridData = this.dataInterface;
   var metricName = gridData.getColHeaders(0).getHeader(0).getName();
   
   Note: Make sure to use the correct syntax. If you are trying to access the property of an object, you have to use square brackets so that the expression is evaluated first and then the value is gotten. For example, this doesn’t work:
   
   
   data[0].attributeName
   
   but this will return “2010”.
   
   
   data[0][attributeName]
   
   Make the following replacements:
   
   
   Replace
   return key !== "period";
   with
   return key !== attributeName;
   Replace:
   x0.domain(data.map(function(d) { return d.period; }));
   with
   x0.domain(data.map(function(d) { return d[attributeName]; }));
   
   Replace:
   return "translate(" + x0(d.period) + ",0)";
   with
   return "translate(" + x0(d[attributeName]) + ",0)";
4. Finally, modify the width and height of the visualization so that the screen adjusts correctly. Typically, the width and height of visualizations are defined as fixed values. These must be replaced so that the sizes reflect the available space in MicroStrategy. For example:
   
   
   var margin = {top: 10, right: 10, bottom: 10, left: 10},
   width = parseInt(this.width,10) - margin.left - margin.right,
   height = parseInt(this.height,10) - margin.top - margin.bottom;
5. Save your visualization and click Apply again. The Waterfall Chart should be displayed with your MicroStrategy data.