Version 2021

Embed a Single Visualization

You can use the Embedding SDK to embed a dossier with a single visualization maximized. This gives the appearance of embedding a single visualization onto a page.

This functionality allows you to:

  • Target between a maximized view of a single visualization or a normal view of the entire dossier.
  • Add event handling so the parent portal is aware of the maximizing action performed by the user.
  • Select a single visualization to appear by default when the dossier opens.
  • Hide the maximize button so viewers cannot view the entire dossier.
  • Choose any visualization on the dossier to appear by default, even if it's not on the current page.

Check out the video below to see how it's done!

A full code sample is also provided below.

Embedding Workflow

When initializing a dossier page, you must specify which visualization will be maximized and the visibility of its resize button. When the visualization is resized, whether it’s by a manual click or the Embedding SDK, the dossier page raises an event to invoke a callback in your application.

  1. Change the visualization size.

    Function

    Dossier.changeVisualizationSize(props)

    The Dossier object is created using microstrategy.dossier.create(props). See Methods and Properties for an Embedded Dossier for more information.

    Input Parameters

    Parameter Name Description Data Type Required?
    props.visualizationKey

    The visualization node key entered by you or from the result of getCurrentPageVisualizationList.

    String Yes

    props.size

    The visualization sizing of "normal" or "maximized". If a string is not provided, the visualization size remains the same.

    String

    No

    props.resizeButtonVisible Determines whether the resize button is visible. If a Boolean is not provided, the visibility remains the same. Boolean No

    Response

    This API returns a promise object, similar to:

    myDossier && myDossier.changeVisualizationSize({
      visualizationKey: "K52",
      size: "maximized",
      resizeButtonVisible: true
    }).then(() => {
      ...
    }).catch(error => {
      ...
    })

    Since the target state is specified in the API parameters, the callback parameters for the resolve case are not necessary.

    Parameter Name Data Type Example Comments
    error

    Error Object

    new Error(“invalid operation!“) See API Errors for more information.
  2. Embed the dossier with a single visualization maximized.

    Function

    microstrategy.dossier.create(props)

    Input Parameters

    The props parameter contains several fields. See Methods and Properties for an Embedded Dossier for more information about these fields. In the props object, you must add a new optional field called visualizationAppearances. The props object contains the fields shown below.

    Parameter Name Description Data Type Required? Default Value
    props.visualizationAppearances[i].visualizationKey

    The visualization node key input by you.

    String Yes N/A

    props.visualizationAppearances[i].size

    Set to "normal" or "maximized".

    String

    No

    N/A

    props.visualizationAppearances[i].resizeButtonVisible Determines whether the resize button is visible. If a Boolean is not provided, the visibility remains the same. Boolean No N/A

    Example:

    microstrategy.dossier.create({  
    	...
    	visualizationAppearances: [{
    	    visualizationKey: "K52",
    	    size: "maximized",
    	    resizeButtonVisible: false
    	}]
    })

    If you don't enter values for visualizationAppearances, the dossier runs using the default behavior.

    Multiple visualizations are not supported. This is because size is coupled on different visualizations, in which only one visualization can be maximized.

    Response

    This API returns a dossier promise object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs.

    var placeholderDiv = document.getElementById("dossierContainer");
    var myDossier;
    microstrategy.dossier.create({  
    	...
    }).then(function(dossier){
        myDossier = dossier;
        myDossier.goToNextPage();
        ...
    });
  3. The resize visualization callback.

    When a user manually clicks the resize button for a visualization, an event is raised that notifies your application.

    Event Name

    Dossier.onVisualizationResized

    The Dossier object is created using microstrategy.dossier.create(props). See Methods and Properties for an Embedded Dossier for more information.

    Callback Format

    In the example below, registerEventHandler is an existing API:

    myDossier && myDossier.registerEventHandler('onVisualizationResized', function(resizedVisualization){
      ...      // The handling logic after resizing the visualization
    });

    in which the resizedVisualization callback parameter uses the following format:

    Parameter Name Description Data Type Sample
    resizedVisualization

    The resized visualization information, similar to:

    {
      visualizationKey: "string",
      size: "maximized"         
    }

    size is "normal" or "maximized".

    Object
    {
      visualizationKey: "K52",
      size: "maximized"
    }

API Errors

Since you cannot set the callback parameters, it’s impossible for these parameters to produce errors. When an error occurs for other reasons, the embedding API returns a promise object that in turn returns an error object in rejected cases. The possible errors are shown below.

Related APIs

Error Case Error Handler Callback Parameter Error Message
Dossier.changeVisualizationSize(props) The visKey is not a valid visualization key or it is not in the current page or panel stack.

