diff --git a/docs/add-functionality/add-event.md b/docs/add-functionality/add-event.md index 6b04ae6..4d84c8e 100644 --- a/docs/add-functionality/add-event.md +++ b/docs/add-functionality/add-event.md @@ -429,6 +429,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 diff --git a/docs/add-functionality/authoring-library.md b/docs/add-functionality/authoring-library.md index 080a451..f78a8ba 100644 --- a/docs/add-functionality/authoring-library.md +++ b/docs/add-functionality/authoring-library.md @@ -66,17 +66,16 @@ The existing parameters can be roughly divided into three categories and their b - 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. -| Field Name | Description | -| ----------------------------- | --------------------------------------------------------------------------------------------------------- | -| instance | An existing instance injected to the embedding SDK that is used for pre-handlings, like an answer prompt. | -| 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 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. | If you have set values for these fields when setting `dossierRenderingMode = authoring`, a dialog appears with the error message: ```text -The fields ["instance", "filters", "visualizationAppearances", "visualizationSelectedElements"] are not allowed to be used when "dossierRenderingMode" is "authoring". Please remove these forbidden fields and try again. +The fields ["filters", "visualizationAppearances", "visualizationSelectedElements"] are not allowed to be used when "dossierRenderingMode" is "authoring". Please remove these forbidden fields and try again. ``` ## Embedding SDK APIs and examples @@ -125,12 +124,12 @@ microstrategy.dossier When an error occurs, this API returns a promise object that in turn returns an error object in rejected cases. -| Error Case | Error Category | Handling Module | Error Handling | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------- | --------------------------------------------- | -| The dossierRenderingMode parameter has the wrong input type. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | -| The dossierRenderingMode parameter is neither “consumption“ nor “authoring“. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | -| A required parameter is missed or it is not in the correct format. | Invalid input in the unsupported case | Web Dossier | Caught by error handler. | -| The unsupported fields in the authoring mode include: | Unsupported case | Embedded SDK | Display an error message and an alert dialog. | +| Error Case | Error Category | Handling Module | Error Handling | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------- | --------------------------------------------- | +| The dossierRenderingMode parameter has the wrong input type. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | +| The dossierRenderingMode parameter is neither “consumption“ nor “authoring“. | Invalid input | Embedded SDK | Display an error message and an alert dialog. | +| A required parameter is missed or it is not in the correct format. | Invalid input in the unsupported case | Web Dossier | Caught by error handler. | +| The unsupported fields in the authoring mode include: | Unsupported case | Embedded SDK | Display an error message and an alert dialog. | ### API for switching to authoring mode @@ -256,11 +255,11 @@ microstrategy.dossier #### Input parameters -| Parameter Names | Data Type | Default Value | Description | Required? | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | ---------------------------------------------------------------------- | --------- | -| props.authoring.menubar.library.visible | Boolean | true | Show or hide corresponding Library home button in the authoring UI. | No | -| 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.insertSurvey.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 | +| Parameter Names | Data Type | Default Value | Description | Required? | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------- | ---------------------------------------------------------------------- | --------- | +| props.authoring.menubar.library.visible | Boolean | true | Show or hide corresponding Library home button in the authoring UI. | No | +| 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. diff --git a/docs/add-functionality/methods-and-properties.md b/docs/add-functionality/methods-and-properties.md index bfd720d..8321c6d 100644 --- a/docs/add-functionality/methods-and-properties.md +++ b/docs/add-functionality/methods-and-properties.md @@ -65,19 +65,21 @@ Yes No -### `url`, `serverURL`, `applicationID`, `objectID`, and `pageKey` +### `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: 1. Use the `url` property to specify a full URL. -1. Use `serverURL`, `applicationID`, `objectID`, and `pageKey` properties. Embedding SDK will build the URL using: `serverURL` + '/app/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`. +1. Use `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` properties. +1. If the `configAppId` property is not provided, embedding SDK will build the URL using: `serverURL` + '/app/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`. +1. Otherwise the URL will be: `serverURL` + '/app/' + 'config/' + `configAppId` + '/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`. #### Required? One of the following is required: - `url` is required. -- `serverURL`, `applicationID`, and `objectID` are required, while `pageKey` is optional. +- `serverURL`, `applicationID`, and `objectID` are required, while `pageKey`, `configAppId` is optional. #### Default value diff --git a/docs/embed-library-main-page/embed-library-properties.md b/docs/embed-library-main-page/embed-library-properties.md index baa9f4c..248b5c7 100644 --- a/docs/embed-library-main-page/embed-library-properties.md +++ b/docs/embed-library-main-page/embed-library-properties.md @@ -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/native-embedding-architecture/embed-multiple-viz.md b/docs/native-embedding-architecture/embed-multiple-viz.md index 8281316..2475a04 100644 --- a/docs/native-embedding-architecture/embed-multiple-viz.md +++ b/docs/native-embedding-architecture/embed-multiple-viz.md @@ -29,55 +29,78 @@ The js bundle is also in the web-dossier war, in the same directory as `embeddin ### Embed visualizations from one dossier To embed multiple visualizations from one dossier, after referring `native-embedding-sdk.js`, use the code shown below: +(please use `` character encoding tag) -```js -try { - const environment = await microstrategy.embeddingComponent.environments.create({ - serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", - // The following function is the default implementation. User can provide custom implementation. - // Only support standard authentication now. - getAuthToken() { - return fetch("https://{host}:{port}/{Library}/api/auth/login", { - method: "POST", - credentials: "include", // including cookie - mode: "cors", // setting as CORS mode for cross origin - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - loginMode: 1, // Standard mode - username: "input your username", - password: "input your password", - }), - }) - .then((response) => { - if (response && response.ok) { - return response.headers.get("X-MSTR-authToken"); - } - throw Error("Failed to fetch auth token."); - }) - .catch((error) => { - console.log("Error:", error); - }); - }, - }); - const dossier = await environment.loadDossier({ - projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", - objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", - }); - - await dossier.refresh([ - { - key: "K66", - container: document.getElementById("container1"), - }, - { - key: "K52", - container: document.getElementById("container2"), - }, - ]); - // Your own code after the visualizations are all loaded -} catch (error) { - // Your own error handling code -} +```html + + + + + + + + +
+
+ + + ``` `applicationType` must be unset or equal to `35`. Because the implementation of Native Embedding SDK is based on login as a Library user, which uses the param of `applicationType:35`. diff --git a/docs/whats-new-in-the-embedding-sdk.md b/docs/whats-new-in-the-embedding-sdk.md index ea79895..ed4d238 100644 --- a/docs/whats-new-in-the-embedding-sdk.md +++ b/docs/whats-new-in-the-embedding-sdk.md @@ -5,6 +5,10 @@ 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. +## 2021 Update 11(September 2023) + +- [Event handlers added to Library for; item selection, and menu selection.](./add-functionality/add-event.md) + ## 2021 Update 9 (May 2023) [Native Embedding SDK](./native-embedding-architecture/native-embedding-architecture.md)