How to Customize Visualizations Using the Visualization Builder

The Visualization Builder makes it easy to create and modify HTML5 visualizations.

If necessary, see Installing Visualization Builder for instructions on installing the Visualization Builder plug-in.

Before you begin, download the zip file that contains the files you will use in this topic. These files include:

  • OrgChartVisPlugin.zip
  • OrgChartData.xlsx
  • GoogleOrgChartWorld.mstr

To edit a custom visualization that has not been added to Workstation

  1. Open a new or existing dossier in Workstation.
  2. In the Visualization Gallery, click Add Visualization and choose Import Visualization.
  3. Navigate to and open the OrgChartVisPlugin.zip file that you downloaded earlier.

  4. Click OK.

    The custom visualization appears in the Visualization Gallery. Hover over the corresponding icon to display the corresponding requirements.

After loading the custom visualization into your project, you can open it in the Visualization Builder.

To open a custom visualization:

  1. Open the Workstation window.
  2. Choose Tools > Open Visualization Builder.

    The Visualization Builder opens.

  3. Select File > Open.
  4. Select the Org Chart visualization from the pop-up window.
  5. The Visualization Builder has six tabs for editing the visualization:
  6. Code Editor: Add or modify the following code for your visualization:

    Style: The CSS code that styles the visualization.

    Plot Code: The JavaScript that implements the visualization.

    Property Code: The JSON code that defines the custom properties.

    Dropzone Editor: Create, edit, and define the behavior of the custom drop zones for your visualization.

    Configuration: Set the following configuration properties for your visualization:

    • Visualization Name
    • Icon
    • Error message and details
    • Minimum number of attributes
    • Minimum number of metrics
    • Options to make your visualization available for use in reports, documents, and dossiers
    • External libraries used

    Editor: Displays the Dropzone panel that appears in the dossier. When you create a custom drop zone, it appears on this panel.

    Filter: Displays the Filter panel that appears in the dossier.

    Format: Display the Format panel that appears in the dossier. When you create a custom property, it appears on the Format panel.

To import data into a custom visualization

  1. Use the Org Chart visualization you opened in the previous procedure.
  2. Choose Add Data > New Data.

    The Data Sources dialog opens.

  3. Select File from Disk.

    The Local Drive dialog opens.

  4. Click Choose Files.
  5. Navigate to and open the OrgChartData.xlsx file that you downloaded earlier.
  6. Click Finish.

To create a custom drop zone for a custom visualization

  1. Open the Editor panel.
  2. Drag Manager and Employee from the Datasets panel to their corresponding areas on the Editor panel. Drag Row Count to the Metric area. There is no drop zone for Title.

    The new Org Chart World visualization appears on the right.

  3. Open the Dropzone Editor panel.
  4. In the Custom Zones area, scroll to the bottom of the list.

  5. Click New Zone to create a new drop zone for Title.
  6. The New Zone dialog opens

  7. Enter the following information for the new drop zone:
  8. Zone Name: Enter Title

    Element Type: Select Attribute

    Max Capacity: Enter 1

    Zone Tooltip: Enter Drag Title Here

    Disabled: Enter this.getDropZoneObjectsByName("Employee").length === 0;

  9. Click OK. The Title drop zone appears
  10. In the Custom Zones area, drag the Title above the Metric drop zone, so it appears along with the other attributes.
  11. Click Apply.
  12. Open the Editor panel.
  13. Drag Row Count from the Title area to the Metric area.
  14. In the Title area, right-click Row Count and choose Remove.
  15. Drag Title from the Datasets panel to the Title area of the Editor panel. The titles for all employees appears in the visualization. There should be one attribute or metric in each area of the Editor panel.
  16. Click Save .
  17. Click Yes.
  18. Click OK.

To add formatting to a custom visualization