Error Object

 

 

 

 

There isn’t a visualization whose key is “${0}“. Please check whether your input visKey is correct.

The dossier page is still loading.

You couldn’t manipulate a visualization when the page data is not ready. Please wait a few seconds to call this function again.

The dossier’s manipulation is not finished, so maximize or restore could not be performed. This may occur when the last maximize or restore is in progress.

You couldn’t resize a visualization when the dossier is busy for loading data.

Another visualization is already maximized.

Another visualization ${maximizedSiblingKey} is already maximized. Please call dossier.changeVisualizationSize({visualizationKey: "${maximizedSiblingKey}", size: "normal"}) to restore it first.

visualizationKey is missing. Invalid input for Dossier.changeVisualizationSize(props): data should have required property 'visualizationKey'

size is not a valid value.

Invalid input for Dossier.changeVisualizationSize(props): data.size should match pattern "(^(maximized|normal)$)"

resizeButtonVisible is not a valid value, Invalid input for Dossier.changeVisualizationSize(props): data.resizeButtonVisible should be boolean
microstrategy.dossier.create(props)
Dossier.changeVisualizationSize(props)

visualizationKey is missing

Error when valid parameter for microstrategy.dossier.create: data.visualizationAppearances[0] should have required property 'visualizationKey'

size is not a valid value. Error when valid parameter for microstrategy.dossier.create: data.visualizationAppearances[0].size should match pattern "(^(maximized|normal)$)"

resizeButtonVisible isn’t a valid value.

Error when valid parameter for microstrategy.dossier.create: data.visualizationAppearances[0].resizeButtonVisible should be boolean

The value of visualizationKey is not a valid visualization key or it is not in the current page or panel stack . There isn’t a visualization whose key is '${vizAppearance.visualizationKey}' in the current page. Please check whether your input 'visualizationkey' is correct.

Full Code Sample

Here is a full code sample containing the necessary HTML and JavaScript. Variables enclosed in < > must be replaced.

<html>
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
 
<body>
  <div class="container">
    <div class="page-header">
      <h1>Simple Embedding Sample with Single Vizualization</h1>
    </div>
  </div>
  <div>
    <div id="dossierContainer1" style="width: 100%;"></div>
  </div>
</body>
 
<!-- Replace path to point to the embeddingLib in your environment -->
            
<script src="https://env-XXXXXX.customer.cloud.microstrategy.com/MicroStrategyLibrary/javascript/embeddinglib.js"></script>
<script>
  //BEGIN CONFIG PARAMETERS -------------------------------------------------------------------------
  baseRestURL = "https://env-XXXXXX.customer.cloud.microstrategy.com/MicroStrategyLibrary";
  username = "<username>";
  password = "<password>";
  projectID = "<projectID>";
  dossierID = "<dossierID>";
  //END CONFIG PARAMETERS -------------------------------------------------------------------------
  //Form PostData for login REST request
  var postData = {};
  postData.username = username;
  postData.password = password;
  postData.loginMode = 1;
  var projectUrl = baseRestURL + '/app/' + projectID;
  var dossierUrl = projectUrl + '/' + dossierID;
  console.log("DossierURL: " + dossierUrl);
  //populate div with dossier
  microstrategy.dossier.create({
    placeholder: document.getElementById("dossierContainer1"),
    url: dossierUrl,
    enableCustomAuthentication: true,
    enableResponsive: true,
    customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
    visualizationAppearances: [{
	    visualizationKey: "<viz key>",
      // you can get the visualizationKey from this endpoint /api/dossiers/{dossierId}/definition
	    size: "maximized",
	    resizeButtonVisible: false
    }],
    getLoginToken: function() {
      return getXHRRequestPromise(baseRestURL + '/api/auth/login', postData, 'POST', 'application/json', 'x-mstr-authToken').then(function(authToken) {
        return authToken;
      })
    }
  }).then(function(dossier) {
	dossierContainer1 = dossier;
    //add any code you want to run after dossier loads    
  });
  function getXHRRequestPromise(url, body, method, contentType, desiredHeader) {
    return new Promise(function(resolve, reject) {
      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.withCredentials=true;
      xhr.setRequestHeader('Content-Type', 'application/json');
      xhr.setRequestHeader("Accept", "application/json");
      xhr.send(JSON.stringify(body));
      xhr.onreadystatechange = function() {
        if (xhr.readyState === 2) {
          resolve(xhr.getResponseHeader(desiredHeader));
        } else {
          reject({
            status: this.status,
            statusText: xhr.statusText
          });
        }
      };
    });
  };
​
</script>
</html>