How to Deploy Custom Visualizations Using D3 on MSTR 10 Version 1.0 Presented by: Felipe Vilela
Table of Contents How to deploy Custom Visualizations using D3 on MSTR 10... 1 Version 1.0... 1 Table of Contents... 2 Deploying methods... 3 Deploying using MicroStrategy s preconfigured visualizations... 3 Configuring a custom visualization to be used in MicroStrategy... 7 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 2 of 18
Deploying Methods There are two main methods that can be used for deploying a custom visualization in MicroStrategy. The first one is downloading the visualizations that MicroStrategy already configured and the second is to choose one visualization from the D3 website and configure it. Deploying Using MicroStrategy s Preconfigured Visualizations MicroStrategy has a repository that contains many custom visualizations that are ready to be used. The URL to see and download those custom visualizations is: https://community.microstrategy.com/t5/custom-visualization-gallery/bg-p/vizgallery Let s use the Animated Gauge as an example to demonstrate how to deploy a custom visualization in MicroStrategy Enterprise version. To do that, you just have to: 1. Click on the visualization that you want to use in MicroStrategy; 2. Look for the ZIP file on the page; 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 3 of 18
3. Download the ZIP file and extract its content inside the plugins folder of your MicroStrategy Web environment. If you are using IIS (Internet Information Service) it might be in this directory: c:\program Files (x86)\microstrategy\web ASPx\plugins If you are using Tomcat it might be in this directory: c:\program Files (x86)\apache Software Foundation\Tomcat 7.0\webapps\MicroStrategy 4. Restart your Web server; 5. Now, let s create create a dashboard. The first step is to open a browser and login to the Web Server; 6. In this case, we are going to use the MicroStrategy Tutorial project, but you have to choose the project that you want to create the dashboard; 7. Click on the Create button; 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 4 of 18
8. Select Enter Dashboard ; 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 5 of 18
9. Then, you will see the custom visualization in the Visualization Gallery; 10. Click on the Add Existing Dataset and select a dataset to be used for the chart; 11. Click on the new chart and add 1 attribute and 1 metric. You should see something like this: 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 6 of 18
Configuring A Custom Visualization to be Used in MicroStrategy Sometimes, you won t find the right visualization in Microstrategy s repository, so the only way is to configure a new custom visualization to use in the dashboards. The steps to configure a new custom visualization are explained below: 1. Go to the D3 repository and choose one visualization: https://github.com/mbostock/d3/wiki/gallery For this example, we are going to use this visualization as an example: http://bl.ocks.org/mbostock/3885304 There are 3 different types of charts. Each one uses a different method to input data. Below are the types of input format: - CSV - JSON - Code (Javascript) When you choose a chart, you will have to see the type of input that it is using. If the chart uses code to display the data, it will be harder to implement in MicroStrategy because it s necessary to change the code to use a file instead. MicroStrategy only supports visualizations that use a file as input for the data. 2. To implement that visualization, you will have to create a folder inside the plugins folder of our Web Server. In this case: C:\Program Files (x86)\apache Software Foundation\Tomcat 8.0\webapps\MicroStrategy\plugins Let s name it as ExampleChart. 3. Now let s create the structure for our plugin. Create 3 folders inside ExampleChart and name them as: 4. Now create these folders inside the javascript folder: mojo\js\source 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 7 of 18
5. Open any text editor and paste this code below: (function() { if (!mstrmojo.plugins.examplechart) { mstrmojo.plugins.examplechart = {; mstrmojo.requirescls("mstrmojo.customvisbase"); mstrmojo.plugins.examplechart.examplechart = mstrmojo.declare( mstrmojo.customvisbase, null, { scriptclass: 'mstrmojo.plugins.examplechart.examplechart', cssclass: "ExampleChart", errordetails: "This visualization requires one or more attributes and one metric.", userichtooltip: true, reusedomnode: true, externallibraries: [{ url: "http://d3js.org/d3.v3.min.js" ], plot: function() { if (this.domnode.childnodes.length === 1) { this.domnode.removechild(this.domnode.childnodes[0]); // JS CODE Here... ); )(); 6. Save this file as ExampleChart.js into..\microstrategy\plugins\examplechart\javascript\mojo\js\source Note that we have ExampleChart in several parts. That is the name of our plugin. If you are creating a plugin with the name of Chart123, you just must replace all ExampleChart to Chart123. 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 8 of 18
7. There is a place in the code above that says // JS CODE Here, we will have to copy the JavaScript from the visualization and paste inside this area. 8. Let s go back to our D3 chart page. You have to copy the content inside the <script> tag (do not insert the <script> nor </script> tags) of the visualization that we chose inside that area. In this case, this code: 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 9 of 18
The ExampleChart.js file will be like this (script will continue. on page 11 and 12): (function() { if (!mstrmojo.plugins.examplechart) { mstrmojo.plugins.examplechart = {; mstrmojo.requirescls("mstrmojo.customvisbase"); // Declare the visualization object mstrmojo.plugins.examplechart.examplechart = mstrmojo.declare( // Declare that this code extends CustomVisBase mstrmojo.customvisbase, null, { scriptclass: 'mstrmojo.plugins.examplechart.examplechart', cssclass: "ExampleChart", errordetails: "Error message", userichtooltip: true, reusedomnode: true, externallibraries: [{ url: "http://d3js.org/d3.v3.min.js" ], plot: function() { if (this.domnode.childnodes.length === 1) { this.domnode.removechild(this.domnode.childnodes[0]); // JS CODE Here 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 10 of 18
var margin = { top: 10, right: 30, bottom: 50, left: 80, width = parseint(this.width, 10) - margin.left - margin.right, height = parseint(this.height, 10) - margin.top - margin.bottom; var chart = d3.select(this.domnode).append("svg").attr("width", width + margin.left + margin.right).attr("height", height + margin.top + margin.bottom).append("g").attr("transform", "translate(" + margin.left + "," + margin.top + ")"); var x = d3.scale.ordinal().rangeroundbands([0, width], 0.1); var data = this.datainterface.getrawdata(mstrmojo.models.template.datainterface.enu M_RAW_DATA_FORMAT.TREE).children; var metricname = this.datainterface.getcolheaders(0).getheader(0).getname(); x.domain(data.map(function(d) { return d.name; )); var y = d3.scale.linear().range([height, 0]).domain([0, d3.max(data, function(d) { return d.value; )]); var xaxis = d3.svg.axis().scale(x).orient("bottom"); var yaxis = d3.svg.axis().scale(y).orient("left"); chart.append("g").attr("class", "x axis").attr("transform", "translate(0," + height + ")").call(xaxis); chart.append("g").attr("class", "y axis") 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 11 of 18
.call(yaxis).append("text").attr("transform", "rotate(-90)").attr("y", 6).attr("dy", ".71em").style("text-anchor", "end").text(metricname); chart.selectall(".bar").data(data).enter().append("rect").attr("class", "bar").attr("x", function(d) { return x(d.name); ).attr("y", function(d) { return y(d.value); ).attr("height", function(d) { return height - y(d.value); ).attr("width", x.rangeband()); ); )(); //JS CODE Ends here 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 12 of 18
9. The next step is to get the CSS part of the visualization. Simply copy the content that is inside of the <style> tag (do not insert the <style> nor </style> tags) into a new file and save it as global.css inside the C:\Program Files (x86)\apache Software Foundation\Tomcat 8.0\webapps\MicroStrategy\plugins\ExampleChart\style folder; We will have to change the classes to look like this:.custom-vis-layout.examplechart.{name of the class 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 13 of 18
The final file should be like this:.custom-vis-layout.examplechart.bar { fill: steelblue;.custom-vis-layout.examplechart.bar:hover { fill: brown;.custom-vis-layout.examplechart.axis { font: 10px sans-serif;.custom-vis-layout.examplechart.axis path,.axis line { fill: none; stroke: #000000; shape-rendering: crispedges;.custom-vis-layout.examplechart.x.axis path { display: none; 10. Create a new file inside the style folder and name it as Html5ViPage.css. We are going to use this file to change the icon of the custom D3 visualization. Paste this code inside this file:.mstrmojo-vigallery.mstrmojo-vigallerylist.item.ic- ExampleChart>div>div { background-image: url(images/examplecharticon.png); background-position: 0 0; background-size: contain; margin: 5px; Where ExampleChart must be the name of your plugin and ExampleChartIcon.png must be the name of the image that you are going to create in the next step. 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 14 of 18
11. Create a new folder inside style and name it as images. 12. Choose an image to be used for the icon and save it as ExampleChartIcon.png inside the images folder. The image must have 28x28 pixels. We are going to use this image. You can right click on the image below and save this image to be used as the icon; 13. Create a new folder inside WEB-INF and name it as xml 14. Create a new file and save it as stylecatalog.xml inside the xml folder. 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 15 of 18
15. Paste the code below in the stylecatalog.xml file. Note that we have to set the name, description and the ActualParameters value to use the name of the plugin that we are creating at the moment. You can use the description property to describe the visualization; <?xml version="1.0" encoding="utf-8" standalone="no"?> <!DOCTYPE StyleCatalog SYSTEM "stylecatalog.dtd"> <StyleCatalog> <Styles> <Style name="examplechart" description="d3 Example Chart" transform="reportajaxmojovisualizationtransform"> <ActualParameters> <ActualParameter name="documentstyle" type="1" value="rwgridjsonstyle" /> <ActualParameter name="reportxmlstyle" type="1" value="visualizationdatastyle" /> <ActualParameter name="mojoclassname" type="1" value="plugins.examplechart.examplechart"/> </ActualParameters> <Layouts> <Layout layout_source="applayoutsourcefile" order="1"> <![CDATA[/WEB-INF/xml/layouts/MojoVisualizationLayout.xml]]> </Layout> </Layouts> </Style> </Styles> </StyleCatalog> 16. Create a new folder inside WEB-INF/xml and name as config. 17. Create a new file inside config folder and name it as visualizations.xml. 18. Paste this content into this file: <visualizations> <visualization-list name="ajax"> <visualization id="mstrvistemplate" desc="nametorender" ismojo="true" scope="18" style-name="mstrvistemplatestyle"/> </visualization-list> </visualizations> 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 16 of 18
19. We will have to change the parameters for the visualization tag. The final code should resemble this: <visualizations> <visualization-list name="ajax"> <visualization id="examplechart" desc="example of D3 Chart" ismojo="true" scope="18" style-name="examplechart" attribute-minimum="1" metric-minimum="1"/> </visualization-list> </visualizations> Note that attribute-minimum and metric-mininum must have to correct values to be used for the chart. For example, if you are going to use another chart that must have at least 2 attributes and 1 metric to display the chart, you will have to update these values accordingly. 20. Now, restart your Web Server. 21. Create a new Dashboard and you will see the chart in the toolbar: 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 17 of 18
Those are the files that we must create in order to deploy a custom D3 visualization in MicroStrategy. You just have to follow these steps and change the values as described above to deploy other D3 charts. 8245 Boone Boulevard, Suite 500, Vienna, VA 22182 www.datameaning.com 888.4BI.DATA 18 of 18