Version 2021
Methods and Properties for an Embedded Dossier
This topic covers a method and corresponding properties for embedding a dossier, as well as a method to remove an embedded dossier.
Method and Properties for Embedding a Dossier
When you embed a MicroStrategy dossier into a web page, you use the create(props) method under the microstrategy.dossier namespace.
Method | Description | Return Value |
---|---|---|
microstrategy.dossier.create(props); |
This method creates an iFrame on the web page (in the location specified by the placeholder property) and inserts a link to the URL (specified by the url property) where the dossier to be embedded is located. |
This method returns a promise, which is resolved when the dossier instance is created. |
The props parameter contains required key:value pairs that define the URL where the dossier is located and the ID of the <div> placeholder where the iFrame containing the dossier instance will be created. It can also contain other optional key:value pairs to customize the UI, features, and authentication.
The props parameter can contain the following key:value pairs:
Property Name | Description | Required? | Default Value | Sample |
---|---|---|---|---|
placeholder |
Reference for the container <div>. |
Yes | ||
url or serverURL application ID objectID pageKey |
url refers to the full URL of the dossier to embed. There are two ways to configure the URL to embed the dossier in Library:
|
1.url is required 2. serverURL, application ID, and objectID are required, while pageKey is optional. |
|
Copy
|
containerHeight |
Sets the height of the placeholder. If the style of the placeholder has a height value, the containerHeight property is ignored. If the enableResponsive property is set to true, the containerWidth property is ignored and the containerHeight property takes effect. The containerHeight property is applied as a style: style="height: $(containerHeight)". You should not set the containerHeight property to 100% if the <div> container has no parent container, but is attached directly to the <body>. |
No | 600px | |
containerWidth |
Sets the width of the placeholder. If the style of the placeholder has a width value, the containerWidth property is ignored. If the enableResponsive property is set to true, the containerWidth property is ignored and the width is adjusted to fit the viewport. |
No |
800px |
|
custom Authentication Type |
Specifies the token type returned by the getLoginToken function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. | No | Custom Authentication Type.IDENTITY_ TOKEN | |
disable |
Specifies whether to display messages, such as Add to library in the notification bar. If this property is set to true, message do not appear in the notification bar. Manipulations are not affected by this property. They persist in the same way as the default dossier status. |
No |
|
|
dockedComment |
Use this property to configure the Comment panel on the UI. dockedPosition
canClose
dockChangeable
isDocked
|
No | null
The default status is used on the dossier. |
Docked Comment: Copy
|
dockedFilter |
Use this property to configure the Filter panel on the UI. dockedPosition
canClose
dockChangeable
isDocked
|
No |
|
Docked Filter: Copy
|
dockedTOC |
Use this property to configure the Table of Contents panel on the UI. dockedPosition
theme
canClose
dockChangeable
isDocked
|
No | null
The default status is used on the dossier. |
Docked TOC: Copy
|
dossierFeature |
Use this property to customize the dossier feature on the UI. readonly
|
No |
|
dossierFeature: Copy
|
enable |
Use this Boolean property to enable or disable collaboration-related controls of Library. |
No |
|
enableCollaboration: Copy
|
enableCustom |
Specifies whether custom authentication is enabled. |
No |
|
|
enableResponsive |
Specifies whether to enable responsive design. When this is set to true, the placeholder is adjusted to fit the width of the viewpoint and the existing width/height ratio is used to provide the height. |
No |
|
|
filterFeature |
Use this property to customize the filter functionality on the UI. All detailed properties below are Boolean. enabled
edit
summary
|
No |
|
Filter Feature: Copy
|
filters |
Use this property to apply attribute selection or attribute search filters during the execution of a dossier. It supports passing multiple filter definitions with multiple selectors. Filter Format: [{ "key": "string",
"name": "string",
"selections": [{
"id": "string",
"name": "string"
}]
}]
Filter Key/Filter Name Element ID/Element Name Only attribute selection filters and attribute search filters are supported. Attribute slider, calendar, and metric filters are not supported. |
No | null
No filters are applied during execution |
Filter Key with Element ID: Copy
Filter Name with Element Name: Copy
|
getLoginToken |
Specifies a function that returns a promise, which is resolved with either authorization token (authToken) or the identity token (identityToken) The token type is specified by the customAuthenticationType property. |
No |
See the sample code in the next column for the default implementation of this function. |
When customAuthenticationType is set to Copy
When customAuthenticationType is set to |
instance |
Use this property to specify the instance information for the embedded dossier.. mid
id
partialManipulation Boolean that indicates the personal view partial execution status. If this is set to true, a personal view is in partial execution status
|
No | null
|
Pass existing instance: Copy
|
navigationBar |
enabled
gotoLibrary
title
toc
reset
reprompt
share
comment
notification
filter
options
search
bookmark
|
No | null
The navigation bar is hidden by default |
Navigation Bar Configuration: Copy
|
optionsFeature |
Use this property to customize the Options feature on the UI. All detailed properties below are Boolean. enabled
help
logout
manage
showTutorials
|
No |
|
Options Feature: Copy
|
shareFeature |
Use this property to customize the Share feature on the UI. All detailed properties below are Boolean. enabled
invite
link
email
export
download
|
No |
|
Share Feature: Copy
Subscribe Feature: Copy
|
smartBanner |
Use this property to enable or disable the smart banner feature when a user opens an embedded dossier in a mobile browser. This property is supported on the dossier and login pages, but not the Library page. If credentials are not provided, the user is redirected to the login page and the property setting in the original URL remains in effect. |
No |
|
Smart Banner: Copy
|
tocFeature |
Use this property to customize the TOC feature on the UI. enabled
|
No |
|
TOC Feature: Copy
|
uiMessage |
Use this property to customize the message features on the UI. If disableNotification is set to true, this property is ignored and all messages are hidden. All detailed properties below are Boolean. enabled
addToLibrary
|
No |
|
UI Message: Copy
|
visibleTutorials |
Use this property to customize the visibility of tutorials. All detailed properties below are Boolean. welcome
library
dossier
notification
If the welcome tutorial is enabled, the Library tutorial is also automatically enabled. |
No |
|
Visible Tutorials: Copy
|
visualizationAppearances
|
Use this property to assign which visualization needs to be resized in the initial loading process, and whether the user could see the resize button of the visualization. See Embed a Single Visualization for more information. Format: [{ "visualizationkey": "K52", "size": "maximized", "resizeButtonVisible": false }]
|
No | null
No visualization needs to be maximized or restored during initial loading |
|
Method for Removing an Embedded Dossier
Method | Description | Return Value |
---|---|---|
microstrategy.dossier.destroy({placeholder: placeholderDiv}); |
Destroy the embedded dossier in the same placeholder you used when calling microstrategy.dossier.create. |
null |