The Org Chart visualization has two custom properties on the Format panel, Background Color and Selection Color. This visualization also has a default setting that allows you to collapse all child nodes when you double-click the parent node. In this section, you add a custom property that allows you to change the size of the text and add an option to disable the collapsing behavior.

  1. Open the Format panel.
  2. Select OrgChart Settings from the first drop-down.
  3. Notice the two custom properties, Background Color and Selection Color.
  4. In the visualization, double-click Martha Rivera. All of the employees under Martha collapse and are no longer visible.
  5. Double-click Martha Rivera again. All of the employees under Martha reappear.
  6. Open the Code Editor panel. You will add the code that makes the two color selections available in the Format panel.
  7. Scroll down to the Property Code pane and find the following lines of code:

    return [{ 
     name: 'OrgChart Settings', 
     value: [
    
  8. Paste the following code after the line that says value: [.

    {  
     style: $WT.EDITORGROUP, 
     items: [{ 
     style: $WT.LABEL, 
     name: "text", 
     width: "100%", 
     labelText: "Chart Size:" 
     }, { 
     style: $WT.BUTTONBAR, 
     propertyName: "size", 
     items: [ 
     { 
     labelText: "Small", 
     propertyName: "small" 
     }, 
     { 
     labelText: "Medium", 
     propertyName: "medium" 
     }, 
     { 
     labelText: "Large", 
     propertyName: "large" 
     } 
     ], 
     multiSelect: false, 
     config: { 
     suppressData: true 
     } 
     }] 
    },   { 
     style: $WT.EDITORGROUP, 
     items: [{  
     style: $WT.LABEL, 
     name: "text", 
     width: "100%", 
     labelText: "Collapse Option:" 
     }, {  
     style: $WT.CHECKBOXANDLABEL, 
     propertyName: "noCollapse", 
     labelText: "Disable collapse" 
     }] 
    },

    The first JSON object defines the button bar that corresponds with the size property. The second defines a checkbox that correspond to the collapse property. Both these properties are supported by the Org Chart World visualization. We created two sections, Chart Size and Collapse Option, using EDITORGROUP. Each section has defined properties with different styles of BUTTONBAR and CHECKBOXANDLABEL. See Custom Properties API: Creating and Using Custom Properties for more information about how to implement custom properties.

  9. Click Apply.
  10. Open the Format tab and select OrgChart Settings from the first drop-down.
  11. Verify that the two new options for Chart Size and Collapse Option appear.
  12. Open the Code Editor panel again. Next, you will add the code that makes the two new properties work.
  13. Scroll down to the Plot Code pane and find the following function in the code:

    function prepareChartOptions()

  14. Paste the following code after the line that says if(!is10Point2()).

    //configure chart size option var sizeOption = me.getProperty(CUSTOM_PROPERTIES.SIZE);
    if (sizeOption.small && sizeOption.small === 'true') { 
     option.size = 'small'; 
    } else if (sizeOption.large && sizeOption.large === 'true') { 
     option.size = 'large'; 
    } else { 
     option.size = 'medium'; 
    } 
    //collapse option 
    var noCollapse = me.getProperty('noCollapse'); 
    if (noCollapse && noCollapse === 'true') { 
      option.allowCollapse = false; 
    } 
    

    In the code above:

    • You retrieve the value of the size property. Depending on whether it is small, medium, or large (each button would be true or false), you set the value of option.size for the Org Chart World visualization.
    • You retrieve the value of the noCollapse property. This is a boolean value that determines the value of option.allowCollapse of the Org Chart World visualization.

  15. Scroll up and click Apply.
  16. Open the Format panel.
  17. Select OrgChart Settings from the first drop-down and verify the new options appear.
  18. Click Small, Medium, or Large to change the size of the text in the visualization.
  19. Select Disable Collapse and double-click any employee. The employee beneath the one you select remains visible and cannot be collapsed.
  20. Click Apply.
  21. Click Save.
  22. Click Yes.
  23. Click OK.

To use a custom visualization as a selector

  1. Open the Workstation window.
  2. Choose File > Open Local Dossier.
  3. Navigate to GoogleOrgChartWorld.mstr and open the file. This is one of the files you downloaded earlier.

    The Org Chart World visualization opens.

  4. Hover over the Org chart visualization, click More in the top right. In the list of available options, Select Target is not available. This option allows you to use the visualization as a selector, filtering data in other visualizations. Use the Visualization Builder to incorporate this functionality.
  5. Close the dossier and return to the Visualization Builder to add the code to make the filtering option available.
  6. Select the Code Editor panel.
  7. In the Plot Code area, add the following line of code on the first line:

    this.addUseAsFilterMenuItem();

  8. Scroll down to the line of code under function processMstrData(mstrData){ and look for:

    case me.zonesModel.getDropZoneObjectsByName(DROP_ZONES.EMPLOYEE)[0].id:

    employeeName = mstrData[i].headers[j].name;

  9. Paste the following code after the line mentioned above:

    //Build the selectorData to make the employee elements "used as a filter"

    selectorData.push(mstrData[i].headers[j].attributeSelector);

  10. To use the selector functionality, the code needs to send a selector object that contains the ID of the employee element that is selected and then build an array of attribute selector objects from that employee element. In the next step, you will add code that uses the index of the employee element to get the appropriate attribute selector from this selectorData array.

  11. Scroll up to function drawChart() and look for the following code:

    chart.draw(visData, chartOptions);

  12. Paste the following code after the line mentioned above:

    var selection = chart.getSelection();

    //ensure selection isn't empty

    if (selection.length) {

    var attributeSelector = selectorData[selection[0].row];

    me.applySelection(attributeSelector);

    }

    This code creates an event on the organization chart to apply the attribute selector of the element selected. You get this attribute selector object from the selectorData array that you previously built.

    google.visualization.events.addListener(chart, 'select', function() {

  13. Click Save.
  14. Click Yes.
  15. Click OK.

To confirm that you can use your visualization as a selector

  1. Open the Workstation window.
  2. Choose File > Open Local Dossier.
  3. Open the GoogleOrgChartWorld.mstr file.
  4. Hover over the visualization, click More in the top right, and choose Select Target.
  5. Click the Bar Chart visualization to select it as the target.
  6. Click Apply.
  7. In the Org Chart visualization, select Martha Rivera. The Bar Chart visualization below changes based on your selection.
  8. Select other employees to see the changes in the Bar Chart visualization.

To export in PDF format

Now that you have customized your visualization, you may want users to be able to export it to PDF. Out-of-the-box visualizations automatically support exporting to PDF (for example, File > Export to PDF), but for custom visualizations, you need to add code.

You can use the Visualization Builder to add the code that raises an event so that MicroStrategy knows when the visualization is ready for exporting. You can also use the Visualization Builder to disable animations only for exporting to speed up the exporting process. However, to add the code that specifies that your visualization supports exporting to PDF, you need to open the JavaScript file for the visualization with a text editor and add a few lines of code manually.

  • Raise a renderFinished event

  • When the custom visualization is ready for exporting, you need to add code to raise a renderFinished event. In order for a visualization to be ready for exporting, the visualization rendering and all of the animation actions after rendering - such as D3 transitions - must be complete. Sample code for raising a renderFinished event is shown below.

    this.raiseEvent({

    name: 'renderFinished',

    id: this.k

    });

  • Optionally, utilize the exporting flag, mstrApp.isExporting, to disable animations only for exporting

    You can speed up the exporting process by disabling animations only for exporting. The mstrApp.isExporting flag indicates the visualization is rendering for exporting so you can use this flag to do special handling for exporting, such as disabling animations instead of waiting for all of the animations to finish. Sample code for disabling animations is shown below.

    // Use 'default' mode to disable animation when exporting to PDF

    .mode(window.mstrApp&&window.mstrApp.isExporting?'default':'queue')

To enable and apply thresholds

The Threshold Editor lets you apply thresholds to metrics used by your custom visualization. In the Editor panel of your dossier, right-click the metric to which you want to apply a threshold and choose Thresholds to open the Threshold Editor. Refer to How to Enable and Apply Thresholds for Custom Visualizations Using the Metric Threshold Editor API for sample code and instructions on how to use APIs to make the threshold editor option visible.