diff --git a/docs/add-functionality/authoring-library.md b/docs/add-functionality/authoring-library.md index 938cd39..6f8a8c5 100644 --- a/docs/add-functionality/authoring-library.md +++ b/docs/add-functionality/authoring-library.md @@ -90,9 +90,12 @@ The fields ["filters", "visualizationAppearances", "visualizationSelectedElement 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? | -| -------------------------- | --------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -| props.dossierRenderingMode | String | consumption | ["consumption", "authoring"] | The value is either `consumption` or `authoring`.
If it is `authoring` and the configuration `feature.dossier.authoring` isn't set, or its value isn't `true`, then an error is returned. | No | +| Parameter Name | Data Type | Default Value | Available Values | Description | Required? | +| -------------------------- | --------------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| props.dossierRenderingMode | string | consumption | ["consumption", "authoring"] | The value is either `consumption` or `authoring`.
If it is `authoring` and the configuration `feature.dossier.authoring` isn't set, or its value isn't `true`, then an error is returned. | No | +| props.newDossier | boolean | false | [true, false] | If the value is true, the Embedding SDK will embed a new dossier authoring page. | No | +| props.newDossierDatasetIds | Array\ | N/A | The valid dataset IDs | When `newDossier` is `true`, the user can use this parameter to specify the datasets that are used to create the new dossier. | No | +| props.authoringPauseMode | boolean | false | [true, false] | If the value is true, the Embedding SDK will embed a dossier authoring page on pause mode. | No | Example: @@ -100,6 +103,9 @@ Example: microstrategy.dossier.create({ // ... dossierRenderingMode: "authoring", + newDossier: true, + newDossierDatasetIds: ["E26BF608B14F1EA61086F3A61034AE21"], + authoringPauseMode: false, }); ``` diff --git a/docs/embedding-context/gotopage-improve-performance.md b/docs/embedding-context/gotopage-improve-performance.md new file mode 100644 index 0000000..7125b15 --- /dev/null +++ b/docs/embedding-context/gotopage-improve-performance.md @@ -0,0 +1,65 @@ +--- +title: Improve embedding dossier page's performance +description: Describes how to use goToPage() API to enhance the performance in some specific scenarios. +--- + +This page introduces a method to improve the embedding performance in a specific case. + +## The performance problem in a specific case + +Sometimes the user may use a special web page layout like this: + +![specialLayout](../images/special_embed_case.png) + +On this web page, the left side is a dossier list, and the right side is a embedded dossier page. The dossier list might be fetched through some REST APIs like `GET /api/searches/results`, and the embedded dossier is normally rendered by calling the Embedding SDK API like `microstrategy.embeddingContexts.embedDossierConsumptionPage()`. When the user changes his selection on the left dossier list, the right side's embedded dossier will also change by calling `microstrategy.embeddingContexts.embedDossierConsumptionPage()` with new dossier id again in the same container. + +It's similar as the process that the user first go to the Library homepage, then clicks a dossier item to enter the dossier page. However, if you simply write the program like this: + +```javascript +// Assume the parameters can be passed to this function after the user click +async function onDossierListClicked({serverUrl, projectId, dossierId}) { + await microstrategy.embeddingContexts.embedDossierConsumptionPage({ + serverUrl, + projectId, + objectId: dossierId, + placeholder: document.getElementById("dossier-container"), + ... + }); +} +``` + +You will see sometimes the embedded dossier page will be loaded slower than entering the dossier page from the homepage on Library Web. + +That's because the `microstrategy.embeddingContexts.embedDossierConsumptionPage()` API call on the same container will destroy the original iframe and create a new one. So its loading is like open the dossier in a new browser tab, in which we need to fetch all the resources, including the static resources and REST API result again. However, when the user enters the dossier page from homepage on Library Web, all these resources are cached and Library Web doesn't need to load them repeatedly. + +## A better solution: Use `goToPage()` + +To improve the performance of this use case and gain the similar performance as entering dossier pages from the Library homepage, we recommend you use the [EmbeddingContext.goToPage()](../embedding-context/#gotopagepageinfo) API like this: + +```javascript +let containerIdToContext = {}; +// If necessary, the user can also create instance by himself and pass the instance Id here +async function onDossierListClicked({serverUrl, projectId, dossierId, instanceId}) { + const containerId = "dossier-container"; + let embeddingContext; + if (containerIdToContext[containerId]) { + embeddingContext = containerIdToContext[containerId]; + await embeddingContext.goToPage({ + projectId, + objectId: dossierId, + instanceId, + }); + } else { + embeddingContext = await microstrategy.embeddingContexts.embedDossierConsumptionPage({ + serverUrl, + projectId, + objectId: dossierId, + placeholder: document.getElementById(containerId), + ... + }); + containerIdToContext[containerId] = embeddingContext; + } +} +``` + +In this case, the `embeddingContext` can be retained, and the `goToPage()` call is similar as a simple redirect on the Library Web. So it has the similar performance as entering the dossier page from homepage on Library. diff --git a/docs/images/special_embed_case.png b/docs/images/special_embed_case.png new file mode 100644 index 0000000..a3a2340 Binary files /dev/null and b/docs/images/special_embed_case.png differ diff --git a/docs/native-embedding-architecture/apply-filter.md b/docs/native-embedding-architecture/apply-filter.md index c296d5f..26cb03e 100644 --- a/docs/native-embedding-architecture/apply-filter.md +++ b/docs/native-embedding-architecture/apply-filter.md @@ -76,10 +76,10 @@ 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 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. +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()` or `MstrDossier.applyFilters()` function to manipulate it. :::note -For filters and selectors, we currently only support manipulating the selector type of the attribute element list. +The `applyFilter()` or `applyFilters()` functions will first call REST API to apply filter on the current dossier instance, then **refresh the affected visualizations automatically**. ::: | `applyFilter()` | | diff --git a/docs/whats-new-in-the-embedding-sdk.md b/docs/whats-new-in-the-embedding-sdk.md index b77e894..cfdf75f 100644 --- a/docs/whats-new-in-the-embedding-sdk.md +++ b/docs/whats-new-in-the-embedding-sdk.md @@ -5,6 +5,11 @@ description: In each release, changes are made to make the MicroStrategy SDK mor In each release, changes are made to make the MicroStrategy SDK more powerful and easier to use. +## Strategy ONE September 2025 + +- [Support dataset ids and pause mode in embedded authoring](./add-functionality/authoring-library#api-for-entering-authoring-mode-or-disabling-authoring-mode-in-the-initial-loading) + - Support to input dataset ids when embedding a new dossier authoring page, and set pause mode in the API `microstrategy.dossier.create()` in iframe Embedding SDK. + ## Strategy ONE August 2025 - [Support Dashboard Instance Id in goToPage()](./embedding-context/#gotopagepageinfo) diff --git a/sidebars.js b/sidebars.js index 6f4d256..764ab12 100644 --- a/sidebars.js +++ b/sidebars.js @@ -119,6 +119,7 @@ const sidebars = { "embedding-context/document-consumption-page-apis", "embedding-context/dossier-consumption-page-apis", "embedding-context/bot-consumption-page-apis", + "embedding-context/gotopage-improve-performance", ], }, {