From 04cb57bf559938b70ac8cb26a7d8f5651a985e19 Mon Sep 17 00:00:00 2001 From: ryu_mstr Date: Wed, 13 Mar 2024 18:36:03 +0800 Subject: [PATCH] Update the document to the newest release --- docs/add-functionality/add-event.md | 111 ++++++++++-- docs/add-functionality/add-functionality.md | 22 +-- docs/add-functionality/add-nav.md | 26 +-- .../attribute-element-selection.md | 12 +- docs/add-functionality/authoring-library.md | 62 +++---- docs/add-functionality/embed-vis.md | 52 +++--- docs/add-functionality/error-handling.md | 26 +-- docs/add-functionality/filters.md | 30 ++-- .../methods-and-properties.md | 56 +++--- docs/add-functionality/panel-stacks.md | 10 +- .../use-custom-dossier-link.md | 16 +- .../embed-dossier-consumption-page.md | 22 +-- .../embed-dossier-consumption-properties.md | 28 +-- .../embed-custom-ui-on-all-pages.md | 68 +++---- .../embed-library-properties.md | 33 +++- .../embed-report-properties.md | 6 +- .../dossier-consumption-page-apis.md | 16 +- docs/embedding-context/embedding-context.md | 10 +- docs/index.md | 12 +- .../apply-filter.md | 14 +- .../destroy-multiple-viz.md | 2 +- .../dossier-info-api.md | 24 +-- .../embed-bot-visualizations.md | 149 ++++++++++++++++ .../embed-multiple-viz.md | 16 +- .../embedding-components.md | 2 +- .../event-handling.md | 2 +- .../mstr-bot-visualization.md | 52 ++++++ .../native-embedding-architecture/mstr-bot.md | 167 ++++++++++++++++++ .../mstr-dossier.md | 10 +- .../mstr-environment.md | 70 ++++++-- .../vis-manipulation.md | 4 +- docs/playground.md | 12 +- .../authentication-saml.md | 4 +- .../guest-authentication-mode-only.md | 30 ++-- .../multiple-modes.md | 18 +- .../seamless-login.md | 6 +- .../standard-authentication.md | 28 +-- ...r-different-authentication-environments.md | 12 +- docs/whats-new-in-the-embedding-sdk.md | 39 ++-- sidebars.js | 7 +- 40 files changed, 912 insertions(+), 374 deletions(-) create mode 100644 docs/native-embedding-architecture/embed-bot-visualizations.md create mode 100644 docs/native-embedding-architecture/mstr-bot-visualization.md create mode 100644 docs/native-embedding-architecture/mstr-bot.md diff --git a/docs/add-functionality/add-event.md b/docs/add-functionality/add-event.md index c6bf4cd..fc6ebd0 100644 --- a/docs/add-functionality/add-event.md +++ b/docs/add-functionality/add-event.md @@ -1,17 +1,17 @@ --- title: Add event handling -description: Events allow an embedded dossier to communicate with the container page. You can listen for these events and provide event handler functions to respond to them. You use helper methods in the Embedding SDK to add event handling. For example, you can add code to capture selection events from one dossier and apply them as a filter to a second dossier. +description: Events allow an embedded dashboard to communicate with the container page. You can listen for these events and provide event handler functions to respond to them. You use helper methods in the Embedding SDK to add event handling. For example, you can add code to capture selection events from one dashboard and apply them as a filter to a second dashboard. --- -Events allow an embedded dossier to communicate with the container page. You can listen to these events and provide event handler functions to respond to them. You use helper methods in the Embedding SDK to add event handlers. For example, you can add code to capture selection events from one dossier and apply them as a filter to a second dossier. +Events allow an embedded dashboard to communicate with the container page. You can listen to these events and provide event handler functions to respond to them. You use helper methods in the Embedding SDK to add event handlers. For example, you can add code to capture selection events from one dashboard and apply them as a filter to a second dashboard. :::tip -To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g5) that embeds a dossier and adds event handling, as well as a description of [events](#events), [event handlers](#event-handlers), and [wrapper functions](#wrapper-functions) you can use to handle additional events. +To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g5) that embeds a dashboard and adds event handling, as well as a description of [events](#events), [event handlers](#event-handlers), and [wrapper functions](#wrapper-functions) you can use to handle additional events. ::: -Once you have used the `dossier.create(props)` method to embed a dossier into a third-party web page, you can use the methods described below to communicate between the dossier and the container page. You can register [event handlers](#event-handlers) for the [events](#events) that are automatically raised when a visualization is selected or when a page or filter is changed. [Wrapper functions](#wrapper-functions) are provided to make it easy to register event handlers for specific events. +Once you have used the `dossier.create(props)` method to embed a dashboard into a third-party web page, you can use the methods described below to communicate between the dashboard and the container page. You can register [event handlers](#event-handlers) for the [events](#events) that are automatically raised when a visualization is selected or when a page or filter is changed. [Wrapper functions](#wrapper-functions) are provided to make it easy to register event handlers for specific events. ## Events @@ -218,7 +218,7 @@ embedDossier.registerEventHandler(EventType.ON_PROMPT_ANSWERED, promptAnsweredHa ```json { - "messageName": "Sales Dossier (w/ Attribute Element Prompt)", + "messageName": "Sales Dashboard (w/ Attribute Element Prompt)", "answers": [ { "key": "3ECF2592C947B909B01624BCF690D6EA@0@10", @@ -361,6 +361,93 @@ embedDossier.registerEventHandler(EventType.ON_VISUALIZATION_RESIZED, vizResized } ``` +### onLibraryItemSelected + +#### Event enumeration + +`EventType.ON_LIBRARY_ITEM_SELECTED` + +#### Description + +Raised when a library item selected. Need library item select mode to be enabled. + +#### Content + +Object containing library item selection information. + +#### Code example + +```js +embedDossier.registerEventHandler(EventType.ON_LIBRARY_ITEM_SELECTED, libraryItemSelectionHandler); +``` + +#### Content example + +```json +[ + { + "id": "A7B1C43C4ABA7E499D4E1789A2EBCD55", + "docId": "BFB749B340572473A1288E9A2F6EDDA6", + "projectId": "B19DEDCC11D4E0EFC000EB9495D0F44F", + "name": "Distribution Center & Brands", + "type": 55, + "subtype": null + } +] +``` + +### onLibraryMenuSelected + +#### Event enumeration + +`EventType.ON_LIBRARY_MENU_SELECTED` + +#### Description + +Raised when a library menu selected. + +#### Content + +Object containing library menu selection information. + +#### Code example + +```js +embedDossier.registerEventHandler(EventType.ON_LIBRARY_MENU_SELECTED, libraryMenuSelectionHandler); +``` + +#### Content example + +```json +{ + "menuKey": "myContent", + "groupId": null +} +``` + +### onLibraryItemSelectionCleared + +#### Event enumeration + +`EventType.ON_LIBRARY_ITEM_SELECTION_CLEARED` + +#### Description + +Raised when a library item selection cleared. + +#### Content + +None + +#### Code example + +```js +embedDossier.registerEventHandler( + EventType.ON_LIBRARY_ITEM_SELECTION_CLEARED, + libraryItemSelectioClearnHandler +); +``` + ### onDossierInstanceIDChange #### Event enumeration @@ -369,7 +456,7 @@ embedDossier.registerEventHandler(EventType.ON_VISUALIZATION_RESIZED, vizResized #### Description -Raised when the embedded dossier instance id changes. +Raised when the embedded dashboard instance id changes. #### Content @@ -393,7 +480,7 @@ embedDossier.registerEventHandler(EventType.ON_DOSSIER_INSTANCE_ID_CHANGE, dossi #### Description -Raised when a dossier is saved after authoring or editing. +Raised when a dashboard is saved after authoring or editing. #### Content @@ -416,7 +503,7 @@ embedDossier.registerEventHandler( #### Description -Raised when the authoring or edit mode of dossier is closed. +Raised when the authoring or edit mode of dashboard is closed. #### Content @@ -439,7 +526,7 @@ embedDossier.registerEventHandler( #### Description -Raised when the dossier consumption page finishes rendering. +Raised when the dashboard consumption page finishes rendering. #### Content @@ -459,11 +546,11 @@ embedDossier.registerEventHandler(EventType.ON_PAGE_RENDER_FINISHED, pageRenderF #### Description -Raised when the a new dossier instance is created on a dossier consumption page. +Raised when the a new dashboard instance is created on a dashboard consumption page. #### Content -The event callback parameters contain the project id, dossier id and the instance id. +The event callback parameters contain the project id, dashboard id and the instance id. #### Code example @@ -491,7 +578,7 @@ embedDossier.registerEventHandler(EventType.ON_DOSSIER_INSTANCE_CHANGED, (conten #### Description -Raised when the dossier consumption page finishes rendering. +Raised when the dashboard consumption page finishes rendering. #### Content diff --git a/docs/add-functionality/add-functionality.md b/docs/add-functionality/add-functionality.md index 65656c9..4ba7598 100644 --- a/docs/add-functionality/add-functionality.md +++ b/docs/add-functionality/add-functionality.md @@ -1,25 +1,25 @@ --- -title: Add functionality to an embedded dossier +title: Add functionality to an embedded dashboard description: Once you have embedded a dossier, you can use helper methods in the Embedding SDK to add other functionality. The topics in this section describe how to implement different kinds of functionalities with code examples. --- Once you have embedded a dossier, you can use helper methods in the Embedding SDK to add other functionality. The topics in this section describe how to implement different kinds of functionalities with code examples. -- [Methods and properties for an embedded dossier](./methods-and-properties.md) +- [Methods and properties for an embedded dashboard](./methods-and-properties.md) - Describes the properties that can be set for an embedded dossier. Provides an example that modifies UI elements like the navigation bar and size of the embedded dossier through properties. + Describes the properties that can be set for an embedded dashboard. Provides an example that modifies UI elements like the navigation bar and size of the embedded dashboard through properties. - [Add navigation](./add-nav.md) - Describes the methods that can be used for navigation within an embedded dossier. For example, the Embedding SDK lets you add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. Provides an example that illustrates how to include navigation controls to allow users to page through the various chapters and pages of an embedded dossier. + Describes the methods that can be used for navigation within an embedded dashboard. For example, the Embedding SDK lets you add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. Provides an example that illustrates how to include navigation controls to allow users to page through the various chapters and pages of an embedded dashboard. - [Add event handling](./add-event.md) - Describes events that an embedded dossier can use to communicate with the container page and methods and wrapper functions for registering event handlers. For example, the Embedding SDK lets you add code to capture selection events from one dossier and apply them as a filter to a second dossier. Provides an example that illustrates how to capture selection events from one embedded dossier and apply them as a filter to a second dossier. + Describes events that an embedded dashboard can use to communicate with the container page and methods and wrapper functions for registering event handlers. For example, the Embedding SDK lets you add code to capture selection events from one dashboard and apply them as a filter to a second dashboard. Provides an example that illustrates how to capture selection events from one embedded dashboard and apply them as a filter to a second dashboard. - [Retrieve and apply filters](./filters.md) - Describes how to retrieve and apply filters for an embedded dossier and shows the filter details for each filter type, with code examples. For example, you can apply different kinds of filters to a chapter in a dossier, either during execution or after a dossier has been rendered. Provides examples on how to retrieve filters and apply each different type of filter. + Describes how to retrieve and apply filters for an embedded dashboard and shows the filter details for each filter type, with code examples. For example, you can apply different kinds of filters to a chapter in a dossier, either during execution or after a dashboard has been rendered. Provides examples on how to retrieve filters and apply each different type of filter. - [Error handling](./error-handling.md) @@ -27,19 +27,19 @@ Once you have embedded a dossier, you can use helper methods in the Embedding SD - [Interact with panel stacks](./panel-stacks.md) - Describes how to interact with panel stacks within dossier. Provides an example on panel-related APIs. + Describes how to interact with panel stacks within dashboard. Provides an example on panel-related APIs. - [Embed a single visualization](./embed-vis.md) - Describes how to embed a single visualization and set it to be maximized. Provides an example that shows embedding a dossier with a single visualization maximized and options to change which visualization to be maximized. + Describes how to embed a single visualization and set it to be maximized. Provides an example that shows embedding a dashboard with a single visualization maximized and options to change which visualization to be maximized. - [Enable the selection of attribute elements](./attribute-element-selection.md) - Describes how to programmatically make attribute element selections on an embedded dossier and capture the selection events. + Describes how to programmatically make attribute element selections on an embedded dashboard and capture the selection events. -- [Author an embedded dossier](./authoring-library.md) +- [Author an embedded dashboard](./authoring-library.md) - Describes how to embed a dossier in authoring or edit mode during the initial dossier load and after the dossier is loaded. + Describes how to embed a dashboard in authoring or edit mode during the initial dashboard load and after the dashboard is loaded. :::tip diff --git a/docs/add-functionality/add-nav.md b/docs/add-functionality/add-nav.md index 3dcf2c7..4510e92 100644 --- a/docs/add-functionality/add-nav.md +++ b/docs/add-functionality/add-nav.md @@ -1,9 +1,9 @@ --- title: Add navigation -description: Once you have embedded a dossier, you can use helper methods in the Embedding SDK to let users navigate within the dossier. For example, you can add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. +description: Once you have embedded a dossier, you can use helper methods in the Embedding SDK to let users navigate within the dashboard. For example, you can add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. --- -The Embedding SDK allows you to quickly integrate dossiers into a web application in a responsive manner. Once you have embedded a dossier, you can use helper methods in the Embedding SDK to let users navigate within the dossier. For example, you can add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. +The Embedding SDK allows you to quickly integrate dossiers into a web application in a responsive manner. Once you have embedded a dossier, you can use helper methods in the Embedding SDK to let users navigate within the dashboard. For example, you can add code to get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. :::tip @@ -13,7 +13,7 @@ To help you get started, we have provided a [page navigation example in the Embe ## Helper methods for navigation -You can use the methods described below to navigate within the dossier. You can get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. +You can use the methods described below to navigate within the dashboard. You can get the table of contents for the dossier, go to the previous or next page, navigate to a specific page, get the current page or chapter, get a specific page, or get a list of pages, chapters and visualizations. Most of the navigation is performed using methods of the Dossier class, but there is one method for navigation in the Chapter class. @@ -29,7 +29,7 @@ Most of the navigation is performed using methods of the Dossier class, but ther #### Description -Return the structure of the embedded dossier in the following format: +Return the structure of the embedded dashboard in the following format: ```json { @@ -80,7 +80,7 @@ embedDossier.getTableContent(); #### Description -Go to the previous page of the embedded dossier. +Go to the previous page of the embedded dashboard. Return a promise, resolved with @@ -113,7 +113,7 @@ embedDossier.goToPrevPage(); #### Description -Go to the next page of the embedded dossier. +Go to the next page of the embedded dashboard. Return a promise, resolved with @@ -146,7 +146,7 @@ embedDossier.goToNextPage(); #### Description -Switch to the specified page of the embedded dossier. +Switch to the specified page of the embedded dashboard. Return a promise, resolved with @@ -180,7 +180,7 @@ embedDossier.navigateToPage(lastPageOfChapter); #### Description -Return the current chapter of the embedded dossier. +Return the current chapter of the embedded dashboard. #### Example @@ -200,7 +200,7 @@ embedDossier.getCurrentChapter(); #### Description -Return the current page of the embedded dossier. +Return the current page of the embedded dashboard. #### Example @@ -220,7 +220,7 @@ embedDossier.getCurrentPage(); #### Description -Return the page of the embedded dossier with the specified `nodeKey`. +Return the page of the embedded dashboard with the specified `nodeKey`. You can get the `nodeKey` from the return value of `getTableContent()`, or You can get the `nodeKey` from the `nodeKey` property of the Page object (`Page.nodeKey`). @@ -242,7 +242,7 @@ embedDossier.getPageByNodeKey("K52"); #### Description -Return a list of all chapters in the embedded dossier. +Return a list of all chapters in the embedded dashboard. #### Example @@ -262,7 +262,7 @@ embedDossier.getChapterList(); #### Description -Return an array of all the visualizations in the current page of the embedded dossier. +Return an array of all the visualizations in the current page of the embedded dashboard. #### Example @@ -322,7 +322,7 @@ embedDossier.closeFilterSummaryBar(); #### Description -Return an array of all the pages in this chapter of the embedded dossier. +Return an array of all the pages in this chapter of the embedded dashboard. #### Example diff --git a/docs/add-functionality/attribute-element-selection.md b/docs/add-functionality/attribute-element-selection.md index 416bd1c..cdb063d 100644 --- a/docs/add-functionality/attribute-element-selection.md +++ b/docs/add-functionality/attribute-element-selection.md @@ -11,9 +11,9 @@ With the visualization element selection feature, the Embedding SDK could do the - Support programmatic selecting of attribute elements in visualizations. This involves the following: - a. Select attribute elements from a single visualization after the dossier is rendered. + a. Select attribute elements from a single visualization after the dashboard is rendered. - b. Select attribute elements in multiple visualizations on the initial loading of the dossier. + b. Select attribute elements in multiple visualizations on the initial loading of the dashboard. - Support programmatic retrieval of available elements in a visualization. @@ -27,7 +27,7 @@ With the visualization element selection feature, the Embedding SDK could do the `Dossier.selectVizElement(props)` -The Dossier object created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The Dossier object created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. #### Input parameters @@ -113,7 +113,7 @@ When an error occurs, this API returns a promise object that in turn returns an | The action is not "replace" and the current visualization selection mode is metric cell selection. | Invalid input | Web Dossier | Caught by the catch() of the promise object. | | The visualization is a filter and the target visualization is loading, so elements could not be selected. | Other | Web Dossier | Caught by the catch() of the promise object. | -### API for selecting attribute elements in multiple visualizations on initial dossier load +### API for selecting attribute elements in multiple visualizations on initial dashboard load #### Function @@ -121,7 +121,7 @@ When an error occurs, this API returns a promise object that in turn returns an #### Input parameters -An optional visualizationSelectedElements field has been added to the props object in 2021 Update 3. This field is an array that contains objects for each visualization attribute element selection. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information about the fields in the props input parameter. +An optional visualizationSelectedElements field has been added to the props object in 2021 Update 3. This field is an array that contains objects for each visualization attribute element selection. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information about the fields in the props input parameter. | Parameter Name | Description | Data Type | Required? | Default Value | | ------------------------------------------------------- | ------------------------------------------------ | --------- | --------- | ------------- | @@ -158,7 +158,7 @@ microstrategy.dossier.create({ }); ``` -If you do not enter a value for visualizationSelectedElements, the dossier runs using the old behavior and no new attribute elements are selected in the visualization. +If you do not enter a value for visualizationSelectedElements, the dashboard runs using the old behavior and no new attribute elements are selected in the visualization. #### Response diff --git a/docs/add-functionality/authoring-library.md b/docs/add-functionality/authoring-library.md index 36fabde..9372b43 100644 --- a/docs/add-functionality/authoring-library.md +++ b/docs/add-functionality/authoring-library.md @@ -1,13 +1,13 @@ --- -title: Author an embedded dossier -description: To allow users to conveniently edit a dossier, Embedding SDK allows embedding a dossier in the authoring mode, whether it is during the initial load or in the view mode of the dossier. +title: Author an embedded dashboard +description: To allow users to conveniently edit a dossier, Embedding SDK allows embedding a dashboard in the authoring mode, whether it is during the initial load or in the view mode of the dashboard. --- -Embedding MicroStrategy content within critical business applications empowers users to make smarter decisions by taking advantage of the dossier development efforts that occur behind the scenes. To allow users to conveniently edit a dossier, Embedding SDK allows embedding a dossier in the authoring mode, whether it is during the initial load or in the view mode of the dossier. +Embedding MicroStrategy content within critical business applications empowers users to make smarter decisions by taking advantage of the dashboard development efforts that occur behind the scenes. To allow users to conveniently edit a dossier, Embedding SDK allows embedding a dashboard in the authoring mode, whether it is during the initial load or in the view mode of the dashboard. :::tip -To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g16) that will embed a dossier in authoring mode along with an edit button that you can use to switch to authoring mode. You need to modify the environment url and dossier url to use your dossier and environment. See the steps to do this in [Introduction to Embedding SDK](../). +To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g16) that will embed a dashboard in authoring mode along with an edit button that you can use to switch to authoring mode. You need to modify the environment url and dashboard url to use your dashboard and environment. See the steps to do this in [Introduction to Embedding SDK](../). ::: @@ -17,24 +17,24 @@ With the Authoring Library feature, the Embedding SDK could enable the users to - Call `microstrategy.dossier.create` API with specific initialized parameters to: - a. Enter the authoring Library page to edit a dossier directly. + a. Enter the authoring Library page to edit a dashboard directly. - b. Hiding the Edit button in the navigation bar of the consumption Library page, to disable the user to edit the dossier. + b. Hiding the Edit button in the navigation bar of the consumption Library page, to disable the user to edit the dashboard. - Call the `Dossier.switchToMode` API to switch from view mode to authoring mode. -- Register events to notify the parent application when the dossier is saved or closed. +- Register events to notify the parent application when the dashboard is saved or closed. ## Authoring mode constraints ### The availability of existing Embedding SDK APIs -In authoring mode, most dossier-related APIs are disabled as they are designed for the consumption dossier instance. The remaining APIs supported in authoring mode are shown below. +In authoring mode, most dossier-related APIs are disabled as they are designed for the consumption dashboard instance. The remaining APIs supported in authoring mode are shown below. | Supported API | Description | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| microstrategy.dossier.create | Creates or destroys the embedded dossier view. | -| microstrategy.dossier.destroy | Creates or destroys the embedded dossier view. | +| microstrategy.dossier.create | Creates or destroys the embedded dashboard view. | +| microstrategy.dossier.destroy | Creates or destroys the embedded dashboard view. | | Dossier.switchToMode | The API added in this feature used in authoring mode. | | Dossier.registerEventHandler | Adds an event handler. | | Dossier.removeEventHandler | Removes an event handler. | @@ -56,7 +56,7 @@ To avoid unexpected events, except the newly added events (see the callback even ### Initial parameters -The props parameter contains many fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The props parameter contains many fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. The existing parameters can be roughly divided into three categories and their behaviors can be set with `dossierRenderingMode = authoring`. @@ -64,13 +64,13 @@ The existing parameters can be roughly divided into three categories and their b - The parameters used for some UI customization in consumption mode, for example, navigationBar.enabled. You can still use these parameters with dossierRenderingMode = authoring, but their effects can only be seen when switching back to consumption mode. -- The parameters used for some extra dossier instance manipulation, for example, filter and visualizationAppearances. These parameters are implementations of some embedding SDK APIs (for example, filter-related functions in the dossier class and changeVisualizationSize) for the initial workflow. As these embedding SDK APIs are forbidden in authoring mode, you must also forbid these parameters in the initial parameter in authoring mode to keep the consistent behavior. A complete list of these parameters are shown below. +- The parameters used for some extra dashboard instance manipulation, for example, filter and visualizationAppearances. These parameters are implementations of some embedding SDK APIs (for example, filter-related functions in the dashboard class and changeVisualizationSize) for the initial workflow. As these embedding SDK APIs are forbidden in authoring mode, you must also forbid these parameters in the initial parameter in authoring mode to keep the consistent behavior. A complete list of these parameters are shown below. -| Field Name | Description | -| ----------------------------- | ------------------------------------------------------------------------------------------- | -| filters | Applies filters to the dossier instance in consumption mode. | -| visualizationAppearances | Applies visualization appearance manipulations to the dossier instance in consumption mode. | -| visualizationSelectedElements | Applies visualization element selections to the dossier instance in consumption mode. | +| Field Name | Description | +| ----------------------------- | --------------------------------------------------------------------------------------------- | +| filters | Applies filters to the dashboard instance in consumption mode. | +| visualizationAppearances | Applies visualization appearance manipulations to the dashboard instance in consumption mode. | +| visualizationSelectedElements | Applies visualization element selections to the dashboard instance in consumption mode. | If you have set values for these fields when setting `dossierRenderingMode = authoring`, a dialog appears with the error message: @@ -88,7 +88,7 @@ The fields ["filters", "visualizationAppearances", "visualizationSelectedElement #### Input parameters -An optional `props.dossierRenderingMode` field has been added to the props object in 2021 Update 3. The `props` parameter contains many fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +An optional `props.dossierRenderingMode` field has been added to the props object in 2021 Update 3. The `props` parameter contains many fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. | Parameter Name | Data Type | Default Value | Available Values | Description | Required? | | -------------------------- | --------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | @@ -176,16 +176,16 @@ When an error occurs, the API returns a promise object that in turn returns an e | -------------------------------- | ---------------- | --------------- | -------------------------------------------- | | Dossier authoring isn’t allowed. | Unsupported case | Web Dossier | Caught by the catch() of the promise object. | -### Callback for monitoring when the dossier is saved or closed +### Callback for monitoring when the dashboard is saved or closed When the Save or Close button is clicked in authoring mode, an event is raised that notifies your application. #### Event name -| Parameter Name | Trigger | -| ------------------------ | --------------------------------------------- | -| onDossierAuthoringSaved | When the dossier is saved in authoring mode. | -| onDossierAuthoringClosed | When the dossier is closed in authoring mode. | +| Parameter Name | Trigger | +| ------------------------ | ----------------------------------------------- | +| onDossierAuthoringSaved | When the dashboard is saved in authoring mode. | +| onDossierAuthoringClosed | When the dashboard is closed in authoring mode. | #### Callback format @@ -211,7 +211,7 @@ myDossier.registerEventHandler(microstrategy.dossier.EventType.ON_DOSSIER_AUTHOR #### Input parameters -An optional `props.navigationBar.edit` field has been added to the `props` object. The `props` parameter contains many fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +An optional `props.navigationBar.edit` field has been added to the `props` object. The `props` parameter contains many fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. | Parameter Name | Data Type | Default Value | Description | Required? | | ------------------------ | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | @@ -228,7 +228,7 @@ microstrategy.dossier.create({ }); ``` -If you do not enter a value for `navigationBar`, the dossier runs using the old behavior and the navigation bar is hidden. +If you do not enter a value for `navigationBar`, the dashboard runs using the old behavior and the navigation bar is hidden. #### Response @@ -261,7 +261,7 @@ microstrategy.dossier | props.authoring.toolbar.tableOfContents.visible
props.authoring.toolbar.undo.visible
props.authoring.toolbar.redo.visible
props.authoring.toolbar.refresh.visible
props.authoring.toolbar.pauseDataRetrieval.visible
props.authoring.toolbar.reprompt.visible
props.authoring.toolbar.dividerLeft.visible
props.authoring.toolbar.addData.visible
props.authoring.toolbar.addChapter.visible
props.authoring.toolbar.addPage.visible
props.authoring.toolbar.insertVisualization.visible
props.authoring.toolbar.insertFilter.visible
props.authoring.toolbar.insertText.visible
props.authoring.toolbar.insertImage.visible
props.authoring.toolbar.insertHtml.visible
props.authoring.toolbar.insertShape.visible
props.authoring.toolbar.insertPanelStack.visible
props.authoring.toolbar.insertInfoWindow.visible
props.authoring.toolbar.save.visible
props.authoring.toolbar.dividerRight.visible
props.authoring.toolbar.more.visible
props.authoring.toolbar.freeformLayout.visible
props.authoring.toolbar.nlp.visible
props.authoring.toolbar.responsiveViewEditor.visible
props.authoring.toolbar.responsivePreview.visible | Boolean | true | Show or hide corresponding buttons on the toolbar in the authoring UI. | No | | props.authoring.panelVisibility.contents
props.authoring.panelVisibility.datasets
props.authoring.panelVisibility.editor
props.authoring.panelVisibility.filter
props.authoring.panelVisibility.format
props.authoring.panelVisibility.layers | Boolean | true | Show or hide corresponding authoring panels. | No | -The `props` parameter contains many fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The `props` parameter contains many fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. Example: @@ -303,7 +303,7 @@ When an error occurs, the API returns a promise object that in turn returns an e | The authoring parameter has the wrong input type. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | | The authoring.$\{key\} has the wrong input type. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | -### API for creating a new dossier for authoring +### API for creating a new dashboard for authoring #### Function @@ -311,11 +311,11 @@ When an error occurs, the API returns a promise object that in turn returns an e #### Input parameters -| Parameter Names | Data Type | Default Value | Description | Required? | -| ---------------- | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -| props.newDossier | Boolean | false | Use when creating a new dossier from scratch. When set to `true`, a new dossier instance is created from a blank dossier template. In this case, the `instance`, `objectID`, or `url` parameters don't have to and shouldn't be provided. | No | +| Parameter Names | Data Type | Default Value | Description | Required? | +| ---------------- | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| props.newDossier | Boolean | false | Use when creating a new dashboard from scratch. When set to `true`, a new dashboard instance is created from a blank dashboard template. In this case, the `instance`, `objectID`, or `url` parameters don't have to and shouldn't be provided. | No | -The `props` parameter contains many fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The `props` parameter contains many fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. Example: diff --git a/docs/add-functionality/embed-vis.md b/docs/add-functionality/embed-vis.md index fea63a8..e0cd2c5 100644 --- a/docs/add-functionality/embed-vis.md +++ b/docs/add-functionality/embed-vis.md @@ -1,17 +1,17 @@ --- title: Embed a single visualization -description: 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. +description: You can use the Embedding SDK to embed a dashboard with a single visualization maximized. This gives the appearance of embedding a single visualization onto a page. --- -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. +You can use the Embedding SDK to embed a dashboard 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. +- Target between a maximized view of a single visualization or a normal view of the entire dashboard. - 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. +- Select a single visualization to appear by default when the dashboard opens. +- Hide the maximize button so viewers cannot view the entire dashboard. +- Choose any visualization on the dashboard to appear by default, even if it's not on the current page. Check out the video below to see how it's done! @@ -23,13 +23,13 @@ Check out the video below to see how it's done! :::tip -To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g15) that will embed a dossier with a single visualization maximized with options to switch between `Max Size` and `Normal Size`. +To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g15) that will embed a dashboard with a single visualization maximized with options to switch between `Max Size` and `Normal Size`. ::: ## 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. +When initializing a dashboard 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 dashboard page raises an event to invoke a callback in your application. ![maximize_viz_workflow](../images/maximize_viz_workflow.png) @@ -39,7 +39,7 @@ When initializing a dossier page, you must specify which visualization will be m `Dossier.changeVisualizationSize(props)` -The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. #### Input parameters @@ -75,7 +75,7 @@ Since the target state is specified in the API parameters, the callback paramete | -------------- | ------------ | --------------------------------- | --------------------------------------------------- | | `error` | Error Object | `new Error("invalid operation!")` | See [API errors](#api-errors) for more information. | -### 2. Embed the dossier with a single visualization maximized +### 2. Embed the dashboard with a single visualization maximized #### Function @@ -83,7 +83,7 @@ Since the target state is specified in the API parameters, the callback paramete #### Input parameters -The `props` parameter contains several fields. See [Methods and properties for an embedded dossier](./methods-and-properties.md) 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. +The `props` parameter contains several fields. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) 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 | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------- | --------- | ------------- | @@ -106,7 +106,7 @@ microstrategy.dossier.create({ }); ``` -If you don't enter values for `visualizationAppearances`, the dossier runs using the default behavior. +If you don't enter values for `visualizationAppearances`, the dashboard 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. @@ -136,7 +136,7 @@ When a user manually clicks the resize button for a visualization, an event is r `Dossier.onVisualizationResized` -The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. #### Callback format @@ -164,16 +164,16 @@ in which the `resizedVisualization` callback parameter uses the following form 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 SDK 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. | +| 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 dashboard 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 dashboard'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 dashboard 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. | diff --git a/docs/add-functionality/error-handling.md b/docs/add-functionality/error-handling.md index e91de8c..ca6f6bd 100644 --- a/docs/add-functionality/error-handling.md +++ b/docs/add-functionality/error-handling.md @@ -1,6 +1,6 @@ --- title: Error handling -description: MicroStrategy provides custom error handling in two stages, during dossier creation and after dossier creation. +description: MicroStrategy provides custom error handling in two stages, during dashboard creation and after dashboard creation. --- By default, Library displays a pop-up dialog when an error occurs, such as when a dataset is not found. @@ -13,9 +13,9 @@ MicroStrategy also provides session error handling for session errors in two sta ## Custom error handling -### Custom error handling during dossier creation +### Custom error handling during dashboard creation -The error handler used during dossier creation in microstrategy.dossier.create is implemented by default. The error handler is executed when the error occurs and you can get details of the error in the customErrorHandler parameter. +The error handler used during dashboard creation in microstrategy.dossier.create is implemented by default. The error handler is executed when the error occurs and you can get details of the error in the customErrorHandler parameter. ```js microstrategy.dossier.create({ @@ -25,7 +25,7 @@ microstrategy.dossier.create({ }); ``` -To disable the custom error handler during dossier creation, set disableCustomErrorHandlerOnCreate to true. The default setting is false. +To disable the custom error handler during dashboard creation, set disableCustomErrorHandlerOnCreate to true. The default setting is false. ```js microstrategy.dossier.create({ @@ -35,9 +35,9 @@ microstrategy.dossier.create({ }); ``` -### Custom error handling after dossier creation +### Custom error handling after dashboard creation -You can also provide error handling after the dossier is created. The error handler is executed when the error occurs and you can get details of the error in the `customErrorHandler` parameter. +You can also provide error handling after the dashboard is created. The error handler is executed when the error occurs and you can get details of the error in the `customErrorHandler` parameter. If you do not configure this error handler and an error is encountered, the default pop-up mentioned at the beginning of this topic appears. @@ -69,7 +69,7 @@ microstrategy.dossier ### The overall MicroStrategy Library error behavior in embed case -The error generated by the embedded Library or dossier page would output an error log in the browser console. Besides that, +The error generated by the embedded Library or dashboard page would output an error log in the browser console. Besides that, - If `disableCustomErrorHandlerOnCreate` is set to `true` in `microstrategy.dossier.create` or `microstrategy.embeddingContexts.embedLibraryPage`, the custom error handler couldn't be registered. The error would only be shown by a popup error dialog, which is the same as the OOTB MicroStrategy Library behavior; - If `disableCustomErrorHandlerOnCreate` is not set or is `false`: @@ -86,11 +86,11 @@ When the session expiration error occurs: The differences from custom error handling: -The `sessionErrorHandler` created during dossier creation will not be deleted after dossier creation. It will continue to exist. +The `sessionErrorHandler` created during dashboard creation will not be deleted after dashboard creation. It will continue to exist. -There can be only one `sessionErrorHandler` function at the same time, whether during dossier creation or after dossier creation. So if you want to add a new `sessionErrorHandler`, you should use `removeSessionErrorhandler()` to remove the existing `sessionErrorHandler` first. +There can be only one `sessionErrorHandler` function at the same time, whether during dashboard creation or after dashboard creation. So if you want to add a new `sessionErrorHandler`, you should use `removeSessionErrorhandler()` to remove the existing `sessionErrorHandler` first. -### Session error handling during dossier creation +### Session error handling during dashboard creation The session error handler is executed when the error occurs and you can get details of the error in the `sessionErrorHandler` parameter. @@ -104,11 +104,11 @@ microstrategy.dossier.create({ }); ``` -In the `sessionErrorHandler`, the API user is responsible for re-logging in, and refreshing the dossier page. It could be done by triggering the original embedding logic, like calling `microstrategy.dossier.create()` again. The different authentication methods could be seen on the page [Support for different authentication environments](../support-for-different-authentication-environments/support-for-different-authentication-environments.md). +In the `sessionErrorHandler`, the API user is responsible for re-logging in, and refreshing the dashboard page. It could be done by triggering the original embedding logic, like calling `microstrategy.dossier.create()` again. The different authentication methods could be seen on the page [Support for different authentication environments](../support-for-different-authentication-environments/support-for-different-authentication-environments.md). -### Session error handling after dossier creation +### Session error handling after dashboard creation -You can also provide a session error handler after the dossier is created. The session error handler is executed when the session expiration error occurs and you can get details of the error in the `sessionErrorHandler` parameter. +You can also provide a session error handler after the dashboard is created. The session error handler is executed when the session expiration error occurs and you can get details of the error in the `sessionErrorHandler` parameter. If you do not configure this error handler and an error is encountered, the default pop-up mentioned at the beginning of this topic appears. diff --git a/docs/add-functionality/filters.md b/docs/add-functionality/filters.md index 11297dd..1384ce7 100644 --- a/docs/add-functionality/filters.md +++ b/docs/add-functionality/filters.md @@ -1,27 +1,27 @@ --- title: Retrieve and apply filters -description: Filters can be applied both during the execution of an embedded dossier and after it has been rendered. +description: Filters can be applied both during the execution of an embedded dashboard and after it has been rendered. --- -Filters can be applied both during the execution of an embedded dossier and after it has been rendered. +Filters can be applied both during the execution of an embedded dashboard and after it has been rendered. - **Apply filters during execution** - You can pass filters as properties when an embedded dossier is being executed. You use the `dossier.create(props)` method in the Embedding SDK and define the filters to apply using the [filters](./methods-and-properties.md#filters) property. + You can pass filters as properties when an embedded dashboard is being executed. You use the `dossier.create(props)` method in the Embedding SDK and define the filters to apply using the [filters](./methods-and-properties.md#filters) property. - **Apply and retrieve filters after execution** - Once you have used the `dossier.create(props)` method to embed a dossier into a third-party web page, you can use methods in the Embedding SDK to retrieve and apply filters. + Once you have used the `dossier.create(props)` method to embed a dashboard into a third-party web page, you can use methods in the Embedding SDK to retrieve and apply filters. - - [Retrieve filters after a dossier is rendered](#retrieve-filters-after-a-dossier-is-rendered) + - [Retrieve filters after a dashboard is rendered](#retrieve-filters-after-a-dashboard-is-rendered) - After an embedded dossier has been rendered, you can use the `getFilterList()` method of the `Dossier` class to retrieve information about filters that were applied to chapters in the dossier. + After an embedded dashboard has been rendered, you can use the `getFilterList()` method of the `Dossier` class to retrieve information about filters that were applied to chapters in the dossier. - - [Apply filters after a dossier is rendered](#apply-a-filter-after-the-dossier-is-rendered) + - [Apply filters after a dashboard is rendered](#apply-a-filter-after-the-dashboard-is-rendered) - After an embedded dossier has been rendered, you can apply different kinds of filters to chapters in the dossier using a number of different methods on the Embedding SDK. Chapter is the only filter type that is currently supported. + After an embedded dashboard has been rendered, you can apply different kinds of filters to chapters in the dashboard using a number of different methods on the Embedding SDK. Chapter is the only filter type that is currently supported. - - [Apply multiple filters after a dossier is rendered](#apply-multiple-filters-after-the-dossier-is-rendered) + - [Apply multiple filters after a dashboard is rendered](#apply-multiple-filters-after-the-dashboard-is-rendered) This section introduces how you can cache the results of several filters and apply them together. @@ -40,9 +40,9 @@ To help you get started, we have provided a set of filter examples in the Embedd ::: -## Retrieve filters after a dossier is rendered +## Retrieve filters after a dashboard is rendered -After an embedded dossier has been rendered, you can use the `getFilterList()` method of the `Dossier` class in the Embedding SDK to retrieve information about filters that were applied to chapters in the dossier. +After an embedded dashboard has been rendered, you can use the `getFilterList()` method of the `Dossier` class in the Embedding SDK to retrieve information about filters that were applied to chapters in the dossier. | `getFilterList()` | | | ----------------- | --------------------------------------------------------- | @@ -566,9 +566,9 @@ or } ``` -## Apply a filter after the dossier is rendered +## Apply a filter after the dashboard is rendered -After an embedded dossier has been rendered, you can apply different kinds of filters to chapters in the dossier using methods on the Embedding SDK. In this release, `getFilterList()` only exposes filters defined in the current chapter. +After an embedded dashboard has been rendered, you can apply different kinds of filters to chapters in the dashboard using methods on the Embedding SDK. In this release, `getFilterList()` only exposes filters defined in the current chapter. ### Dossier.filterSelectAllAttributes(filterJson) @@ -974,7 +974,7 @@ Applies all changes cached by `holdSubmit`. No parameters -## Apply multiple filters after the dossier is rendered +## Apply multiple filters after the dashboard is rendered This section introduces how you can cache the results of several filters and apply them together. Let's say you have the following filters: @@ -1002,7 +1002,7 @@ Take the following steps: ## Events -There are two events that are fired on the embedded dossier when a filter is applied after rendering. +There are two events that are fired on the embedded dashboard when a filter is applied after rendering. - [onFilterUpdated](./add-event.md#onfilterupdated) - [onVisualizationElementsChanged](./add-event.md#onvisualizationelementschanged) diff --git a/docs/add-functionality/methods-and-properties.md b/docs/add-functionality/methods-and-properties.md index 026bbb3..3c89298 100644 --- a/docs/add-functionality/methods-and-properties.md +++ b/docs/add-functionality/methods-and-properties.md @@ -1,13 +1,13 @@ --- -title: Methods and properties for an embedded dossier -description: When you embed a MicroStrategy dossier into a web page, you use the `create(props)` method under the `microstrategy.dossier` namespace. +title: Methods and properties for an embedded dashboard +description: When you embed a MicroStrategy dashboard into a web page, you use the `create(props)` method under the `microstrategy.dossier` namespace. --- -When you embed a MicroStrategy dossier into a web page, you use the `create(props)` method under the `microstrategy.dossier` namespace. +When you embed a MicroStrategy dashboard into a web page, you use the `create(props)` method under the `microstrategy.dossier` namespace. :::tip -To help you get started, we have provided an [example on playground](https://microstrategy.github.io/playground/?example=g1) that sets properties on an embedded dossier. Use the `create(props)` method under the `microstrategy.dossier` namespace to set properties. The props parameter contains optional key-value pairs to customize the UI, features, and authentication, in addition to the required key-value pairs that define the URL where the dossier is located and the ID of the `
` placeholder where the iFrame containing the dossier instance will be created. +To help you get started, we have provided an [example on playground](https://microstrategy.github.io/playground/?example=g1) that sets properties on an embedded dashboard. Use the `create(props)` method under the `microstrategy.dossier` namespace to set properties. The props parameter contains optional key-value pairs to customize the UI, features, and authentication, in addition to the required key-value pairs that define the URL where the dashboard is located and the ID of the `
` placeholder where the iFrame containing the dashboard instance will be created. This example is provided as an HTML file, which must be hosted on a web server. It cannot be run as a standalone file. @@ -17,13 +17,13 @@ This example is provided as an HTML file, which must be hosted on a web server. ### 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 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 dashboard to be embedded is located. #### Return value -This method returns a promise, which is resolved to a `Dossier` object when the dossier instance is created. +This method returns a promise, which is resolved to a `Dossier` object when the dashboard 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 `
` 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 contains required key-value pairs that define the URL where the dashboard is located and the ID of the `
` placeholder where the iFrame containing the dashboard instance will be created. It can also contain other optional key-value pairs to customize the UI, features, and authentication. Embedding too many pages using the Embedding SDK can lead to performance problems and even browser crashes due to limited browser resources. To ensure stable performance, it's recommended to embed the MicroStrategy Library page in no more than 4 to 6 containers. @@ -33,11 +33,11 @@ The `props` parameter is explained in [Properties](#properties). ### Dossier.getDossierInstanceId() -After calling `microstrategy.dossier.create(props)` to embed a dossier and get a `Dossier` object, you can use `Dossier.getDossierInstanceId()` to get the embedded dossier's instance id. +After calling `microstrategy.dossier.create(props)` to embed a dashboard and get a `Dossier` object, you can use `Dossier.getDossierInstanceId()` to get the embedded dashboard's instance id. #### Return value -This method returns a promise, which is resolved to the dossier instance id. An example is as below: +This method returns a promise, which is resolved to the dashboard instance id. An example is as below: #### Sample @@ -49,7 +49,7 @@ const myDossier = await microstrategy.dossier.create({ const instanceId = await myDossier.getDossierInstanceId(); ``` -The `instanceId` is a unique GUID, which is different each time you embed a dossier into a container. +The `instanceId` is a unique GUID, which is different each time you embed a dashboard into a container. ## Properties @@ -67,7 +67,7 @@ No ### `url`, `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` -The `url` property refers to the full URL of the dossier to be embedded. There are two ways to configure the URL to embed a dossier: +The `url` property refers to the full URL of the dashboard to be embedded. There are two ways to configure the URL to embed a dossier: 1. Use the `url` property to specify a full URL. 1. Use `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` properties. @@ -156,7 +156,7 @@ No The `disableNotification` property specifies whether to display messages, such as "Add to Library" in the notification bar. If this property is set to true, message does not appear in the notification bar. -Manipulations are not affected by this property. They persist in the same way as the default dossier status. +Manipulations are not affected by this property. They persist in the same way as the default dashboard status. #### Required? @@ -195,7 +195,7 @@ microstrategy.dossier ### `dockedComment` -The `dockedComment` object is used to configure the comments panel on the Dossier page. +The `dockedComment` object is used to configure the comments panel on the Dashboard page. - `dockedPosition` - Only `"left"` or `"right"` is accepted as the position of the docked panel. - `canClose` - `Boolean`. If set to `false`, the panel is forced to appear. @@ -231,7 +231,7 @@ microstrategy.dossier.create({ ### `dockedFilter` -The `dockedFilter` object is used to configure the filter panel on the Dossier page. +The `dockedFilter` object is used to configure the filter panel on the Dashboard page. - `dockedPosition` - Only `"left"` or `"right"` is accepted as the position of the docked panel. - `canClose` - `Boolean`. If set to `false`, the panel is forced to appear. @@ -267,7 +267,7 @@ microstrategy.dossier.create({ ### `dockedTOC` -The `dockedTOC` object is used to configure the Table of Contents (TOC) panel on the Dossier page. +The `dockedTOC` object is used to configure the Table of Contents (TOC) panel on the Dashboard page. - `dockedPosition` - Only `"left"` or `"right"` is accepted as the position of the docked panel. - `theme` - The color theme of the page. Only `"light"` or `"dark"` is accepted. The default is `"light"`. @@ -303,7 +303,7 @@ microstrategy.dossier.create({ ### `dossierFeature` -The `dossierFeature` object is used to customize the dossier feature on the Dossier page. +The `dossierFeature` object is used to customize the dashboard feature on the Dashboard page. - `readonly` - Enable or disable context menus. If this property is set to `true`, all context menus are disabled. This includes the visualization right-mouse-click context menu and the context menu at the top right of the visualization that contains options such as Export. @@ -415,7 +415,7 @@ microstrategy.dossier.create({ ### `filters` -Use the `filters` object to apply attribute selection or attribute search filters during the execution of a dossier. It supports passing multiple filter definitions with multiple selectors. +Use the `filters` object to apply attribute selection or attribute search filters during the execution of a dashboard. It supports passing multiple filter definitions with multiple selectors. Filter Format: @@ -564,7 +564,7 @@ When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOK ### `instance` -Use this `instance` object to specify a dossier instance for the embedded dossier. If you would like to make some manipulation to the dossier before it is embedded, you can use this property, e.g., answering prompts. If the `instance` is used, the Embedding SDK will use it instead of creating a dossier instance. +Use this `instance` object to specify a dashboard instance for the embedded dashboard. If you would like to make some manipulation to the dashboard before it is embedded, you can use this property, e.g., answering prompts. If the `instance` is used, the Embedding SDK will use it instead of creating a dashboard instance. - `mid` - This instance ID. - `id` - Instance ID for a report-based in-memory dossier. @@ -600,7 +600,7 @@ Use the `navigationBar` object to customize the navigation bar on the page. All - `enabled` - Enable or disable the navigation bar. The default is `false`. - `gotoLibrary` - Show or hide the gotoLibrary icon. The default is `true`. -- `title` - Show or hide the dossier title. The default is `true`. +- `title` - Show or hide the dashboard title. The default is `true`. - `toc` - Show or hide the TOC icon. The default is `true`. - `reset` - Show or hide the reset icon. The default is `true`. - `reprompt` - Show or hide the reprompt icon. The default is `true`. @@ -651,7 +651,7 @@ microstrategy.dossier.create({ ### `customUi` -Use the `customUi` object to customize the UI component visibilities except the dossier consumption and authoring pages. The detailed properties are as below: +Use the `customUi` object to customize the UI component visibilities except the dashboard consumption and authoring pages. The detailed properties are as below: - `library` - This field is used to customized the UI components on the MicroStrategy Library home page. Its details could be seen in [The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md#propscustomuilibrary) - `reportConsumption` - This field is used to customize the UI components on the report consumption page. Its details could be seen in [The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md#propscustomuireportconsumption). @@ -785,9 +785,9 @@ microstrategy.dossier.create({ ### `smartBanner` -Use the `smartBanner` property to enable or disable the smart banner feature when a user opens an embedded dossier in a mobile browser. +Use the `smartBanner` property to enable or disable the smart banner feature when a user opens an embedded dashboard 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. +This property is supported on the dashboard 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. #### Required? @@ -856,7 +856,7 @@ No `null` -Depends on the default status of the dossier and the value in the `disableNotification` property. +Depends on the default status of the dashboard and the value in the `disableNotification` property. #### Sample @@ -879,7 +879,7 @@ Use this property to customize the visibility of tutorials. All detailed propert - `welcome` - Enable or disable the welcome tutorial. - `library` - Enable or disable the Library tutorial. -- `dossier` - Enable or disable the dossier tutorial. +- `dossier` - Enable or disable the dashboard tutorial. - `notification` - Enable or disable the notification tutorial. If the welcome tutorial is enabled, the Library tutorial is also automatically enabled. @@ -913,7 +913,7 @@ microstrategy.dossier.create({ ### `visualizationAppearances` -If you want to show just one visualization on the dossier page, use the `visualizationAppearances` object 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](./embed-vis.md) for more information about the feature. +If you want to show just one visualization on the dashboard page, use the `visualizationAppearances` object 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](./embed-vis.md) for more information about the feature. Format: @@ -943,7 +943,7 @@ No visualization needs to be maximized or restored during initial loading. ### `authoring` -The `authoring` object controls the dossier interface in authoring mode. See [Author an embedded dossier](./authoring-library.md#api-for-controlling-the-authoring-ui) for details. +The `authoring` object controls the dashboard interface in authoring mode. See [Author an embedded dashboard](./authoring-library.md#api-for-controlling-the-authoring-ui) for details. ### `errorHandler` @@ -953,7 +953,7 @@ The custom error handler that is executed when an error occurs in the dossier-cr The custom error handler that is executed when the session expires in the embedding lifetime. See [Custom error handling](./error-handling.md#session-error-handling) for details. -## Method for removing an embedded dossier +## Method for removing an embedded dashboard ### microstrategy.dossier.destroy(config) @@ -963,7 +963,7 @@ The config parameter: {"placeholder": placeholderDiv} ``` -This method removes the embedded dossier in the same placeholder you used when calling `microstrategy.dossier.create`. The `placeholder` refers to the DOM object of the container `
`. +This method removes the embedded dashboard in the same placeholder you used when calling `microstrategy.dossier.create`. The `placeholder` refers to the DOM object of the container `
`. #### Return value diff --git a/docs/add-functionality/panel-stacks.md b/docs/add-functionality/panel-stacks.md index d4f86d3..4945cb5 100644 --- a/docs/add-functionality/panel-stacks.md +++ b/docs/add-functionality/panel-stacks.md @@ -1,9 +1,9 @@ --- title: Interact with panel stacks -description: Panel stacks provide end users with the ability to conveniently reuse segments of space within a dossier to represent data in multiple ways. MicroStrategy supports one level of nesting within panel stacks. You can switch panel stacks by using a selector or the panel stack header. An application can now develop external controls to paginate through the various displays within a panel stack. In addition, if the panel stack is switched by a user's manual input, an event handler notifies the parent application of this action, allowing it to perform filtering or any other desirable action. +description: Panel stacks provide end users with the ability to conveniently reuse segments of space within a dashboard to represent data in multiple ways. MicroStrategy supports one level of nesting within panel stacks. You can switch panel stacks by using a selector or the panel stack header. An application can now develop external controls to paginate through the various displays within a panel stack. In addition, if the panel stack is switched by a user's manual input, an event handler notifies the parent application of this action, allowing it to perform filtering or any other desirable action. --- -The MicroStrategy 2021 Update 1 release exposed [panel stacks](https://www2.microstrategy.com/producthelp/2021/Workstation/WebHelp/Lang_1033/Content/panel_stacks.htm) within dossiers. This provides end users with the ability to conveniently reuse segments of space within a dossier to represent data in multiple ways. To provide continuity with our existing APIs and enable embedded applications to take advantage of this new design concept, we have updated existing endpoints and provided new Embedding SDK functions. +The MicroStrategy 2021 Update 1 release exposed [panel stacks](https://www2.microstrategy.com/producthelp/2021/Workstation/WebHelp/Lang_1033/Content/panel_stacks.htm) within dossiers. This provides end users with the ability to conveniently reuse segments of space within a dashboard to represent data in multiple ways. To provide continuity with our existing APIs and enable embedded applications to take advantage of this new design concept, we have updated existing endpoints and provided new Embedding SDK functions. MicroStrategy supports one level of nesting within panel stacks. You can switch panel stacks by using a selector or the panel stack header. @@ -13,7 +13,7 @@ Similar to providing navigation capabilities through provided embedded SDK funct :::tip -To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g23) that will embed a dossier with a panel stack and the option to switch between panels. +To help you get started, we have provided an [example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g23) that will embed a dashboard with a panel stack and the option to switch between panels. ::: @@ -128,7 +128,7 @@ In which the callback parameters are: :::tip -The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dossier](./methods-and-properties.md) for more information. +The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dashboard](./methods-and-properties.md) for more information. ::: @@ -310,7 +310,7 @@ N/A ##### Error message -You couldn’t switch a panel when the dossier is busy for loading data. Please wait for a while... +You couldn’t switch a panel when the dashboard is busy for loading data. Please wait for a while... #### Error case: REST API error diff --git a/docs/add-functionality/use-custom-dossier-link.md b/docs/add-functionality/use-custom-dossier-link.md index d9abf4a..1de32e0 100644 --- a/docs/add-functionality/use-custom-dossier-link.md +++ b/docs/add-functionality/use-custom-dossier-link.md @@ -1,15 +1,15 @@ --- -title: How to handle dossier link in email notifications when sharing content +title: How to handle dashboard link in email notifications when sharing content description: The client application could get the embed URL from the application settings. --- -In a client application that embeds a dossier page, if you want the share link in the embedded dossier page to be the client application URL instead of the embedded dossier URL, you need to configure the "Host Web Portal" in the client application settings: +In a client application that embeds a dashboard page, if you want the share link in the embedded dashboard page to be the client application URL instead of the embedded dashboard URL, you need to configure the "Host Web Portal" in the client application settings: ![Host Web Portal](../images/application-config.png) -If you set the "Host Web Portal" value to be the URL of the client application, when you share the dossier via email: +If you set the "Host Web Portal" value to be the URL of the client application, when you share the dashboard via email: -![Share Dossier Email](../images/dossier-email.png) +![Share Dashboard Email](../images/dossier-email.png) The link in the email would be a url like: @@ -17,19 +17,19 @@ The link in the email would be a url like: http://{hostWebPortal}?mstrLibraryLink=https%3A%2F%2Fdemo%2Emicrostrategy%2Ecom%3A8080%2FMicroStrategyLibrary%2Fapp%2F9D8A49D54E04E0BE62C877ACC18A5A0A%2F0627433046E1B80BCE681C87E48F5C28%2Fbookmarks%3Fids%3D77776092475755EE696EEABF94CF3A61 ``` -You can see it's the client application URL, not the embedded dossier URL. However, in this URL, the url-encoded result of the embedded dossier url is still stored in the value of the query parameter `mstrLibraryLink`. In the above case, it's the url-encoded result of +You can see it's the client application URL, not the embedded dashboard URL. However, in this URL, the url-encoded result of the embedded dashboard url is still stored in the value of the query parameter `mstrLibraryLink`. In the above case, it's the url-encoded result of ```url https://demo.microstrategy.com:8080/MicroStrategyLibrary/app/9D8A49D54E04E0BE62C877ACC18A5A0A/0627433046E1B80BCE681C87E48F5C28/bookmarks?ids=77776092475755EE696EEABF94CF3A61 ``` -So the client application could use this URL to recover the status of the embedded dossier page. It could get the embedded dossier url via the parameter `mstrLibraryLink` like this: +So the client application could use this URL to recover the status of the embedded dashboard page. It could get the embedded dashboard url via the parameter `mstrLibraryLink` like this: ```js -// The original embeded dossier URL. Would be used if there is no "mstrLibraryLink" parameter +// The original embeded dashboard URL. Would be used if there is no "mstrLibraryLink" parameter let dossierUrl = "https://demo.microstrategy.com:8080/MicroStrategyLibrary/app/9D8A49D54E04E0BE62C877ACC18A5A0A/0627433046E1B80BCE681C87E48F5C28"; -// The logic to get the embedded dossier URL +// The logic to get the embedded dashboard URL const url = new URL(window.location.href); const mstrLibraryLink = url.searchParams.get("mstrLibraryLink"); // Use this URL to replace the original URL if you want diff --git a/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md b/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md index 426556e..394ff65 100644 --- a/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md +++ b/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md @@ -1,11 +1,11 @@ --- -title: Embed MicroStrategy dossier consumption page -description: The Embedding SDK allows you to quickly integrate a MicroStrategy dossier consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as toggling the navigation bar and setting the visibility of icons in the navigation bar. +title: Embed MicroStrategy dashboard consumption page +description: The Embedding SDK allows you to quickly integrate a MicroStrategy dashboard consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as toggling the navigation bar and setting the visibility of icons in the navigation bar. --- -The Embedding SDK allows you to quickly integrate a MicroStrategy dossier consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as toggling the navigation bar and setting the visibility of icons in the navigation bar. +The Embedding SDK allows you to quickly integrate a MicroStrategy dashboard consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as toggling the navigation bar and setting the visibility of icons in the navigation bar. -There are three basic steps for embedding a MicroStrategy dossier consumption page. +There are three basic steps for embedding a MicroStrategy dashboard consumption page. 1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. @@ -15,13 +15,13 @@ There are three basic steps for embedding a MicroStrategy dossier consumption pa Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). -1. Create a `
` as the placeholder where you want to embed the dossier consumption page. +1. Create a `
` as the placeholder where you want to embed the dashboard consumption page. ```html
``` -1. Call the `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` method to embed the dossier consumption page in the container. +1. Call the `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` method to embed the dashboard consumption page in the container. ```js microstrategy.embeddingContexts.embedDossierConsumptionPage({ @@ -32,14 +32,14 @@ There are three basic steps for embedding a MicroStrategy dossier consumption pa }); ``` -The `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` API is an upgraded version of `microstrategy.dossier.create(props)`. Both of these 2 APIs embed the dossier consumption page after the initial loading, but `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` supports the user to navigate between the dossier consumption pages and the other types of pages, like Library homepage and report pages, while `microstrategy.dossier.create(props)` doesn't support that. +The `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` API is an upgraded version of `microstrategy.dossier.create(props)`. Both of these 2 APIs embed the dashboard consumption page after the initial loading, but `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` supports the user to navigate between the dashboard consumption pages and the other types of pages, like Library homepage and report pages, while `microstrategy.dossier.create(props)` doesn't support that. To help you get started, we have provided a number of simple applications with sample code and explanations. -- [Properties for an embedded MicroStrategy dossier consumption page](./embed-dossier-consumption-properties.md) +- [Properties for an embedded MicroStrategy dashboard consumption page](./embed-dossier-consumption-properties.md) - Describes the properties that can be set for an embedded MicroStrategy dossier consumption page. + Describes the properties that can be set for an embedded MicroStrategy dashboard consumption page. -- [Dossier consumption page APIs](../embedding-context/dossier-consumption-page-apis.md) +- [Dashboard consumption page APIs](../embedding-context/dossier-consumption-page-apis.md) - Describes which Embedding SDK APIs are available on the MicroStrategy dossier consumption page. + Describes which Embedding SDK APIs are available on the MicroStrategy dashboard consumption page. diff --git a/docs/embed-dossier-consumption-page/embed-dossier-consumption-properties.md b/docs/embed-dossier-consumption-page/embed-dossier-consumption-properties.md index afbf34b..df3b002 100644 --- a/docs/embed-dossier-consumption-page/embed-dossier-consumption-properties.md +++ b/docs/embed-dossier-consumption-page/embed-dossier-consumption-properties.md @@ -1,23 +1,23 @@ --- -title: Properties for an embedded MicroStrategy dossier consumption page -description: Describes the properties that can be set for an embedded MicroStrategy dossier consumption page. +title: Properties for an embedded MicroStrategy dashboard consumption page +description: Describes the properties that can be set for an embedded MicroStrategy dashboard consumption page. --- -When you embed a MicroStrategy dossier consumption page into a web page, you use the `embedDossierConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a MicroStrategy dashboard consumption page into a web page, you use the `embedDossierConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` -This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the MicroStrategy dossier consumption page URL (specified by the `serverUrl` property). +This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the MicroStrategy dashboard consumption page URL (specified by the `serverUrl` property). #### Return value -This method returns a promise, which is resolved when the MicroStrategy dossier consumption page is loaded. +This method returns a promise, which is resolved when the MicroStrategy dashboard consumption page is loaded. #### Input parameters -The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the MicroStrategy dossier consumption page will be created. It can also contain other optional key:value pairs to customize the UI, authentication and custom error handler. +The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the MicroStrategy dashboard consumption page will be created. It can also contain other optional key:value pairs to customize the UI, authentication and custom error handler. The `props` parameter could contain the following key:value pairs: @@ -48,7 +48,7 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ ### `serverUrl`, `projectId`, `objectId` -The required parameters in the dossier URL. +The required parameters in the dashboard URL. These properties build the full report page URL to be embedded. The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. @@ -74,7 +74,7 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ ### `customApplicationId`, `pageKey` -The optional parameters in the dossier URL. +The optional parameters in the dashboard URL. Specifies the application and page that the user wants to show in the embedded page. @@ -230,7 +230,7 @@ To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to If this flag is set, all the errors occur in the initial loading process and manual actions would be handled by OOTB Library itself, an error dialog would pop up. -You could also refer to [Custom error handling during dossier creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation). +You could also refer to [Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation). #### Required? @@ -307,7 +307,7 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ ### `customUi` -Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dossier consumption page，dossier authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dashboard consumption page，dashboard authoring page, and report consumption page. #### Properties @@ -315,7 +315,7 @@ Please see all the properties in [The customized UI settings in Embedding SDK](. ### `settings` -Specify the custom settings on the embedding pages. Including the non-UI settings of dossier consumption page. +Specify the custom settings on the embedding pages. Including the non-UI settings of dashboard consumption page. #### Required? @@ -325,16 +325,16 @@ No ##### `dossierConsumption` -Use the `dossierConsumption` object to customize the options on the dossier consumption page. The detailed properties contain: +Use the `dossierConsumption` object to customize the options on the dashboard consumption page. The detailed properties contain: - `componentSelectionMode` - - To assign the selection mode of the visualizations or groups on the dossier consumption page. + - To assign the selection mode of the visualizations or groups on the dashboard consumption page. - Available values: ["noSelection", "singleSelection", "multipleSelection"] - Default value: "noSelection". - `disableManipulationsAutoSaving` - - Disable the dossier instance manipulation auto saving or not. + - Disable the dashboard instance manipulation auto saving or not. - Default value: `false`. #### Sample diff --git a/docs/embed-library-main-page/embed-custom-ui-on-all-pages.md b/docs/embed-library-main-page/embed-custom-ui-on-all-pages.md index 4900f64..4614460 100644 --- a/docs/embed-library-main-page/embed-custom-ui-on-all-pages.md +++ b/docs/embed-library-main-page/embed-custom-ui-on-all-pages.md @@ -1,9 +1,9 @@ --- title: The customized UI settings in Embedding SDK -description: The Embedding SDK enables you to customize the UI components of all embedded pages, like MicroStrategy home page, dossier consumption page, dossier authoring page, and report consumption page. +description: The Embedding SDK enables you to customize the UI components of all embedded pages, like MicroStrategy home page, dashboard consumption page, dashboard authoring page, and report consumption page. --- -The Embedding SDK supports the user to customize the UI components of all embedded pages, including MicroStrategy home page, dossier consumption page, dossier authoring page, and report consumption page. To do this, you need to set the input parameters `props.customUi` in the functions below: +The Embedding SDK supports the user to customize the UI components of all embedded pages, including MicroStrategy home page, dashboard consumption page, dashboard authoring page, and report consumption page. To do this, you need to set the input parameters `props.customUi` in the functions below: - `microstrategy.embeddingContexts.embedLibraryPage(props)` - `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` @@ -159,7 +159,7 @@ microstrategy.embeddingContexts.embedLibraryPage({ }); ``` -In the example above, the user uses `microstrategy.embeddingContexts.embedLibraryPage` to embed a MicroStrategy Library home page. After the embedded page is loaded, the user may click a dossier in the dossier list to go to a dossier consumption page, or RMC the "Edit" menu to go to a dossier authoring page. The user could use fields `props.customUi.dossierConsumption` and `props.customUi.dossierAuthoring` to show or hide the components in these 2 pages. +In the example above, the user uses `microstrategy.embeddingContexts.embedLibraryPage` to embed a MicroStrategy Library home page. After the embedded page is loaded, the user may click a dashboard in the dashboard list to go to a dashboard consumption page, or RMC the "Edit" menu to go to a dashboard authoring page. The user could use fields `props.customUi.dossierConsumption` and `props.customUi.dossierAuthoring` to show or hide the components in these 2 pages. The details of `props.customUi` are as below: @@ -185,7 +185,7 @@ Use the `sidebar` object to customize the sidebar on the MicroStrategy Library h Use the `navigationBar` object to customize navigation bar on the MicroStrategy Library home page. All detailed properties below are `Boolean`. - `enabled` - - Show the Library home page navigation bar or not. If the navigation bar is disabled in custom application, the true value wouldn’t take effect, which is the same as the original dossier navigation bar icons behavior. + - Show the Library home page navigation bar or not. If the navigation bar is disabled in custom application, the true value wouldn’t take effect, which is the same as the original dashboard navigation bar icons behavior. - Default value: `true`. - `sortAndFilter` - Show the library filter icon and the search bar on the Library home page navigation bar or not. @@ -215,7 +215,7 @@ No ### `props.customUi.dossierConsumption` -This field is used to customized the UI components on the dossier consumption page. It has 1 property: `navigationBar`. +This field is used to customized the UI components on the dashboard consumption page. It has 1 property: `navigationBar`. #### Properties @@ -230,7 +230,7 @@ Use the `navigationBar` object to customize the navigation bar on the page. All - Show or hide the gotoLibrary icon. - Default value: `true`. - `title` - - Show or hide the dossier title. + - Show or hide the dashboard title. - Default value: `true`. - `toc` - Show or hide the TOC icon. @@ -275,93 +275,93 @@ No ### `props.customUi.dossierAuthoring` -This field is used to customized the UI components on the dossier authoring page. It has 2 properties: `toolbar` and `menubar`. +This field is used to customized the UI components on the dashboard authoring page. It has 2 properties: `toolbar` and `menubar`. #### Properties ##### `toolbar` -Use the `toolbar` object to customize the visibilities of the toolbar icons on the dossier authoring page. All detailed properties below are `Boolean`. +Use the `toolbar` object to customize the visibilities of the toolbar icons on the dashboard authoring page. All detailed properties below are `Boolean`. - `tableOfContents.visible` - - Show the TOC button on the dossier authoring page toolbar or not. + - Show the TOC button on the dashboard authoring page toolbar or not. - Default value: `true`. - `undo.visible` - - Show the undo button on the dossier authoring page toolbar or not. + - Show the undo button on the dashboard authoring page toolbar or not. - Default value: `true`. - `redo.visible` - - Show the redo button on the dossier authoring page toolbar or not. + - Show the redo button on the dashboard authoring page toolbar or not. - Default value: `true`. - `refresh.visible` - - Show the refresh button on the dossier authoring page toolbar or not. + - Show the refresh button on the dashboard authoring page toolbar or not. - Default value: `true`. - `pauseDataRetrieval.visible` - - Show the "pauseDataRetrieval" button on the dossier authoring page toolbar or not. + - Show the "pauseDataRetrieval" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `dividerLeft.visible` - - Show the left divider on the dossier authoring page toolbar or not. + - Show the left divider on the dashboard authoring page toolbar or not. - Default value: `true`. - `addData.visible` - - Show the "Add Data" button on the dossier authoring page toolbar or not. + - Show the "Add Data" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `addChapter.visible` - - Show the "Add Chapter" button on the dossier authoring page toolbar or not. + - Show the "Add Chapter" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `addPage.visible` - - Show the "Add Page" button on the dossier authoring page toolbar or not. + - Show the "Add Page" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertVisualization.visible` - - Show the "Visualization" button on the dossier authoring page toolbar or not. + - Show the "Visualization" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertFilter.visible` - - Show the "Filter" button on the dossier authoring page toolbar or not. + - Show the "Filter" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertText.visible` - - Show the "Text" button on the dossier authoring page toolbar or not. + - Show the "Text" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertImage.visible` - - Show the "Image" button on the dossier authoring page toolbar or not. + - Show the "Image" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertHtml.visible` - - Show the "Html" button on the dossier authoring page toolbar or not. + - Show the "Html" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertShape.visible` - - Show the "Shape" button on the dossier authoring page toolbar or not. + - Show the "Shape" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertPanelStack.visible` - - Show the "Panel Stack" button on the dossier authoring page toolbar or not. + - Show the "Panel Stack" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `insertInfoWindow.visible` - - Show the "Information Window" button on the dossier authoring page toolbar or not. + - Show the "Information Window" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `save.visible` - - Show the save button on the dossier authoring page toolbar or not. + - Show the save button on the dashboard authoring page toolbar or not. - Default value: `true`. - `dividerRight.visible` - - Show the right divider on the dossier authoring page toolbar or not. + - Show the right divider on the dashboard authoring page toolbar or not. - Default value: `true`. - `more.visible` - - Show the "More" button(Only shown in small window) on the dossier authoring page toolbar or not. + - Show the "More" button(Only shown in small window) on the dashboard authoring page toolbar or not. - Default value: `true`. - `freeformLayout.visible` - - Show the "Freeform Layout" button on the dossier authoring page toolbar or not. + - Show the "Freeform Layout" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `nlp.visible` - - Show the nlp button on the dossier authoring page toolbar or not. + - Show the nlp button on the dashboard authoring page toolbar or not. - Default value: `true`. - `responsiveViewEditor.visible` - - Show the "Responsive View Editor" button on the dossier authoring page toolbar or not. + - Show the "Responsive View Editor" button on the dashboard authoring page toolbar or not. - Default value: `true`. - `responsivePreview.visible` - - Show the "Responsive Preview" button on the dossier authoring page toolbar or not. + - Show the "Responsive Preview" button on the dashboard authoring page toolbar or not. - Default value: `true` ##### `menubar` -Use the `menubar` object to customize the visibilities of the menubar items on the dossier authoring page. All detailed properties below are `Boolean`. +Use the `menubar` object to customize the visibilities of the menubar items on the dashboard authoring page. All detailed properties below are `Boolean`. - `library.visible` - - Show the Library home icon on the dossier authoring page menubar or not. + - Show the Library home icon on the dashboard authoring page menubar or not. - Default value: `true`. ### `props.customUi.reportConsumption` diff --git a/docs/embed-library-main-page/embed-library-properties.md b/docs/embed-library-main-page/embed-library-properties.md index eebdd69..a41b51e 100644 --- a/docs/embed-library-main-page/embed-library-properties.md +++ b/docs/embed-library-main-page/embed-library-properties.md @@ -181,7 +181,7 @@ To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to If this flag is set, all the errors occur in the initial loading process and manual actions would be handled by OOTB Library itself, an error dialog would pop up. -You could also refer to [Custom error handling during dossier creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation) to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as in `microstrategy.embeddingContexts.embedLibraryPage` function. +You could also refer to [Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation) to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as in `microstrategy.embeddingContexts.embedLibraryPage` function. #### Required? @@ -265,7 +265,7 @@ Specifies the application that the user wants to show in the embedded page. The application in MicroStrategy has 2 categories: - If the application selects library home page as its home screen, the library home page would be embedded with the application's configuration. -- If the application selects a dossier as its home screen, the embedding would fail and an error would occur. +- If the application selects a dashboard as its home screen, the embedding would fail and an error would occur. #### Required? @@ -281,7 +281,7 @@ N/A ### `customUi` -Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dossier consumption page，dossier authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dashboard consumption page，dashboard authoring page, and report consumption page. #### Properties @@ -325,6 +325,33 @@ The special behaviors are as below: - If sidebar is disabled in the application settings, whether setting `customUi.library.sidebar.show` to true or false, the sidebar couldn't be shown. - If the navigation bar is enabled in `customUi.library.navigationBar.enabled` and application settings, and "Collapse toolbar by default" is enabled by default, when `customUi.library.sidebar.show` is true, the navigation bar would be expanded and shown. +### `libraryItemSelectMode` + +Specifies the library item select mode on the embedded pages, including grid and list views. + +#### Required? + +No + +#### Default value + +N/A + +#### Allowed values + +- single +- multiple + +#### Sample + +```js +microstrategy.embeddingContexts.embedLibraryPage({ + placeholder: placeholderDiv, + serverUrl: "http://{host}:{port}/{Library}", + libraryItemSelectMode: "single", +}); +``` + ### `currentPage` Specifies the page on the sidebar entries that you want to embed. diff --git a/docs/embed-report-page/embed-report-properties.md b/docs/embed-report-page/embed-report-properties.md index f9939c7..e48daf1 100644 --- a/docs/embed-report-page/embed-report-properties.md +++ b/docs/embed-report-page/embed-report-properties.md @@ -195,7 +195,7 @@ To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to If this flag is set, all errors that occur in the initial loading process as the result of manual actions are handled by OOTB Library and an error dialog appears. -Refer to [Custom error handling during dossier creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation) to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as in the `microstrategy.embeddingContexts.embedReportPage` function. +Refer to [Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dossier-creation) to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as in the `microstrategy.embeddingContexts.embedReportPage` function. #### Required? @@ -285,7 +285,7 @@ Specifies the application that the user wants to show in the embedded page. The application in MicroStrategy has two categories: - If the application selects the Library home page as its home screen, the Library home page is embedded with the application's configuration. -- If the application selects a dossier as its home screen, the embedding fails and an error occurs. +- If the application selects a dashboard as its home screen, the embedding fails and an error occurs. #### Required? @@ -301,7 +301,7 @@ N/A ### `customUi` -Specifies the custom UI settings on the embedded pages, including the MicroStrategy Library home, dossier consumption，dossier authoring, and report consumption pages. +Specifies the custom UI settings on the embedded pages, including the MicroStrategy Library home, dashboard consumption，dashboard authoring, and report consumption pages. #### Properties diff --git a/docs/embedding-context/dossier-consumption-page-apis.md b/docs/embedding-context/dossier-consumption-page-apis.md index aa2535c..0038be1 100644 --- a/docs/embedding-context/dossier-consumption-page-apis.md +++ b/docs/embedding-context/dossier-consumption-page-apis.md @@ -1,21 +1,21 @@ --- -title: Dossier consumption page APIs -description: Describes which Embedding SDK APIs are available on the MicroStrategy dossier consumption page. +title: Dashboard consumption page APIs +description: Describes which Embedding SDK APIs are available on the MicroStrategy dashboard consumption page. --- -The `dossierConsumption` object is the manipulator of the MicroStrategy dossier consumption page. It could be got by `embeddingContext.dossierConsumption`. +The `dossierConsumption` object is the manipulator of the MicroStrategy dashboard consumption page. It could be got by `embeddingContext.dossierConsumption`. The details of the `embeddingContext` object could be seen in [Embedding context](./embedding-context.md). The APIs under Library page object are as below. -## Dossier consumption page APIs +## Dashboard consumption page APIs ### `getDossierDefinition()` #### Description -This API is used for getting the dossier definition. Its result contains the dossier id, name, project id and TOC information. +This API is used for getting the dashboard definition. Its result contains the dashboard id, name, project id and TOC information. #### Class @@ -23,7 +23,7 @@ This API is used for getting the dossier definition. Its result contains the dos #### Return type -This API would return a Promise object that resolves to an object that contains the dossier definition. Its serialized JSON string is as below: +This API would return a Promise object that resolves to an object that contains the dashboard definition. Its serialized JSON string is as below: ```json { @@ -66,7 +66,7 @@ try { #### Description -This API could be used to select visualizations or groups on a dossier consumption page. +This API could be used to select visualizations or groups on a dashboard consumption page. #### Class @@ -105,7 +105,7 @@ try { #### Description -This API could be used to get currently selected visualizations and groups on a dossier consumption page. +This API could be used to get currently selected visualizations and groups on a dashboard consumption page. #### Class diff --git a/docs/embedding-context/embedding-context.md b/docs/embedding-context/embedding-context.md index 35084ad..d9c320f 100644 --- a/docs/embedding-context/embedding-context.md +++ b/docs/embedding-context/embedding-context.md @@ -26,7 +26,7 @@ The `embedLibraryPage()` function above can be replaced to the other functions u This `embeddingContext` object could be used when the user navigates between different types of pages. It has several fields: - `libraryPage`: used for call the APIs that interact with the Library homepage. The detailed APIs could be seen in [Library page APIs](./library-page-apis.md) -- `dossierConsumption`: used for call the APIs that interact with the dossier consumption page. The detailed APIs could be seen in [Dossier consumption page APIs](./dossier-consumption-page-apis.md) +- `dossierConsumption`: used for call the APIs that interact with the dashboard consumption page. The detailed APIs could be seen in [Dashboard consumption page APIs](./dossier-consumption-page-apis.md) If the current embedded page is the Library homepage, and the user uses the manipulation object of the other pages, like `embeddingContext.dossierConsumption` to call the APIs of the other page, there would be an error. @@ -62,7 +62,7 @@ See the identical function in [Event handlers](../add-functionality/add-event#re #### Description -See the identical function in [Custom error handling after dossier creation](../add-functionality/error-handling#custom-error-handling-after-dossier-creation). +See the identical function in [Custom error handling after dashboard creation](../add-functionality/error-handling#custom-error-handling-after-dossier-creation). ### `removeCustomErrorHandler()` @@ -72,7 +72,7 @@ See the identical function in [Custom error handling after dossier creation](../ #### Description -See the identical function in [Custom error handling after dossier creation](../add-functionality/error-handling#custom-error-handling-after-dossier-creation). +See the identical function in [Custom error handling after dashboard creation](../add-functionality/error-handling#custom-error-handling-after-dossier-creation). ### `addSessionErrorHandler(handler)` @@ -82,7 +82,7 @@ See the identical function in [Custom error handling after dossier creation](../ #### Description -See the identical function in [Session error handling after dossier creation](../add-functionality/error-handling#session-error-handling-after-dossier-creation). +See the identical function in [Session error handling after dashboard creation](../add-functionality/error-handling#session-error-handling-after-dossier-creation). ### `removeSessionErrorhandler()` @@ -92,4 +92,4 @@ See the identical function in [Session error handling after dossier creation](.. #### Description -See the identical function in [Session error handling after dossier creation](../add-functionality/error-handling#session-error-handling-after-dossier-creation). +See the identical function in [Session error handling after dashboard creation](../add-functionality/error-handling#session-error-handling-after-dossier-creation). diff --git a/docs/index.md b/docs/index.md index b48373e..4291b7f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,12 @@ --- title: Introduction to the Embedding SDK slug: / -description: The Embedding SDK allows you to quickly integrate a MicroStrategy dossier into a web application in a responsive manner. It also provides resources to add functionality such as controlling navigation, retrieving and applying filters, setting properties, and managing events, and supports several different authentication environments. +description: The Embedding SDK allows you to quickly integrate a MicroStrategy dashboard into a web application in a responsive manner. It also provides resources to add functionality such as controlling navigation, retrieving and applying filters, setting properties, and managing events, and supports several different authentication environments. --- -The Embedding SDK allows you to quickly integrate a MicroStrategy dossier into a web application in a responsive manner. It also provides resources to add functionality such as controlling navigation, retrieving and applying filters, setting properties, and managing events, and supports several different authentication environments. +The Embedding SDK allows you to quickly integrate a MicroStrategy dashboard into a web application in a responsive manner. It also provides resources to add functionality such as controlling navigation, retrieving and applying filters, setting properties, and managing events, and supports several different authentication environments. -There are three basic steps for embedding a dossier. +There are three basic steps for embedding a dashboard. 1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. @@ -22,7 +22,7 @@ There are three basic steps for embedding a dossier. ::: -1. Create a `
` as the placeholder where you want to embed the dossier. +1. Create a `
` as the placeholder where you want to embed the dashboard. ```html
@@ -40,7 +40,7 @@ There are three basic steps for embedding a dossier. :::tip - Check out all the [properties](./add-functionality/methods-and-properties.md#properties) you can set in the `microstrategy.dossier.create(props)` method. You can do many things with the [properties](./add-functionality/methods-and-properties.md#properties). To name a few, you can set filters, show/hide UI elements, and adjust the size of the embedded dossier. + Check out all the [properties](./add-functionality/methods-and-properties.md#properties) you can set in the `microstrategy.dossier.create(props)` method. You can do many things with the [properties](./add-functionality/methods-and-properties.md#properties). To name a few, you can set filters, show/hide UI elements, and adjust the size of the embedded dashboard. ::: @@ -48,7 +48,7 @@ To help you get started, we have provided a number of simple applications with s - [Support for different authentication environments](./support-for-different-authentication-environments/support-for-different-authentication-environments.md) - Examples that display an embedded dossier in different authentication environments + Examples that display an embedded dashboard in different authentication environments - [Add functionality](./add-functionality/add-functionality.md) diff --git a/docs/native-embedding-architecture/apply-filter.md b/docs/native-embedding-architecture/apply-filter.md index 3785ea5..5e8c948 100644 --- a/docs/native-embedding-architecture/apply-filter.md +++ b/docs/native-embedding-architecture/apply-filter.md @@ -1,11 +1,11 @@ --- title: Retrieve and apply filters -description: Filters can be applied both during the execution of an embedded dossier and after it has been rendered. +description: Filters can be applied both during the execution of an embedded dashboard and after it has been rendered. --- -Filters can be applied both during the execution of an embedded dossier and after it has been rendered. After using [Native Embedding SDK](embed-multiple-viz.md) to embed multiple visualizations in a client's webpage, you can manipulate the chapter-level filters, on-page selectors, and visualizations used as filters via the Native Embedding SDK available since 2021 Update 9. For chapter-level filters and on-page selectors, MicroStrategy only supports attribute element list selectors. +Filters can be applied both during the execution of an embedded dashboard and after it has been rendered. After using [Native Embedding SDK](embed-multiple-viz.md) to embed multiple visualizations in a client's webpage, you can manipulate the chapter-level filters, on-page selectors, and visualizations used as filters via the Native Embedding SDK available since 2021 Update 9. For chapter-level filters and on-page selectors, MicroStrategy only supports attribute element list selectors. Let's say you already have the `MstrEnvironment` and `MstrDossier` objects: @@ -14,7 +14,7 @@ try { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK }, }); const mstrDossier = await mstrEnvironment.loadDossier({ @@ -76,7 +76,7 @@ Example of the attribute element list in the resolved value: ## Apply filters after embedded visualizations are rendered -After embedded visualizations have been rendered, you can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to retrieve information about filters, selectors, and visualizations used as filters in the dossier. After you have the key of the filter, selector, or visualization used as a filter, you can use the `MstrDossier.applyFilter()` function to manipulate it. +After embedded visualizations have been rendered, you can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to retrieve information about filters, selectors, and visualizations used as filters in the dashboard. After you have the key of the filter, selector, or visualization used as a filter, you can use the `MstrDossier.applyFilter()` function to manipulate it. :::note For filters and selectors, we currently only support manipulating the selector type of the attribute element list. @@ -96,7 +96,7 @@ The sections below show the filter details for each filter type. #### Chapter-level filters -For the chapter-level filter with an `attribute_element_list` type, you can get its key and source attribute definition from the dossier definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the filter with the `MstrDossier.applyFilter()` function as follows. After the function successfully returns, all embedded visualizations on the same chapter as the filter are refreshed to reflect the latest data. +For the chapter-level filter with an `attribute_element_list` type, you can get its key and source attribute definition from the dashboard definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the filter with the `MstrDossier.applyFilter()` function as follows. After the function successfully returns, all embedded visualizations on the same chapter as the filter are refreshed to reflect the latest data. ```js try { @@ -120,7 +120,7 @@ try { #### On-Page selectors -For on-page selectors with an `attribute_element_list` type, you can get its key from the dossier definition and source attribute definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the filter with the `MstrDossier.applyFilter()` function as follows. After the function successfully returns, all embedded visualizations that are the targets of the selector are refreshed to reflect the latest data. +For on-page selectors with an `attribute_element_list` type, you can get its key from the dashboard definition and source attribute definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the filter with the `MstrDossier.applyFilter()` function as follows. After the function successfully returns, all embedded visualizations that are the targets of the selector are refreshed to reflect the latest data. ```js try { @@ -144,7 +144,7 @@ try { #### Visualizations used as filters -For a visualization used as a filter, you need its key from the dossier definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the visualization used as a filter with `MstrDossier.applyFilter()` function as follows. After the function successfully returns, the elements of the visualization used as a filter are highlighted accordingly, and all embedded visualizations that are the targets of the visualization as the filter are refreshed to reflect the latest data. +For a visualization used as a filter, you need its key from the dashboard definition with the `MstrDossier.getDossierDefinition()` function. Then you can manipulate the visualization used as a filter with `MstrDossier.applyFilter()` function as follows. After the function successfully returns, the elements of the visualization used as a filter are highlighted accordingly, and all embedded visualizations that are the targets of the visualization as the filter are refreshed to reflect the latest data. - attribute element selection diff --git a/docs/native-embedding-architecture/destroy-multiple-viz.md b/docs/native-embedding-architecture/destroy-multiple-viz.md index 9b4d176..7813620 100644 --- a/docs/native-embedding-architecture/destroy-multiple-viz.md +++ b/docs/native-embedding-architecture/destroy-multiple-viz.md @@ -18,7 +18,7 @@ try { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK }, }); const mstrDossier = await mstrEnvironment.loadDossier({ diff --git a/docs/native-embedding-architecture/dossier-info-api.md b/docs/native-embedding-architecture/dossier-info-api.md index 48610fd..fa9ca87 100644 --- a/docs/native-embedding-architecture/dossier-info-api.md +++ b/docs/native-embedding-architecture/dossier-info-api.md @@ -1,11 +1,11 @@ --- -title: Getting dossier info via APIs -description: You can get dossier information, such as definition and visualization data, with Native Embedding SDK. +title: Getting dashboard info via APIs +description: You can get dashboard information, such as definition and visualization data, with Native Embedding SDK. --- -Filters can be applied both during the execution of an embedded dossier and after it has been rendered. After using [Native Embedding SDK](embed-multiple-viz.md) to load the dossier in a client's webpage, you can use the Native Embedding SDK to get the definition or data from the dossier. +Filters can be applied both during the execution of an embedded dashboard and after it has been rendered. After using [Native Embedding SDK](embed-multiple-viz.md) to load the dashboard in a client's webpage, you can use the Native Embedding SDK to get the definition or data from the dashboard. Let's say you already have `MstrEnvironment` and `MstrDossier` objects: @@ -14,7 +14,7 @@ try { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK }, }); const mstrDossier = await mstrEnvironment.loadDossier({ @@ -27,15 +27,15 @@ try { } ``` -## Get dossier definition +## Get dashboard definition -You can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to retrieve the definition of the dossier. +You can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to retrieve the definition of the dashboard. -| `getDossierDefinition()` | | -| ------------------------ | ---------------------------------- | -| Class | `MstrDossier` | -| Return Type | `Promise` | -| Description | Get the definition of the dossier. | +| `getDossierDefinition()` | | +| ------------------------ | ------------------------------------ | +| Class | `MstrDossier` | +| Return Type | `Promise` | +| Description | Get the definition of the dashboard. | ### `MstrDossier.getDossierDefinition` examples @@ -49,7 +49,7 @@ try { ```
- Example of the dossier definition in the resolved value: + Example of the dashboard definition in the resolved value: ```json { diff --git a/docs/native-embedding-architecture/embed-bot-visualizations.md b/docs/native-embedding-architecture/embed-bot-visualizations.md new file mode 100644 index 0000000..9350bdf --- /dev/null +++ b/docs/native-embedding-architecture/embed-bot-visualizations.md @@ -0,0 +1,149 @@ +--- +title: Embed multiple bot visualizations on a page +description: Embed multiple bot visualizations on a page +--- + + + +## Purpose + +You can use the Native Embedding SDK to embed multiple visualizations from a bot in a client's webpage, with high performance that is similar to loading one out-of-the-box Library dashboard page. + +## Requirements + +You must use the js bundle, `native-embedding-sdk.js`: + +```html + +``` + +## Example code + +### Embed visualizations from one bot + +To embed multiple visualizations from one dossier, after referring `native-embedding-sdk.js`, use the code shown below: +(please use `` character encoding tag) + +```html + + + + + + + + +
+
+ + + +``` + +### Destroy one visualization + +You can destroy one of these visualizations by calling `MstrBotVisualization.destroy()` API. For example, if you want to destroy the first visualization in the above code: + +```js +try { + // Follow the code above to get the array botVizList + await botVizList[0].destroy(); +} catch (error) { + // Add your own handling logic here +} +``` + +### Destroy visualizations from one bot + +You can destroy all the visualizations from a bot by calling `MstrBot.destroy()` API: + +```js +try { + // Follow the code above to get the mstrBot object + await mstrBot.destroy(); +} catch (error) { + // Add your own handling logic here +} +``` + +## References + +This piece of code contains a function from the following namespace and classes: + +- [`microstrategy.embeddingComponent.environments`](embedding-components.md) Namespace + + This namespace is responsible for creating and destroying `MstrEnvironment` objects. + +- [`MstrEnvironment`](mstr-environment.md) Class + + This class is the object returned from the `microstrategy.embeddingComponent.environments.create()` function, which is responsible for creating and destroying `MstrDossier` objects. + +- [`MstrBot`](mstr-bot.md) Class + + This class is returned from the `MstrEnvironment.loadBot()` function, which is responsible for showing bot visualizations in containers. diff --git a/docs/native-embedding-architecture/embed-multiple-viz.md b/docs/native-embedding-architecture/embed-multiple-viz.md index bd26d97..061b597 100644 --- a/docs/native-embedding-architecture/embed-multiple-viz.md +++ b/docs/native-embedding-architecture/embed-multiple-viz.md @@ -1,13 +1,13 @@ --- -title: Embed multiple visualizations on a page -description: Embed multiple visualizations on a page +title: Embed multiple dossier visualizations on a page +description: Embed multiple dossier visualizations on a page --- ## Purpose -You can use the Native Embedding SDK to embed multiple visualizations in a client's webpage, with high performance that is similar to loading one out-of-the-box Library dossier page. +You can use the Native Embedding SDK to embed multiple visualizations in a client's webpage, with high performance that is similar to loading one out-of-the-box Library dashboard page. Custom visualizations are also supported. To embed custom visualizations, you should deploy them on MicroStrategy Library first. To deploy custom visualizations on MicroStrategy Library, refer to [Deploy a custom visualization](https://www2.microstrategy.com/producthelp/Current/VisSDK/Content/topics/HTML5/Deploying_a_custom_visualization.htm). @@ -83,7 +83,7 @@ To embed multiple visualizations from one dossier, after referring `native-embed projectId: configs.projectId, objectId: configs.objectId, }); - // the viz keys can be obtained from dossier definition APIs: e.g.`GET /app/v2/dossier/{dossierId}/definition` + // the viz keys can be obtained from dashboard definition APIs: e.g.`GET /app/v2/dossier/{dossierId}/definition` await mstrDossier.refresh([ { key: "W1334", @@ -170,7 +170,7 @@ try { const environment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); const dossier = await environment.loadDossier({ @@ -223,7 +223,7 @@ async function loadVisualizationsFromDossiers() { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Embedding SDK. }, }); const projectId = "B19DEDCC11D4E0EFC000EB9495D0F44F"; @@ -288,9 +288,9 @@ After you embed multiple visualizations on a page, you can do some deeper manipu You can manipulate the chapter-level filters, on-page selectors, and visualizations used as filters via the Native Embedding SDK available since 2021 Update 9. -- [Getting dossier info via APIs](dossier-info-api.md) +- [Getting dashboard info via APIs](dossier-info-api.md) - You can use the Native Embedding SDK to get the definition or data from the dossier. + You can use the Native Embedding SDK to get the definition or data from the dashboard. ## References diff --git a/docs/native-embedding-architecture/embedding-components.md b/docs/native-embedding-architecture/embedding-components.md index 08247f3..1a9f186 100644 --- a/docs/native-embedding-architecture/embedding-components.md +++ b/docs/native-embedding-architecture/embedding-components.md @@ -35,7 +35,7 @@ try { const environment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); // Your own code diff --git a/docs/native-embedding-architecture/event-handling.md b/docs/native-embedding-architecture/event-handling.md index 554a1b4..8435193 100644 --- a/docs/native-embedding-architecture/event-handling.md +++ b/docs/native-embedding-architecture/event-handling.md @@ -14,7 +14,7 @@ try { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); const mstrDossier = await mstrEnvironment.loadDossier({ diff --git a/docs/native-embedding-architecture/mstr-bot-visualization.md b/docs/native-embedding-architecture/mstr-bot-visualization.md new file mode 100644 index 0000000..58523fc --- /dev/null +++ b/docs/native-embedding-architecture/mstr-bot-visualization.md @@ -0,0 +1,52 @@ +--- +title: MstrBotVisualization class +description: MstrBotVisualization class +--- + + + +The object returned from the `MstrBot.renderVisualization()` function, which allows access to the MicroStrategy bot visualization object. + +## APIs + +### The Destroy API + +#### Function + +`async destroy()` + +#### Input Parameters + +N/A + +#### Response + +This API returns a promise object that resolves to nothing. + +#### Example + +```js +try { + // Create bot object from the MstrEnvironment.loadBot() API + const environment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + getAuthToken: () => { + // Logic similar to the existing Native Embedding SDK. + }, + }); + // Begin here + const bot = await environment.loadBot({ + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "E9AB379D11EC92C1D9DC0080EFD415BB", + }); + const botViz = await bot.renderVisualization(dataId, document.getElementById("container")); + // do some other things... + await botViz.destroy(); +} catch (error) { + // Add your own handling logic here +} +``` + +#### API Errors + +N/A diff --git a/docs/native-embedding-architecture/mstr-bot.md b/docs/native-embedding-architecture/mstr-bot.md new file mode 100644 index 0000000..e2e8ea6 --- /dev/null +++ b/docs/native-embedding-architecture/mstr-bot.md @@ -0,0 +1,167 @@ +--- +title: MstrBot class +description: MstrBot class +--- + + + +The object returned from the `MstrEnvironment.loadBot()` function, which allows access to the MicroStrategy bot object. + +## APIs + +### The Get Questions API + +#### Function + +`async getQuestions()` + +#### Input Parameters + +N/A + +#### Response + +This API returns a promise object that resolves to the result of GET `/api/bots/{botId}/questions` API. A data sample is like this: + +
+ Example of the questions in the resolved value: + +```json +{ + "questions": [ + { + "id": "D0AEE8DB0BE7471E8CA3FCAF412DB096", + "text": "List all orders from the call center", + "answers": [ + { + "text": "The customer with the highest revenue is Simonetti with a total revenue of $11,619.", + "type": "markdown" + } + ], + "creationDate": "2024-01-05T06:36:36.755+0000" + }, + { + "id": "D0AEE8DB0BE7471E8CA3FCAF412DB097", + "text": "List all orders from the call center", + "answers": [ + { + "text": "The customer with the highest revenue is Simonetti with a total revenue of $11,619.", + "type": "visualization", + "data": { + "id": "A9D9247C28FB4708B8F8E4D81D192ED8" + } + } + ], + "creationDate": "2024-01-05T06:36:36.755+0000" + } + ] +} +``` + +
+ +#### Example + +```js +try { + const environment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + getAuthToken: () => { + // Logic similar to the existing Native Embedding SDK. + }, + }); + // Begin here + const bot = await environment.loadBot({ + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "E9AB379D11EC92C1D9DC0080EFD415BB", + }); + const questions = await bot.getQuestions(); +} catch (error) { + // Your own error handling logic +} +``` + +#### API Errors + +| Error Case | Error Category | Handling Module | Error Handling | +| --------------- | -------------- | -------------------- | --------------------------------------------- | +| REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | + +### The Render Visualization API + +#### Function + +`async renderVisualization(dataId, container)` + +#### Input Parameters + +| Parameter Name | Data Type | Description | Is Required | +| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| dataId | String | The data cache id. Could be got from `getQuestions()` API. | true | +| container | HTMLElement | The HTML element used for displaying the visualization. The HTML element must be in the current DOM tree of the client’s page. All elements must exist and cannot be in iframes. The `Node.contains()` function is used to determine this and is compatible with all browsers. | true | + +#### Response + +This API returns a promise object that resolves to nothing. + +#### Example + +```js +try { + const environment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + getAuthToken: () => { + // Logic similar to the existing Native Embedding SDK. + }, + }); + // Begin here + const bot = await environment.loadBot({ + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "E9AB379D11EC92C1D9DC0080EFD415BB", + }); + // Get data id from the result of this API + const questions = await bot.getQuestions(); + const botViz = await bot.renderVisualization(dataId, document.getElementById("container")); +} catch (error) { + // Your own error handling logic +} +``` + +#### API Errors + +| Error Case | Error Category | Handling Module | Error Handling | +| -------------------------------------------------------- | -------------- | -------------------- | --------------------------------------------- | +| The input parameter fails input validation | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| data id isn't a valid data cache id | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| The container isn’t a valid HTML element in the DOM tree | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| A container has children | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | + +### The Destroy API + +#### Function + +`async destroy()` + +#### Input Parameters + +N/A + +#### Response + +This API returns a promise object that resolves to nothing. + +#### Example + +```js +try { + // Create bot object from the MstrEnvironment.loadBot() API + await bot.destry(); +} catch (error) { + // Add your own handling logic here +} +``` + +#### API Errors + +N/A | diff --git a/docs/native-embedding-architecture/mstr-dossier.md b/docs/native-embedding-architecture/mstr-dossier.md index 6103fe7..d68947c 100644 --- a/docs/native-embedding-architecture/mstr-dossier.md +++ b/docs/native-embedding-architecture/mstr-dossier.md @@ -5,7 +5,7 @@ description: MstrDossier class -The object returned from the `MstrEnvironment.loadDossier()` function, which allows access to the MicroStrategy dossier object. +The object returned from the `MstrEnvironment.loadDossier()` function, which allows access to the MicroStrategy dashboard object. ## APIs @@ -34,7 +34,7 @@ try { const environment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); const dossier = await environment.loadDossier({ @@ -62,13 +62,13 @@ try { | The input parameter fails input validation | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | The user wants to show more than one visualization in one container in input params | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | The user wants to show one visualization in multiple containers | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | -| Visualization key isn't a valid visualization key in the dossier | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| Visualization key isn't a valid visualization key in the dashboard | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | The container isn’t a valid HTML element in the DOM tree | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | A container has children that are not shown in the visualization | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | A container is occupied by other dossiers | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | | The key is the visualization key of the visualization in the panel | Invalid input | Native Embedding SDK | console err message in console "The visualization `${VisualizationKey}` is a visualization in a panel, which isn't supported." | -### The get infomation API +### The get information API -You can see the API at the [Getting dossier info via APIs document](dossier-info-api) +You can see the API at the [Getting dashboard info via APIs document](dossier-info-api) diff --git a/docs/native-embedding-architecture/mstr-environment.md b/docs/native-embedding-architecture/mstr-environment.md index ee93b01..09a5e48 100644 --- a/docs/native-embedding-architecture/mstr-environment.md +++ b/docs/native-embedding-architecture/mstr-environment.md @@ -9,7 +9,7 @@ The instance of this class is the object returned from the `microstrategy.embedd ## APIs -### The load dossier API +### The load dashboard API #### Function @@ -17,13 +17,13 @@ The instance of this class is the object returned from the `microstrategy.embedd #### Input Parameters -| Parameter Name | Data Type | Description | Is Required | -| ---------------- | --------- | ------------------------------------------------------------------------------------------------ | ----------- | -| props.projectId | String | The project ID, which must be a GUID. | true | -| props.objectId | String | The dossier ID, which must be valid. If the ID is a document or report ID, an error is reported. | true | -| props.instanceId | String | The dossier instance ID, if it already exists. | false | +| Parameter Name | Data Type | Description | Is Required | +| ---------------- | --------- | -------------------------------------------------------------------------------------------------------- | ----------- | +| props.projectId | String | The project ID, which must be a GUID. | true | +| props.objectId | String | The dashboard ID, which must be valid. If the ID is a document, report, or bot ID, an error is reported. | true | +| props.instanceId | String | The dashboard instance ID, if it already exists. | false | -The `projectId` + `objectId` is used as the dossier identifier. If the function is called twice with the same parameter, the same `MstrDossier` object is returned in the callback. +The `projectId` + `objectId` is used as the dashboard identifier. If the function is called twice with the same parameter, the same `MstrDossier` object is returned in the callback. #### Response @@ -36,7 +36,7 @@ try { const environment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); // Begin here @@ -56,7 +56,7 @@ try { | The input parameter fails input validation | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | | Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | -### The destroy dossier API +### The destroy dashboard API #### Function @@ -85,6 +85,52 @@ try { #### API Errors -| Error Case | Error Category | Handling Module | Error Handling | -| ------------------------------------------------ | -------------- | -------------------- | --------------------------------------------- | -| The input parameter isn’t a valid dossier object | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| Error Case | Error Category | Handling Module | Error Handling | +| -------------------------------------------------- | -------------- | -------------------- | --------------------------------------------- | +| The input parameter isn’t a valid dashboard object | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | + +### The load bot API + +#### Function + +`async loadBot(props)` + +#### Input Parameters + +| Parameter Name | Data Type | Description | Is Required | +| --------------- | --------- | ------------------------------------------------------------------------------------------------------- | ----------- | +| props.projectId | String | The project ID, which must be a GUID. | true | +| props.objectId | String | The bot ID, which must be valid. If the ID is a dashboard, document or report ID, an error is reported. | true | + +The `projectId` + `objectId` is used as the bot identifier. If the function is called twice with the same parameter, the same `MstrBot` object is returned in the callback. + +#### Response + +This API returns a promise object that resolves to a `MstrBot` object. + +#### Example + +```js +try { + const environment = await microstrategy.embeddingComponent.environments.create({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + getAuthToken: () => { + // Logic similar to the existing Native Embedding SDK. + }, + }); + // Begin here + const bot = await environment.loadBot({ + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "E9AB379D11EC92C1D9DC0080EFD415BB", + }); +} catch (error) { + // Your own error handling logic +} +``` + +#### API Errors + +| Error Case | Error Category | Handling Module | Error Handling | +| ------------------------------------------ | -------------- | -------------------- | --------------------------------------------- | +| The input parameter fails input validation | Invalid input | Native Embedding SDK | Caught by the `catch()` of the promise object | +| Other REST API errors | Other | Native Embedding SDK | Caught by the `catch()` of the promise object | diff --git a/docs/native-embedding-architecture/vis-manipulation.md b/docs/native-embedding-architecture/vis-manipulation.md index ce97e97..7523f34 100644 --- a/docs/native-embedding-architecture/vis-manipulation.md +++ b/docs/native-embedding-architecture/vis-manipulation.md @@ -5,7 +5,7 @@ description: You can do manipulation on the embedded visualizations after they h -The embedded visualizations can be manipulated the same way as they are seen on MicroStrategy Library dossier pages. +The embedded visualizations can be manipulated the same way as they are seen on MicroStrategy Library dashboard pages. Currently, the supported manipulation types include element selection inside a visualization, actions inside the right-click menu, and actions triggered by clicking, dragging, and scrolling inside a visualization @@ -16,7 +16,7 @@ try { const mstrEnvironment = await microstrategy.embeddingComponent.environments.create({ serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", getAuthToken: () => { - // Logic similar to the existing Native Embedding SDK, but only standard auth login is allowed + // Logic similar to the existing Native Embedding SDK. }, }); const mstrDossier = await mstrEnvironment.loadDossier({ diff --git a/docs/playground.md b/docs/playground.md index c97b394..3ca5933 100644 --- a/docs/playground.md +++ b/docs/playground.md @@ -19,16 +19,16 @@ Here are some examples in the gallery so far. | Example | Use Case | | :------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Simple Dossier Example](https://microstrategy.github.io/playground/?example=g1) | How to embed a dossier. | -| [Minimal Template](https://microstrategy.github.io/playground/?example=g2) | A template for the least amount code needed to embed a dossier. | +| [Simple Dashboard Example](https://microstrategy.github.io/playground/?example=g1) | How to embed a dashboard. | +| [Minimal Template](https://microstrategy.github.io/playground/?example=g2) | A template for the least amount code needed to embed a dashboard. | | [Responsive Height](https://microstrategy.github.io/playground/?example=g3) | JavaScript code to make the height responsive. | -| [Dossier in Full Screen](https://microstrategy.github.io/playground/?example=g4) | How to show embedded dossier in full screen. | -| [Inter-dossier interaction](https://microstrategy.github.io/playground/?example=g5) | Interaction between embedded dossier. One dossier filters another. | +| [Dashboard in Full Screen](https://microstrategy.github.io/playground/?example=g4) | How to show embedded dashboard in full screen. | +| [Inter-dashboard interaction](https://microstrategy.github.io/playground/?example=g5) | Interaction between embedded dashboard. One dashboard filters another. | | [Filters](https://microstrategy.github.io/playground/?example=g6) | Various examples to show how to use filter-related API. It covers attribute selector filter, attribute search, attribute slider, calendar, metric qualification filters, etc. | | [Page Navigation](https://microstrategy.github.io/playground/?example=g14) | How to use page navigation API. | | [Single Visualization](https://microstrategy.github.io/playground/?example=g15) | How to embed a single visualization. | -| [Authoring](https://microstrategy.github.io/playground/?example=g16) | How to embed dossier in authoring mode. | +| [Authoring](https://microstrategy.github.io/playground/?example=g16) | How to embed dashboard in authoring mode. | | [Standard Authentication](https://microstrategy.github.io/playground/?example=g17) | How to implement standard authentication. | -| [Export to Excel or PDF](https://microstrategy.github.io/playground/?example=g18) | How to export dossier to excel or PDF. | +| [Export to Excel or PDF](https://microstrategy.github.io/playground/?example=g18) | How to export dashboard to excel or PDF. | | [Prompts](https://microstrategy.github.io/playground/?example=g20) | Various examples to show how to answer prompts. | | [Interact with Panel Stacks](https://microstrategy.github.io/playground/?example=g23) | How to use panel-related API. | diff --git a/docs/support-for-different-authentication-environments/authentication-saml.md b/docs/support-for-different-authentication-environments/authentication-saml.md index 6fa4e11..6f48d03 100644 --- a/docs/support-for-different-authentication-environments/authentication-saml.md +++ b/docs/support-for-different-authentication-environments/authentication-saml.md @@ -1,9 +1,9 @@ --- title: Use SAML or OIDC authentication -description: The example in this topic illustrates how to display an embedded dossier using SAML authentication. The same code works for OIDC except the `loginMode` parameter. +description: The example in this topic illustrates how to display an embedded dashboard using SAML authentication. The same code works for OIDC except the `loginMode` parameter. --- -The example in this topic illustrates how to display an embedded dossier using SAML authentication. The same code works for OIDC except the `loginMode` parameter. +The example in this topic illustrates how to display an embedded dashboard using SAML authentication. The same code works for OIDC except the `loginMode` parameter. A live example can be seen on [GitHub](https://microstrategy.github.io/embedding-sdk-samples/feature_showcase/4_Use_SAML.html). Also check out [other examples](https://microstrategy.github.io/embedding-sdk-samples/). diff --git a/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md b/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md index 8251e11..6cc9f67 100644 --- a/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md +++ b/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md @@ -1,13 +1,13 @@ --- title: Use guest authentication -description: The example in this topic illustrates how to seamlessly display an embedded dossier using Guest authentication when Guest is the only authentication mode that is enabled. +description: The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest authentication when Guest is the only authentication mode that is enabled. --- -The Embedding SDK allows you to quickly integrate dossiers into a web application in a responsive manner. The code required for the dossier to be displayed without requesting credentials depends on the how authentication is configured for the environment where the embedded dossier is hosted. The example in this topic illustrates how to seamlessly display an embedded dossier using Guest authentication when Guest is the only authentication mode that is enabled. +The Embedding SDK allows you to quickly integrate dossiers into a web application in a responsive manner. The code required for the dashboard to be displayed without requesting credentials depends on the how authentication is configured for the environment where the embedded dashboard is hosted. The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest authentication when Guest is the only authentication mode that is enabled. -To help you get started, we have provided [a live example](https://microstrategy.github.io/playground/?example=g2) in the [Embedding SDK Playground](https://microstrategy.github.io/playground/). By design, the code in this example only shows how to embed a dossier and nothing else, and it embeds an existing dossier from the MicroStrategy Library demo site, which has only Guest authentication enabled. +To help you get started, we have provided [a live example](https://microstrategy.github.io/playground/?example=g2) in the [Embedding SDK Playground](https://microstrategy.github.io/playground/). By design, the code in this example only shows how to embed a dashboard and nothing else, and it embeds an existing dashboard from the MicroStrategy Library demo site, which has only Guest authentication enabled. -We have provided simple instructions and code snippets to help you configure the example to use a dossier from your MicroStrategy Library Server. If you customize the example, however, you must configure your Library Server to support only Guest authentication. +We have provided simple instructions and code snippets to help you configure the example to use a dashboard from your MicroStrategy Library Server. If you customize the example, however, you must configure your Library Server to support only Guest authentication. Please also check out the examples in [Embedding SDK Playground](https://microstrategy.github.io/playground/) from the "Start over" button and [https://microstrategy.github.io/embedding-sdk-samples](https://microstrategy.github.io/embedding-sdk-samples). @@ -26,8 +26,8 @@ Please also check out the examples in [Embedding SDK Playground](https://microst