diff --git a/.eslintrc.yml b/.eslintrc.yml index b72ff95..4a6ed7b 100644 --- a/.eslintrc.yml +++ b/.eslintrc.yml @@ -4,9 +4,9 @@ env: es2022: true node: true extends: - - 'airbnb-base' - - 'plugin:markdown/recommended' - - 'prettier' + - "airbnb-base" + - "plugin:markdown/recommended" + - "prettier" plugins: - markdown - prettier @@ -15,10 +15,10 @@ parserOptions: ecmaVersion: 13 overrides: - files: - - "**/*.md" + - "**/*.md" processor: "markdown/markdown" - files: - - '**/*.md/*.{js}' + - "**/*.md/*.{js}" parserOptions: ecmaFeatures: impliedStrict: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f6c21e3..6ecdc2c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,7 +13,8 @@ - [ ] My changes rendered as expected by running `yarn start`. -- [ ] My changes followed the [style guide](https://github.com/MicroStrategy/embedding-sdk-docs/blob/public/contributing/content-style-guide.md). +- [ ] My changes followed the + [style guide](https://github.com/MicroStrategy/embedding-sdk-docs/blob/public/contributing/content-style-guide.md). - [ ] I have self-reviewed this PR. - [ ] I have performed a syntax validation check to avoid syntax errors. diff --git a/.lintstagedrc b/.lintstagedrc index 8e5ac57..17e0caf 100644 --- a/.lintstagedrc +++ b/.lintstagedrc @@ -4,8 +4,5 @@ "yarn prettier --list-different --config ./.prettiermarkdownrc", "yarn markdownlint" ], - "*.js": [ - "yarn eslint --quiet", - "yarn prettier --list-different --config ./.prettierrc" - ] -} \ No newline at end of file + "*.js": ["yarn eslint --quiet", "yarn prettier --list-different --config ./.prettierrc"] +} diff --git a/.markdownlint.yml b/.markdownlint.yml index d0ead04..011e60b 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -171,7 +171,20 @@ MD032: true # MD033/no-inline-html - Inline HTML MD033: # Allowed elements - allowed_elements: ["br", "pre", "a", "iframe", "blockquote", "ul", "li", "details", "summary", "Available", "Deprecated"] + allowed_elements: + [ + "br", + "pre", + "a", + "iframe", + "blockquote", + "ul", + "li", + "details", + "summary", + "Available", + "Deprecated", + ] # MD034/no-bare-urls - Bare URL used MD034: true @@ -239,4 +252,4 @@ MD047: true # MD048/code-fence-style - Code fence style MD048: # Code fence style - style: "backtick" \ No newline at end of file + style: "backtick" diff --git a/.prettierrc b/.prettierrc index 4359419..ae85ef1 100644 --- a/.prettierrc +++ b/.prettierrc @@ -15,4 +15,4 @@ "trailingComma": "es5", "useTabs": false, "vueIndentScriptAndStyle": false -} \ No newline at end of file +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 527edc7..e4c9bc6 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -4,9 +4,14 @@ ## Our Pledge -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in our community a +harassment-free experience for everyone, regardless of age, body size, visible or invisible +disability, ethnicity, sex characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, religion, or sexual +identity and orientation. -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and +healthy community. ## Our Standards @@ -15,7 +20,8 @@ Examples of behavior that contributes to a positive environment for our communit - Demonstrating empathy and kindness toward other people - Being respectful of differing opinions, viewpoints, and experiences - Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the + experience - Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: @@ -23,60 +29,89 @@ Examples of unacceptable behavior include: - The use of sexualized language or imagery, and sexual attention or advances of any kind - Trolling, insulting or derogatory comments, and personal or political attacks - Public or private harassment -- Publishing others' private information, such as a physical or email address, without their explicit permission -- Contacting individual members, contributors, or leaders privately, outside designated community mechanisms, without their explicit permission +- Publishing others' private information, such as a physical or email address, without their + explicit permission +- Contacting individual members, contributors, or leaders privately, outside designated community + mechanisms, without their explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior +and will take appropriate and fair corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, +code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and +will communicate reasons for moderation decisions when appropriate. ## Scope -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. +This Code of Conduct applies within all community spaces, and also applies when an individual is +officially representing the community in public spaces. Examples of representing our community +include using an official e-mail address, posting via an official social media account, or acting as +an appointed representative at an online or offline event. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at opensource@microstrategy.com. All complaints will be reviewed and investigated promptly and fairly. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community +leaders responsible for enforcement at [opensource@microstrategy.com](mailto:opensource@microstrategy.com). All complaints will be reviewed +and investigated promptly and fairly. -All community leaders are obligated to respect the privacy and security of the reporter of any incident. +All community leaders are obligated to respect the privacy and security of the reporter of any +incident. ## Enforcement Guidelines -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: +Community leaders will follow these Community Impact Guidelines in determining the consequences for +any action they deem in violation of this Code of Conduct: ### 1. Correction -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or +unwelcome in the community. -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. +**Consequence**: A private, written warning from community leaders, providing clarity around the +nature of the violation and an explanation of why the behavior was inappropriate. A public apology +may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. +**Consequence**: A warning with consequences for continued behavior. No interaction with the people +involved, including unsolicited interaction with those enforcing the Code of Conduct, for a +specified period of time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. +**Community Impact**: A serious violation of community standards, including sustained inappropriate +behavior. -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. +**Consequence**: A temporary ban from any sort of interaction or public communication with the +community for a specified period of time. No public or private interaction with the people involved, +including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this +period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. +**Community Impact**: Demonstrating a pattern of violation of community standards, including +sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement +of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at . +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at +. -Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org -For answers to common questions about this code of conduct, see the FAQ at . Translations are available at . +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31c63c7..fdf1759 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,63 +10,83 @@ - [Open a pull request](#open-a-pull-request) - [Submit your PR & get it reviewed](#submit-your-pr--get-it-reviewed) - [Your PR is merged](#your-pr-is-merged) - - [Keep contributing as you use MicroStrategy Docs](#keep-contributing-as-you-use-microstrategy-docs) + - [Keep contributing as you use Strategy Docs](#keep-contributing-as-you-use-strategy-docs) ## Getting started Before you begin: - Have you read the [code of conduct](CODE_OF_CONDUCT.md)? -- Check out the [existing issues](https://github.com/MicroStrategy/embedding-sdk-docs/issues) & see if we [accept contributions](#memo-types-of-contributions) for your type of issue. +- Check out the [existing issues](https://github.com/MicroStrategy/embedding-sdk-docs/issues) & see + if we [accept contributions](#memo-types-of-contributions) for your type of issue. ### Use the 'Edit' button -Navigating a new codebase can be challenging, so we're making that a little easier. As you're using this MicroStrategy Embedding SDK Docs, you may come across an article that you want to make an update to. You can find and click the **Edit** button on the top right corner on that article, which will take you to the file in this repo where you'll make your changes. +Navigating a new codebase can be challenging, so we're making that a little easier. As you're using +this Strategy Embedding SDK Docs, you may come across an article that you want to make an update to. +You can find and click the **Edit** button on the top right corner on that article, which will take +you to the file in this repo where you'll make your changes. -Before you make your changes, check to see if an [issue exists](https://github.com/MicroStrategy/embedding-sdk-docs/issues) already for the change you want to make. +Before you make your changes, check to see if an +[issue exists](https://github.com/MicroStrategy/embedding-sdk-docs/issues) already for the change +you want to make. ### Don't see your issue? Open one -If you spot something new, open an issue [here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). We'll use the issue to have a conversation about the problem you want to fix. +If you spot something new, open an issue +[here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). We'll use the issue to have a +conversation about the problem you want to fix. ### Ready to make a change? Fork the repo -:warning: Please do not use the "Add file" or directly edit the file and create PR on GitHub. It is recommended to clone the forked repo to local and then modify. In this way, you can leverage the linters provided by us to fix some styling issues or typos. +:warning: Please do not use the "Add file" or directly edit the file and create PR on GitHub. It is +recommended to clone the forked repo to local and then modify. In this way, you can leverage the +linters provided by us to fix some styling issues or typos. Fork using the command line: -- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them. +- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) + so that you can make your changes without affecting the original project until you're ready to + merge them. Fork using GitHub Desktop: -- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop. -- Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)! +- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) + will guide you through setting up Desktop. +- Once Desktop is set up, you can use it to + [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)! ### Make your update -Make your changes to the file(s) you'd like to update. Here are some tips and tricks for [using the docs codebase](#working-in-the-microstrategyembedding-sdk-docs-repository). +Make your changes to the file(s) you'd like to update. Here are some tips and tricks for +[using the docs codebase](#working-in-the-strategyembedding-sdk-docs-repository). -- Are you making changes to the application code? You'll need **Node.js v16** to run the site locally. See [contributing/development.md](contributing/development.md). +- Are you making changes to the application code? You'll need **Node.js v16** to run the site + locally. See [contributing/development.md](contributing/development.md). - Are you contributing to markdown? We use [Markdown](https://www.markdownguide.org/basic-syntax/). ### Open a pull request -When you're done making changes and you'd like to propose them for review, use the [pull request template](#pull-request-template) to open your PR (pull request). +When you're done making changes and you'd like to propose them for review, use the +[pull request template](#pull-request-template) to open your PR (pull request). ### Submit your PR & get it reviewed -- Once you submit your PR, others from the Docs community will review it with you. The first thing you're going to want to do is a [self review](#self-review). +- Once you submit your PR, others from the Docs community will review it with you. The first thing + you're going to want to do is a [self review](#self-review). - After that, we may have questions, check back on your PR to keep up with the conversation. ### Your PR is merged -Congratulations! The whole MicroStrategy community thanks you. :sparkles: +Congratulations! The whole Strategy community thanks you. :sparkles: -Once your PR is merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/MicroStrategy/embedding-sdk-docs/graphs/contributors) and at the bottom of the page you contributed to. +Once your PR is merged, you will be proudly listed as a contributor in the +[contributor chart](https://github.com/MicroStrategy/embedding-sdk-docs/graphs/contributors) and at +the bottom of the page you contributed to. -### Keep contributing as you use MicroStrategy Docs +### Keep contributing as you use Strategy Docs -Now that you're a part of the MicroStrategy Docs community, you can keep participating in many ways. +Now that you're a part of the Strategy Docs community, you can keep participating in many ways. **Learn more about contributing:** @@ -77,7 +97,7 @@ Now that you're a part of the MicroStrategy Docs community, you can keep partici - [:earth_asia: Translations](#earth_asia-translations) - [Starting with an issue](#starting-with-an-issue) - [Opening a pull request](#opening-a-pull-request) - - [Working in the MicroStrategy/embedding-sdk-docs repository](#working-in-the-microstrategyembedding-sdk-docs-repository) + - [Working in the Strategy/embedding-sdk-docs repository](#working-in-the-strategyembedding-sdk-docs-repository) - [Reviewing](#reviewing) - [Self review](#self-review) - [Test it locally](#test-it-locally) @@ -87,25 +107,42 @@ Now that you're a part of the MicroStrategy Docs community, you can keep partici ## :memo: Types of contributions -You can contribute to the MicroStrategy Embedding SDK Docs content and site in several ways. This repo is a place to discuss and collaborate on MicroStrategy Embedding SDK Docs! Our small, but mighty :muscle: docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be closed. +You can contribute to the Strategy Embedding SDK Docs content and site in several ways. This repo is +a place to discuss and collaborate on Strategy Embedding SDK Docs! Our small, but mighty :muscle: +docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be +closed. ### :beetle: Issues -If you've found something in the content or the website that should be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue [here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). We'll use the issue to have a conversation about the problem you want to fix. +If you've found something in the content or the website that should be updated, search open issues +to see if someone else has reported the same thing. If it's something new, open an issue +[here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). We'll use the issue to have a +conversation about the problem you want to fix. ### :hammer_and_wrench: Pull requests -A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. +A +[pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) +is a way to suggest changes in our repository. -When we merge those changes, they should be deployed to the live site within 24 hours. :earth_africa: To learn more about opening a pull request in this repo, see [Opening a pull request](#opening-a-pull-request) below. +When we merge those changes, they should be deployed to the live site within 24 hours. +:earth_africa: To learn more about opening a pull request in this repo, see +[Opening a pull request](#opening-a-pull-request) below. ### :question: Support -We are a small team working hard to keep up with the documentation demands of a continuously changing product. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with MicroStrategy, unrelated to our documentation, please [contact MicroStrategy Support directly](https://www.microstrategy.com/support). Any issues, or pull requests opened here requesting support will be given information about how to contact MicroStrategy Support, then closed and locked. +We are a small team working hard to keep up with the documentation demands of a continuously +changing product. Unfortunately, we just can't help with support questions in this repository. If +you are experiencing a problem with Strategy, unrelated to our documentation, please +[contact Strategy Support directly](https://www.microstrategy.com/support). Any issues, or pull +requests opened here requesting support will be given information about how to contact Strategy +Support, then closed and locked. ### :earth_asia: Translations -This website is internationalized and available in multiple languages. The source content in this repository is written in English. We integrate with an external localization platform and work with professional translators to localize the English content. +This website is internationalized and available in multiple languages. The source content in this +repository is written in English. We integrate with an external localization platform and work with +professional translators to localize the English content. **We do not currently accept contributions for translated content**, but we hope to in the future. @@ -115,20 +152,28 @@ You can browse existing issues to find something that needs help! ## Opening a pull request -You can use the GitHub user interface :pencil2: for some small changes, like fixing a typo or updating a readme. You can also fork the repo and then clone it locally, to view changes and run your tests on your machine. +You can use the GitHub user interface :pencil2: for some small changes, like fixing a typo or +updating a readme. You can also fork the repo and then clone it locally, to view changes and run +your tests on your machine. -## Working in the MicroStrategy/embedding-sdk-docs repository +## Working in the Strategy/embedding-sdk-docs repository Here's some information that might be helpful while working on a Docs PR: -- [Development](contributing/development.md) - This short guide describes how to get this app running on your local machine. -- [Content style guide for MicroStrategy Docs](contributing/content-style-guide.md) - This guide covers information about how we style our content and images. It also links to the resources we use for general style guidelines. +- [Development](contributing/development.md) - This short guide describes how to get this app + running on your local machine. +- [Content style guide for Strategy Docs](contributing/content-style-guide.md) - This guide covers + information about how we style our content and images. It also links to the resources we use for + general style guidelines. ## Reviewing -We (usually the docs team, but sometimes MicroStrategy product managers, engineers, or supportocats too!) review every single PR. The purpose of reviews is to create the best content we can for people who use MicroStrategy. +We (usually the docs team, but sometimes Strategy product managers, engineers, or supportocats too!) +review every single PR. The purpose of reviews is to create the best content we can for people who +use Strategy. -:yellow_heart: Reviews are always respectful, acknowledging that everyone did the best possible job with the knowledge they had at the time. +:yellow_heart: Reviews are always respectful, acknowledging that everyone did the best possible job +with the knowledge they had at the time. :yellow_heart: Reviews discuss content, not the person who created it. @@ -143,28 +188,43 @@ For content changes, make sure that you: - [ ] Confirm the changes pass linter checks by running `yarn lint`. - [ ] Make sure your content is rendered as expected by running `yarn start`. - [ ] Review the content for technical accuracy. -- [ ] Confirm your changes follow the [style guide](https://github.com/MicroStrategy/embedding-sdk-docs/blob/main/contributing/content-style-guide.md). +- [ ] Confirm your changes follow the + [style guide](https://github.com/MicroStrategy/embedding-sdk-docs/blob/main/contributing/content-style-guide.md). ### Test it locally You should always test your changes locally if the changes are more than just fixing some wording. -Start the site locally, by running `yarn start` in the root folder of the project. The site will be started locally with URL `http://localhost:3000`. Visit the site to make sure it is displayed well. +Start the site locally, by running `yarn start` in the root folder of the project. The site will be +started locally with URL `http://localhost:3000`. Visit the site to make sure it is displayed well. ### Pull request template -When you open a pull request, you must fill out the ["Ready for review" template](./.github/pull_request_template.md) before we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request. +When you open a pull request, you must fill out the +["Ready for review" template](./.github/pull_request_template.md) before we can review your PR. This +template helps reviewers understand your changes and the purpose of your pull request. ### Suggested changes -We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch. +We may ask for changes to be made before a PR can be merged, either using +[suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) +or pull request comments. You can apply suggested changes directly through the UI. You can make any +other changes in your fork, then commit them to your branch. -As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations). +As you update your PR and apply changes, mark each conversation as +[resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations). ## Windows This site can be developed on Windows, however a few potential gotchas need to be kept in mind: -1. Regular Expressions: Windows uses `\r\n` for line endings, while Unix based systems use `\n`. Therefore when working on Regular Expressions, use `\r?\n` instead of `\n` in order to support both environments. The Node.js [`os.EOL`](https://nodejs.org/api/os.html#os_os_eol) property can be used to get an OS-specific end-of-line marker. -1. Paths: Windows systems use `\` for the path separator, which would be returned by `path.join` and others. You could use `path.posix`, `path.posix.join` etc and the [slash](https://ghub.io/slash) module, if you need forward slashes - like for constructing URLs - or ensure your code works with either. -1. Bash: Not every Windows developer has a terminal that fully supports Bash, so it's generally preferred to write [scripts](/script) in JavaScript instead of Bash. +1. Regular Expressions: Windows uses `\r\n` for line endings, while Unix based systems use `\n`. + Therefore when working on Regular Expressions, use `\r?\n` instead of `\n` in order to support + both environments. The Node.js [`os.EOL`](https://nodejs.org/api/os.html#os_os_eol) property can + be used to get an OS-specific end-of-line marker. +1. Paths: Windows systems use `\` for the path separator, which would be returned by `path.join` and + others. You could use `path.posix`, `path.posix.join` etc and the [slash](https://ghub.io/slash) + module, if you need forward slashes - like for constructing URLs - or ensure your code works with + either. +1. Bash: Not every Windows developer has a terminal that fully supports Bash, so it's generally + preferred to write [scripts](/script) in JavaScript instead of Bash. diff --git a/LICENSE b/LICENSE index 3156baf..f8c2a2c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2023, MicroStrategy Incorporated. All rights reserved. +Copyright 2023, Strategy Incorporated. All rights reserved. Apache License Version 2.0, January 2004 @@ -188,7 +188,7 @@ Copyright 2023, MicroStrategy Incorporated. All rights reserved. same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2023, MicroStrategy Incorporated. + Copyright 2023, Strategy Incorporated. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index b4dac59..163982d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ Documentation for Embedding SDK ### Requirements -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed. +- [Node.js](https://nodejs.org/en/download/) version 16.14 or above (which can be checked by running + `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions + on a single machine installed. - When installing Node.js, you are recommended to check all checkboxes related to dependencies. ### Step one @@ -29,7 +31,8 @@ yarn yarn start ``` -This command will start a local server and you'll be able to work on your site with hot reloads and some nice Browsersync features. 💥 +This command will start a local server and you'll be able to work on your site with hot reloads and +some nice Browsersync features. 💥 --- @@ -37,22 +40,31 @@ This command will start a local server and you'll be able to work on your site w ### Start contributing right now -We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code. +We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contributions-memo), +including some that don't require you to write a single line of code. #### Click **Edit** from docs -As you're using Embedding SDK Docs, you may find something in an article that you'd like to add to, update, or change. Click on **Edit** button, which could be found on the top right corner of the article, to navigate directly to that article in the codebase, so that you can begin making your contribution. +As you're using Embedding SDK Docs, you may find something in an article that you'd like to add to, +update, or change. Click on **Edit** button, which could be found on the top right corner of the +article, to navigate directly to that article in the codebase, so that you can begin making your +contribution. #### Open an issue -If you've found a problem, you can open an issue [here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). +If you've found a problem, you can open an issue +[here](https://github.com/MicroStrategy/embedding-sdk-docs/issues). #### Solve an issue -If you have a solution to one of the open issues, you will need to fork the repository and submit a pull request. For more details about this process, please check out [Getting Started with Contributing](CONTRIBUTING.md). +If you have a solution to one of the open issues, you will need to fork the repository and submit a +pull request. For more details about this process, please check out +[Getting Started with Contributing](CONTRIBUTING.md). #### And that's it -That's how you can get started easily as a member of the MicroStrategy Embedding SDK Documentation community. :sparkles: +That's how you can get started easily as a member of the Strategy Embedding SDK Documentation +community. :sparkles: -If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](CONTRIBUTING.md). +If you want to know more, or you're making a more complex contribution, check out +[Getting Started with Contributing](CONTRIBUTING.md). diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md index aec39b7..f67af1e 100644 --- a/contributing/content-style-guide.md +++ b/contributing/content-style-guide.md @@ -2,15 +2,20 @@ # Content styling guidelines -We try to keep our styling consistent throughout the documentation. Please follow the guidelines to help us provide better documentation. +We try to keep our styling consistent throughout the documentation. Please follow the guidelines to +help us provide better documentation. ## Markdownlint Some rules are enforced by the [`markdownlint`](../.markdownlint.yml). -You can download the [markdownlint linter](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) from the VSCode marketplace, and it will warn you in the markdown files. +You can download the +[markdownlint linter](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +from the VSCode marketplace, and it will warn you in the markdown files. -To automatically fix these violations when saving a Markdown document, configure Visual Studio Code's [`editor.codeActionsOnSave` setting](https://code.visualstudio.com/docs/getstarted/settings) like so: +To automatically fix these violations when saving a Markdown document, configure Visual Studio +Code's [`editor.codeActionsOnSave` setting](https://code.visualstudio.com/docs/getstarted/settings) +like so: ```text "editor.codeActionsOnSave": { @@ -18,25 +23,36 @@ To automatically fix these violations when saving a Markdown document, configure } ``` -More information about `markdownlint` could be found [here](https://github.com/DavidAnson/markdownlint#rules--aliases). +More information about `markdownlint` could be found +[here](https://github.com/DavidAnson/markdownlint#rules--aliases). ## Front matter - (Required) `title` is the `h1` heading that shows as the title of your documentation. -- (Optional) `sidebar_label` is the title you want to show in the sidebar navigation. If the sidebar label is the same as `title`, you can omit this field. -- (Required) `description` is the summary for this page. It provides better text snippet in the search result. This is only for SEO purpose and it won't show up in the documentation. Therefore, If you want the reader see the description, you may want to have the same content of this description in your documentation as well. +- (Optional) `sidebar_label` is the title you want to show in the sidebar navigation. If the sidebar + label is the same as `title`, you can omit this field. +- (Required) `description` is the summary for this page. It provides better text snippet in the + search result. This is only for SEO purpose and it won't show up in the documentation. Therefore, + If you want the reader see the description, you may want to have the same content of this + description in your documentation as well. -Note: Do not use backticks in front matter since they won't be rendered the same as markdown content. +Note: Do not use backticks in front matter since they won't be rendered the same as markdown +content. ## Headers -Use two hashes (##) for the headers to begin, and continue moving down the line (###, ####, etc.) for subsections. +Use two hashes (##) for the headers to begin, and continue moving down the line (###, ####, etc.) +for subsections. -For headers that need an ordered list, e.g., "1. Do something in this step", it is recommended to write it like `### Step 1: Do something here`, `### 1. Do something here` or something similar instead of `1. ### Do something here` because this would cause the Table of Contents plugin to show the wrong order. +For headers that need an ordered list, e.g., "1. Do something in this step", it is recommended to +write it like `### Step 1: Do something here`, `### 1. Do something here` or something similar +instead of `1. ### Do something here` because this would cause the Table of Contents plugin to show +the wrong order. ## Code blocks -- Code blocks (not inline code) should be surrounded by three backticks on either side. The language should also be specified after the first three backticks, like so: +- Code blocks (not inline code) should be surrounded by three backticks on either side. The language + should also be specified after the first three backticks, like so: ````text ```bash @@ -80,7 +96,8 @@ Supported languages are listed [here](https://prismjs.com/#languages-list). `INLINE CODE BLOCK` ``` -- Inline code that is also a link should not have a backtick so that it still appears blue. Like the following: +- Inline code that is also a link should not have a backtick so that it still appears blue. Like the + following: ```text [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/#!/Authentication/postLogin) @@ -100,7 +117,9 @@ It is suggested to use `-` instead of `*`. ## Emojis -Our docs site supports all [Github-supported emojis](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md). Please use it as needed. +Our docs site supports all +[Github-supported emojis](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md). +Please use it as needed. The list below shows the usage of emojis in our Docs site: @@ -108,42 +127,64 @@ The list below shows the usage of emojis in our Docs site: ## Links and images -- Make sure you check that all links and images are still functional after adding them into Markdown. Some of the links have spaces in them, which don’t work in Markdown and should be replaced by a `%20` or the appropriate generated characters (you can use inspect on the page to identify the id/anchor link). +- Make sure you check that all links and images are still functional after adding them into + Markdown. Some of the links have spaces in them, which don’t work in Markdown and should be + replaced by a `%20` or the appropriate generated characters (you can use inspect on the page to + identify the id/anchor link). -- Images in the `/images` folder are linked relatively. The pathway back can be found by looking at the permalink for the page and backing out until the root folder is reached. For example, if you want to access the images from `playground.md`, you need to access the images like this: `![ALT TEXT](./images/IMAGE-NAME)`, and if you want to access the images from `add-functionality/add-event.md`, you need to access the images like this: `![ALT TEXT](../images/IMAGE-NAME)`. +- Images in the `/images` folder are linked relatively. The pathway back can be found by looking at + the permalink for the page and backing out until the root folder is reached. For example, if you + want to access the images from `playground.md`, you need to access the images like this: + `![ALT TEXT](./images/IMAGE-NAME)`, and if you want to access the images from + `add-functionality/add-event.md`, you need to access the images like this: + `![ALT TEXT](../images/IMAGE-NAME)`. - Endpoints for REST API calls should have links if possible. - For internal links: - - If the description of the link is related to the title of some page, use sentence case. For example: + - If the description of the link is related to the title of some page, use sentence case. For + example: ```md [Ability to customize dashboard pages from embedding Library home page](./embed-library-main-page/embed-custom-ui-on-all-pages.md) ``` - - If the description of the link is in the middle of the sentence and it is a brief explanation of what the link is, use proper cases as needed. For example: + - If the description of the link is in the middle of the sentence and it is a brief explanation of + what the link is, use proper cases as needed. For example: ```md - New properties allow you to [customize features and the UI](./add-functionality/methods-and-properties.md) for an embedded dashboard. + New properties allow you to + [customize features and the UI](./add-functionality/methods-and-properties.md) for an embedded + dashboard. ``` ## Naming conventions - Folders and files - - All folder and file names should have **dashes** (`-`) between **lowercase** letters. There should be no spaces in folder or file names. - - Permalinks for nested files or folders should recognize the nesting; that is, the permalink should be an relative path from the current folder. For instance, to access `add-functionality/add-event.md` from `add-functionality/add-functionality.md` you would use the link `./add-event.md`. - - Markdown links should have a `.md` ending to them like `./add-functionality/add-functionality.md`. + - All folder and file names should have **dashes** (`-`) between **lowercase** letters. There + should be no spaces in folder or file names. + - Permalinks for nested files or folders should recognize the nesting; that is, the permalink + should be an relative path from the current folder. For instance, to access + `add-functionality/add-event.md` from `add-functionality/add-functionality.md` you would use the + link `./add-event.md`. + - Markdown links should have a `.md` ending to them like + `./add-functionality/add-functionality.md`. - Titles, sidebar labels, and headers - - These should use **sentence case**. For example, prefer "This is the title from MicroStrategy" over "This Is The Title From MicroStrategy". - - `sidebar_label` should only be used if you want a different title in the sidebar than the `title` in front matter. (Note: For folders, `label` in sidebars.js takes priority over `sidebar_label`) + - These should use **sentence case**. For example, prefer "This is the title from Strategy" over + "This Is The Title From Strategy". + - `sidebar_label` should only be used if you want a different title in the sidebar than the + `title` in front matter. (Note: For folders, `label` in sidebars.js takes priority over + `sidebar_label`) ## Tables -- The recommended converter could convert the basic HTML table to a Markdown table. However, Markdown doesn’t support merged cells (1 cell in 1 row covers multiple smaller rows). You need to add duplicated entries for the wider row manually). +- The recommended converter could convert the basic HTML table to a Markdown table. However, + Markdown doesn’t support merged cells (1 cell in 1 row covers multiple smaller rows). You need to + add duplicated entries for the wider row manually). For example: @@ -151,7 +192,8 @@ The list below shows the usage of emojis in our Docs site: ![original table example](../docs/images/original_table_example.png) -You need to add "information" cell multiple times manually because the converter cannot handle this correctly. It will omit the "information" cell for the following rows to make the table not correct. +You need to add "information" cell multiple times manually because the converter cannot handle this +correctly. It will omit the "information" cell for the following rows to make the table not correct. ![markdown table example](../docs/images/markdown_table_example.png) @@ -159,7 +201,8 @@ You need to add "information" cell multiple times manually because the converter ## Admonitions -We use `:::tip` to to provide some tips, `:::info` to provide some extra information, and `:::danger` to let readers to pay more attention in this section. +We use `:::tip` to to provide some tips, `:::info` to provide some extra information, and +`:::danger` to let readers to pay more attention in this section. Examples: @@ -205,7 +248,8 @@ should be rendered as ### Available since tag -If you want to mention that the doc is available since some specific release, you can use the following code snippet: +If you want to mention that the doc is available since some specific release, you can use the +following code snippet: ```jsx @@ -244,7 +288,8 @@ and it will look like this: ### Deprecated since tag -If you want to mention that the doc is deprecated since some specific release, you can use the following code snippet: +If you want to mention that the doc is deprecated since some specific release, you can use the +following code snippet: ```jsx diff --git a/contributing/development.md b/contributing/development.md index e3ee3cb..e31ed6f 100644 --- a/contributing/development.md +++ b/contributing/development.md @@ -4,7 +4,9 @@ ## Requirements -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed. +- [Node.js](https://nodejs.org/en/download/) version 16.14 or above (which can be checked by running + `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions + on a single machine installed. - When installing Node.js, you are recommended to check all checkboxes related to dependencies. ## Getting started @@ -16,12 +18,14 @@ ## Content styling guidelines -We want to keep our documentation consistent in styling. More details could be found [here](./content-style-guide.md). +We want to keep our documentation consistent in styling. More details could be found +[here](./content-style-guide.md). ## Adding new content - All documentation markdown files are located within `./docs/`. -- Every documentation markdown file should have the front matter. You should have required `title`, `description`, and an optional `sidebar_label`. Please see the example below: +- Every documentation markdown file should have the front matter. You should have required `title`, + `description`, and an optional `sidebar_label`. Please see the example below: ```text --- @@ -37,9 +41,13 @@ We want to keep our documentation consistent in styling. More details could be f 1. the label in sidebars.js for the file will be used. 1. the title in front matter will be used if the label doesn't exist. - An exception exists for folders' index page or pages in sidebars.js with type `category`. The `label` field is required (instead of optional) in sidebars.js and will take priority over `sidebar_label`. Examples include: `add-functionality/add-functionality.md`, `support-for-different-authentication-environments/support-for-different-authentication-environments.md`. + An exception exists for folders' index page or pages in sidebars.js with type `category`. The + `label` field is required (instead of optional) in sidebars.js and will take priority over + `sidebar_label`. Examples include: `add-functionality/add-functionality.md`, + `support-for-different-authentication-environments/support-for-different-authentication-environments.md`. - - `description` is the summary for this page. It provides better text snippet in the search result. This is only for SEO purpose. + - `description` is the summary for this page. It provides better text snippet in the search + result. This is only for SEO purpose. Note: Don't use backticks in front matter. The text won't be surrounded by code background effect. @@ -49,7 +57,9 @@ This is all based on the ordering in `sidebars.js` file. There are three main ways to add your new doc into the sidebar: -1. If you don't mind the `title` and `sidebar_label` are the same, you can directly add `id` of your doc in `sidebars.js`. The `id` is the file path from `/docs` folder. For example, `add-functionality/add-nav`. +1. If you don't mind the `title` and `sidebar_label` are the same, you can directly add `id` of your + doc in `sidebars.js`. The `id` is the file path from `/docs` folder. For example, + `add-functionality/add-nav`. 1. If you only want to modify the `sidebar_label` value, you can use the code snippet below: @@ -80,30 +90,39 @@ There are three main ways to add your new doc into the sidebar: } ``` -1. If you want to update an existing doc, the versioned docs locate in `/versioned_doc`, the current docs locate in `/docs`. +1. If you want to update an existing doc, the versioned docs locate in `/versioned_doc`, the current + docs locate in `/docs`. 1. If you want to delete an existing version, you need to perform three steps: 1. Remove the version from `versions.json`. 1. Delete the versioned docs directory. Example: `versioned_docs/version-1.0.0`. 1. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json` -More information could be found in `sidebars.js` or in the ["Sidebar" section](https://docusaurus.io/docs/sidebar) of the Docusaurus official documentation. +More information could be found in `sidebars.js` or in the +["Sidebar" section](https://docusaurus.io/docs/sidebar) of the Docusaurus official documentation. ## How to do versioning Run `yarn run docusaurus docs:version VERSION_NAME` to tag a new version. -Detailed information can be found on [Docusaurus Docs](https://docusaurus.io/docs/versioning#tutorials). +Detailed information can be found on +[Docusaurus Docs](https://docusaurus.io/docs/versioning#tutorials). ## Testing your changes -You can run `yarn start` to test your local changes. Make sure everything looks okay before creating a Pull Request. +You can run `yarn start` to test your local changes. Make sure everything looks okay before creating +a Pull Request. -You can also run `yarn lint` before committing to make sure no errors exist. If errors exist, try to run `yarn lint:fix` to auto fix some of the errors for you. If the errors cannot be auto fixed, please fix the error manually based on the terminal logs. +You can also run `yarn lint` before committing to make sure no errors exist. If errors exist, try to +run `yarn lint:fix` to auto fix some of the errors for you. If the errors cannot be auto fixed, +please fix the error manually based on the terminal logs. ## Committing your changes -When you try to commit your changes, `yarn eslint --quiet`, `yarn prettier --list-different`, and `yarn markdownlint` will be run in sequence for the staged files only. If any error is detected, the commit will fail. You need to follow the error messages and suggestions of changes to fix all the errors before committing them. +When you try to commit your changes, `yarn eslint --quiet`, `yarn prettier --list-different`, and +`yarn markdownlint` will be run in sequence for the staged files only. If any error is detected, the +commit will fail. You need to follow the error messages and suggestions of changes to fix all the +errors before committing them. Some helpful commands are available to help you auto fix some of the errors: @@ -113,4 +132,7 @@ Some helpful commands are available to help you auto fix some of the errors: ## Creating pull request -When you finish making changes, and you'd like to propose them for review, fill up the [pull request template](../.github/pull_request_template.md) to open your PR (pull request). You can find more detail on creating a PR in the official GitHub documentation [here](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +When you finish making changes, and you'd like to propose them for review, fill up the +[pull request template](../.github/pull_request_template.md) to open your PR (pull request). You can +find more detail on creating a PR in the official GitHub documentation +[here](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). diff --git a/docs/add-functionality/add-event.md b/docs/add-functionality/add-event.md index fc6ebd0..7672678 100644 --- a/docs/add-functionality/add-event.md +++ b/docs/add-functionality/add-event.md @@ -1,21 +1,37 @@ --- title: Add event handling -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. +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 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. +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 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. +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 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. +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 -Each supported event is described in the table below. You get the EventType from `microstrategy.dossier.EventType`. +Each supported event is described in the table below. You get the EventType from `microstrategy.dossier.EventType` or `microstrategy.embeddingContexts.EventType`. ### onGraphicsSelected @@ -25,7 +41,8 @@ Each supported event is described in the table below. You get the EventType from #### Description -Raised when a graphic in the visualization is selected. This event is raised only if the visualization supports "use as filter". +Raised when a graphic in the visualization is selected. This event is raised only if the +visualization supports "use as filter". #### Content @@ -391,7 +408,8 @@ embedDossier.registerEventHandler(EventType.ON_LIBRARY_ITEM_SELECTED, libraryIte "projectId": "B19DEDCC11D4E0EFC000EB9495D0F44F", "name": "Distribution Center & Brands", "type": 55, - "subtype": null + "subtype": null, + "isDocument": false } ] ``` @@ -570,6 +588,40 @@ embedDossier.registerEventHandler(EventType.ON_DOSSIER_INSTANCE_CHANGED, (conten } ``` +### onInstanceChanged + +#### Event enumeration + +`EventType.ON_INSTANCE_CHANGED` + +#### Description + +Raised when the a new object instance is created or destroyed. The object type could be a dashboard, document, report or bot. + +#### Content + +The event callback parameters contain the project id, object id, object type, object name, and the instance id. + +#### Code example + +```js +embedDossier.registerEventHandler(EventType.ON_INSTANCE_CHANGED, (content) => { + // Use the content here +}); +``` + +#### Content example + +```json +{ + "projectId": "B19DEDCC11D4E0EFC000EB9495D0F44F", + "objectId": "D9AB379D11EC92C1D9DC0080EFD415BB", + "objectName": "Dashboard Prompted on Category", + "objectType": "dossier", + "instanceId": "EC003BC7A046E75DE83373A254824F20" +} +``` + ### onComponentSelectionChanged #### Event enumeration @@ -598,6 +650,8 @@ embedDossier.registerEventHandler(EventType.ON_COMPONENT_SELECTION_CHANGED, (con { "projectId": "B19DEDCC11D4E0EFC000EB9495D0F44F", "dossierId": "EC5441154009D3C39D5BD6AD75865EF4", + "objectId": "EC5441154009D3C39D5BD6AD75865EF4", + "objectType": "dossier", "selectedComponents": [ { "key": "K52", @@ -659,7 +713,8 @@ The following wrapper functions make it easy to register event handlers for spec #### Description -Wrapper function for `registerEventHandler` for `EventType.ON_GRAPHICS_SELECTED` on certain visualizations (whose node key is equal to `vizKey`). +Wrapper function for `registerEventHandler` for `EventType.ON_GRAPHICS_SELECTED` on certain +visualizations (whose node key is equal to `vizKey`). ### registerFilterUpdateHandler(handler) @@ -685,7 +740,10 @@ Wrapper function for `registerEventHandler` for `EventType.ON_PAGE_SWITCHED`. Equal to `registerEventHandler(EventType.ON_PAGE_SWITCHED, pageSwitchedHandler)`. -Because the Map visualization can have multiple map layers, the selected graphics can come from different map layers. As a result, the event raised for `EventType.ON_GRAPHICS_SELECTED` for the Map visualization is different from the event raised for other visualizations. See the following example. +Because the Map visualization can have multiple map layers, the selected graphics can come from +different map layers. As a result, the event raised for `EventType.ON_GRAPHICS_SELECTED` for the Map +visualization is different from the event raised for other visualizations. See the following +example. ```json { @@ -737,4 +795,5 @@ Because the Map visualization can have multiple map layers, the selected graphic Wrapper function for `registerEventHandler` for `EventType.ON_DOSSIER_INSTANCE_ID_CHANGE`. -Equal to `registerEventHandler(EventType.ON_DOSSIER_INSTANCE_ID_CHANGE, dossierInstanceIdChangeHandler)`. +Equal to +`registerEventHandler(EventType.ON_DOSSIER_INSTANCE_ID_CHANGE, dossierInstanceIdChangeHandler)`. diff --git a/docs/add-functionality/add-functionality.md b/docs/add-functionality/add-functionality.md index bbcf503..412f110 100644 --- a/docs/add-functionality/add-functionality.md +++ b/docs/add-functionality/add-functionality.md @@ -1,25 +1,44 @@ --- title: Add functionality to an embedded dashboard -description: Once you have embedded a dashboard, 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. +description: + Once you have embedded a dashboard, 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 dashboard, 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 dashboard, 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 dashboard](./methods-and-properties.md) - 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. + 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 dashboard. For example, the Embedding SDK lets you add code to get the table of contents for the dashboard, 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. + 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 dashboard, 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 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. + 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 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 dashboard, either during execution or after a dashboard 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 dashboard, 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,27 +46,34 @@ Once you have embedded a dashboard, you can use helper methods in the Embedding - [Interact with panel stacks](./panel-stacks.md) - Describes how to interact with panel stacks within dashboard. 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 dashboard 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 dashboard 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 dashboard](./authoring-library.md) - Describes how to embed a dashboard in authoring or edit mode during the initial dashboard load and after the dashboard 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 -If you plan to use Embedding SDK on a web page on a different domain from your MicroStrategy environment, please also meet the following requirements. More information in +If you plan to use Embedding SDK on a web page on a different domain from your Strategy environment, +please also meet the following requirements. More information in 1. [Enable Cross-Origin Resource Sharing (CORS)](../config.md) 1. [Allow SameSite cookies](../config.md#allow-samesite-cookies) -If you plan to use Embedding SDK on the same domain as your MicroStrategy, the above changes are not required. +If you plan to use Embedding SDK on the same domain as your Strategy, the above changes are not +required. ::: diff --git a/docs/add-functionality/add-nav.md b/docs/add-functionality/add-nav.md index 7177325..7b500b2 100644 --- a/docs/add-functionality/add-nav.md +++ b/docs/add-functionality/add-nav.md @@ -1,21 +1,33 @@ --- title: Add navigation -description: Once you have embedded a dashboard, 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 dashboard, 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 dashboard, 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 + dashboard, 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 dashboard, 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 dashboard, 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 dashboard, 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 dashboard, 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 -To help you get started, we have provided a [page navigation example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g14). +To help you get started, we have provided a +[page navigation example in the Embedding SDK Playground](https://microstrategy.github.io/playground/?example=g14). ::: ## Helper methods for navigation -You can use the methods described below to navigate within the dashboard. You can get the table of contents for the dashboard, 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 dashboard, 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. +Most of the navigation is performed using methods of the Dossier class, but there is one method for +navigation in the Chapter class. ### getTableContent() @@ -222,7 +234,8 @@ embedDossier.getCurrentPage(); 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`). +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`). #### Example diff --git a/docs/add-functionality/attribute-element-selection.md b/docs/add-functionality/attribute-element-selection.md index cdb063d..10dd421 100644 --- a/docs/add-functionality/attribute-element-selection.md +++ b/docs/add-functionality/attribute-element-selection.md @@ -1,15 +1,24 @@ --- title: Enable the selection of attribute elements -description: Attribute element selection within dossiers provides end-users with the ability to conveniently select attribute elements in visualizations in an embedding way. 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. +description: + Attribute element selection within dossiers provides end-users with the ability to conveniently + select attribute elements in visualizations in an embedding way. 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 3 release exposes attribute element selection within dossiers. This provides end-users with the ability to conveniently select attribute elements in visualizations in an embedding way. 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 Strategy 2021 Update 3 release exposes attribute element selection within dossiers. This +provides end-users with the ability to conveniently select attribute elements in visualizations in +an embedding way. 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. ## Embedding SDK functionalities With the visualization element selection feature, the Embedding SDK could do the things below: -- Support programmatic selecting of attribute elements in visualizations. This involves the following: +- Support programmatic selecting of attribute elements in visualizations. This involves the + following: a. Select attribute elements from a single visualization after the dashboard is rendered. @@ -17,7 +26,10 @@ With the visualization element selection feature, the Embedding SDK could do the - Support programmatic retrieval of available elements in a visualization. -- Enables the user to register an event handler to notify the parent application when the attribute element selection is changed. Incorporate the ability to register and unregister events for a callback. This enables the parent application to know when the attribute element selection is changed and provide information about the newly selected attribute elements. +- Enables the user to register an event handler to notify the parent application when the attribute + element selection is changed. Incorporate the ability to register and unregister events for a + callback. This enables the parent application to know when the attribute element selection is + changed and provide information about the newly selected attribute elements. ## Embedding SDK APIs and examples @@ -27,7 +39,9 @@ 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 dashboard](./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 @@ -94,7 +108,8 @@ myDossier }); ``` -Since the target state is specified in the API parameters, the callback parameters for the resolve case are not necessary. +Since the target state is specified in the API parameters, the callback parameters for the resolve +case are not necessary. | Parameter Name | Data Type | Example | Comments | | -------------- | ------------ | ------------------------------- | -------------------------------- | @@ -102,7 +117,8 @@ Since the target state is specified in the API parameters, the callback paramete #### Errors -When an error occurs, this API returns a promise object that in turn returns an error object in rejected cases. +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 | | --------------------------------------------------------------------------------------------------------- | -------------- | --------------- | -------------------------------------------- | @@ -121,7 +137,10 @@ 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 dashboard](./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,11 +177,13 @@ microstrategy.dossier.create({ }); ``` -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. +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 -This API returns a dossier promise object in the resolved case, which can be used to call other dossier-owned Embedding SDK APIs. +This API returns a dossier promise object in the resolved case, which can be used to call other +dossier-owned Embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -180,7 +201,8 @@ microstrategy.dossier #### Errors -When an error occurs, this API returns a promise object that in turn returns an error object in rejected cases. +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 | | ------------------------------------------------------------------------------------------- | -------------- | --------------- | --------------------------------------------- | @@ -235,7 +257,8 @@ The `availableElements` is an array representing all the available elements. Her #### Errors -When an error occurs, this API returns a promise object that in turn returns an error object in rejected cases. +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 | | ------------------------------------------------------------------------------------------ | -------------- | --------------- | -------------------------------------------- | @@ -243,7 +266,9 @@ When an error occurs, this API returns a promise object that in turn returns an ### Callback for monitoring the changing of visualization elements -In some instances, the available elements may change when visualization data is changed by a user’s manual actions. An onVisualizationElementsChanged event monitors this action and enables the user to update their available elements immediately when the data is changed. +In some instances, the available elements may change when visualization data is changed by a user’s +manual actions. An onVisualizationElementsChanged event monitors this action and enables the user to +update their available elements immediately when the data is changed. #### Event name @@ -289,7 +314,8 @@ The callback parameter's availableElements are shown below. #### Response -This API returns a `dossier` promise object in the resolved case, which can be used to call other dossier-owned Embedding SDK APIs. +This API returns a `dossier` promise object in the resolved case, which can be used to call other +dossier-owned Embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); diff --git a/docs/add-functionality/authoring-library.md b/docs/add-functionality/authoring-library.md index 06ad855..7655eaa 100644 --- a/docs/add-functionality/authoring-library.md +++ b/docs/add-functionality/authoring-library.md @@ -1,13 +1,22 @@ --- title: Author an embedded dashboard -description: To allow users to conveniently edit a dashboard, 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. +description: + To allow users to conveniently edit a dashboard, 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 dashboard development efforts that occur behind the scenes. To allow users to conveniently edit a dashboard, 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 Strategy 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 dashboard, 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 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](../). +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](../). ::: @@ -19,7 +28,8 @@ With the Authoring Library feature, the Embedding SDK could enable the users to 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 dashboard. + 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. @@ -29,7 +39,8 @@ With the Authoring Library feature, the Embedding SDK could enable the users to ### The availability of existing Embedding SDK APIs -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. +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 | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | @@ -48,23 +59,37 @@ In authoring mode, most dossier-related APIs are disabled as they are designed f | Dossier.removeSessionErrorhandler | Handles the error handlers. | | Dossier.makeSureSessionAlive | Checks the session. If it is expired, you should refresh it. | -The other APIs are disabled in authoring mode. If a disabled API is called in authoring mode, an error is returned with the message, "The API $\{funcName\} isn't supported in the authoring mode!" +The other APIs are disabled in authoring mode. If a disabled API is called in authoring mode, an +error is returned with the message, "The API $\{funcName\} isn't supported in the authoring mode!" ### Events -To avoid unexpected events, except the newly added events (see the callback event API and example), you cannot receive Embedding SDK events in authoring mode as they are designed for consumption mode. +To avoid unexpected events, except the newly added events (see the callback event API and example), +you cannot receive Embedding SDK events in authoring mode as they are designed for consumption mode. ### Initial parameters -The props parameter contains many fields. See [Methods and properties for an embedded dashboard](./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`. +The existing parameters can be roughly divided into three categories and their behaviors can be set +with `dossierRenderingMode = authoring`. -- The parameters shared by both modes, for example, `URL`, `serverURL`, `applicationID`, `objectID`, and `placeholder`. These parameters only involve the embedding framework and are effective on both modes. +- The parameters shared by both modes, for example, `URL`, `serverURL`, `applicationID`, `objectID`, + and `placeholder`. These parameters only involve the embedding framework and are effective on both + modes. -- 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 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 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. +- 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 | | ----------------------------- | --------------------------------------------------------------------------------------------- | @@ -72,7 +97,8 @@ The existing parameters can be roughly divided into three categories and their b | 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: +If you have set values for these fields when setting `dossierRenderingMode = authoring`, a dialog +appears with the error message: ```text The fields ["filters", "visualizationAppearances", "visualizationSelectedElements"] are not allowed to be used when "dossierRenderingMode" is "authoring". Please remove these forbidden fields and try again. @@ -88,7 +114,10 @@ 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 dashboard](./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? | | -------------------------- | --------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | @@ -105,7 +134,8 @@ microstrategy.dossier.create({ #### Response -This API returns a promise `dossier` object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs. +This API returns a promise `dossier` object in the resolved case, which can be used to call other +dossier-owned embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -122,7 +152,8 @@ microstrategy.dossier #### Errors -When an error occurs, this API returns a promise object that in turn returns an error object in rejected cases. +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 | | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------- | --------------------------------------------- | @@ -133,7 +164,9 @@ When an error occurs, this API returns a promise object that in turn returns an ### API for switching to authoring mode -This API, similar to the `Dossier.resizeVisualization` API, can ignore the restriction of the initial `navigationBar.edit` parameter. This means when `navigationBar.edit` is set to false, you cannot enter authoring mode via manual actions, but are able to via this API. +This API, similar to the `Dossier.resizeVisualization` API, can ignore the restriction of the +initial `navigationBar.edit` parameter. This means when `navigationBar.edit` is set to false, you +cannot enter authoring mode via manual actions, but are able to via this API. #### Function @@ -160,9 +193,11 @@ myDossier }); ``` -Since additional feedback information is not required, the callback parameters for the resolve case are not necessary. +Since additional feedback information is not required, the callback parameters for the resolve case +are not necessary. -Similar to the behavior of the existing `goToPage` API, the user's callback should be invoked when the editing page completes loading. +Similar to the behavior of the existing `goToPage` API, the user's callback should be invoked when +the editing page completes loading. | Parameter Name | Data Type | Example | Comments | | -------------- | ------------ | ------------------------------- | -------------------------------- | @@ -170,7 +205,8 @@ Similar to the behavior of the existing `goToPage` API, the user's callback shou #### Errors -When an error occurs, the API returns a promise object that in turn returns an error object in rejected cases. +When an error occurs, the API returns a promise object that in turn returns an error object in +rejected cases. | Error Case | Error Category | Handling Module | Error Handling | | -------------------------------- | ---------------- | --------------- | -------------------------------------------- | @@ -178,7 +214,8 @@ When an error occurs, the API returns a promise object that in turn returns an e ### 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. +When the Save or Close button is clicked in authoring mode, an event is raised that notifies your +application. #### Event name @@ -211,7 +248,10 @@ 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 dashboard](./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,11 +268,13 @@ microstrategy.dossier.create({ }); ``` -If you do not enter a value for `navigationBar`, the dashboard 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 -This API returns a `dossier` promise object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs. +This API returns a `dossier` promise object in the resolved case, which can be used to call other +dossier-owned embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -261,7 +303,9 @@ 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 dashboard](./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: @@ -279,7 +323,8 @@ microstrategy.dossier.create({ #### Response -This API returns a `dossier` promise object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs. +This API returns a `dossier` promise object in the resolved case, which can be used to call other +dossier-owned embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -296,7 +341,8 @@ microstrategy.dossier #### Errors -When an error occurs, the API returns a promise object that in turn returns an error object in rejected cases. +When an error occurs, the API returns a promise object that in turn returns an error object in +rejected cases. | Error Case | Error Category | Handling Module | Error Handling | | ------------------------------------------------- | -------------- | --------------- | --------------------------------------------- | @@ -315,7 +361,9 @@ When an error occurs, the API returns a promise object that in turn returns an e | ---------------- | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | 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 dashboard](./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: @@ -329,7 +377,8 @@ microstrategy.dossier.create({ #### Response -This API returns a `dossier` promise object in the resolved case, which can be used to call other dossier-owned embedding SDK APIs. +This API returns a `dossier` promise object in the resolved case, which can be used to call other +dossier-owned embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -346,7 +395,8 @@ microstrategy.dossier #### Errors -When an error occurs, the API returns a promise object that in turn returns an error object in rejected cases. +When an error occurs, the API returns a promise object that in turn returns an error object in +rejected cases. | Error Case | Error Category | Handling Module | Error Handling | | ---------------------------------------------------- | -------------- | --------------- | --------------------------------------------- | diff --git a/docs/add-functionality/embed-vis.md b/docs/add-functionality/embed-vis.md index e0cd2c5..3db3aa8 100644 --- a/docs/add-functionality/embed-vis.md +++ b/docs/add-functionality/embed-vis.md @@ -1,17 +1,22 @@ --- title: Embed a single visualization -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. +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 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 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 dashboard. +- 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 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. +- 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 +28,18 @@ 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 dashboard 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 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. +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 +49,9 @@ When initializing a dashboard page, you must specify which visualization will be `Dossier.changeVisualizationSize(props)` -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. +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 @@ -69,7 +81,8 @@ myDossier && }); ``` -Since the target state is specified in the API parameters, the callback parameters for the resolve case are not necessary. +Since the target state is specified in the API parameters, the callback parameters for the resolve +case are not necessary. | Parameter Name | Data Type | Example | Comments | | -------------- | ------------ | --------------------------------- | --------------------------------------------------- | @@ -83,7 +96,10 @@ 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 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. +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,13 +122,16 @@ microstrategy.dossier.create({ }); ``` -If you don't enter values for `visualizationAppearances`, the dashboard 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. +Multiple visualizations are not supported. This is because `size` is coupled on different +visualizations, in which only one visualization can be maximized. #### Response -This API returns a `dossier` promise object in the resolved case, which can be used to call other dossier-owned Embedding SDK APIs. +This API returns a `dossier` promise object in the resolved case, which can be used to call other +dossier-owned Embedding SDK APIs. ```js const placeholderDiv = document.getElementById("dossierContainer"); @@ -130,13 +149,16 @@ microstrategy.dossier ### 3. The resize visualization callback -When a user manually clicks the resize button for a visualization, an event is raised that notifies your application. +When a user manually clicks the resize button for a visualization, an event is raised that notifies +your application. #### Event name `Dossier.onVisualizationResized` -The `Dossier` object is created using `microstrategy.dossier.create(props)`. See [Methods and properties for an embedded dashboard](./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 @@ -162,7 +184,9 @@ 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. +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 | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/add-functionality/error-handling.md b/docs/add-functionality/error-handling.md index ca6f6bd..f4be2cd 100644 --- a/docs/add-functionality/error-handling.md +++ b/docs/add-functionality/error-handling.md @@ -1,21 +1,28 @@ --- title: Error handling -description: MicroStrategy provides custom error handling in two stages, during dashboard creation and after dashboard creation. +description: + Strategy 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. +By default, Library displays a pop-up dialog when an error occurs, such as when a dataset is not +found. ![library server error](../images/library_server_error.png) -MicroStrategy provides custom error handling for these kinds of pop-up errors in two stages. +Strategy provides custom error handling for these kinds of pop-up errors in two stages. -MicroStrategy also provides session error handling for session errors in two stages. Because the handling method of the session error is different from other errors, we don't use the custom error handling in this case. +Strategy also provides session error handling for session errors in two stages. Because the handling +method of the session error is different from other errors, we don't use the custom error handling +in this case. ## Custom error handling ### Custom error handling during dashboard creation -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. +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 +32,8 @@ microstrategy.dossier.create({ }); ``` -To disable the custom error handler during dashboard 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({ @@ -37,9 +45,11 @@ microstrategy.dossier.create({ ### Custom error handling after dashboard creation -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. +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. +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. | Class | Method | Description | | ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -67,32 +77,46 @@ microstrategy.dossier }); ``` -### The overall MicroStrategy Library error behavior in embed case +### The overall Strategy Library error behavior in embed case -The error generated by the embedded Library or dashboard 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 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 + Strategy Library behavior; - If `disableCustomErrorHandlerOnCreate` is not set or is `false`: - - If a custom error handler is set by `errorHandler` or `addCustomErrorHandler(customErrorHandler, false)`, the error would only invoke the custom error handler and wouldn't popup a Library error dialog. - - If a custom error handler is set by `addCustomErrorHandler(customErrorHandler, true)`, the error would first popup an error dialog, and when the user clicks the button on the error dialog, the custom error handler would be invoked. - - If no custom error handler is set, the error would not popup an error dialog. There is no additional effect except the error log in the console. + - If a custom error handler is set by `errorHandler` or + `addCustomErrorHandler(customErrorHandler, false)`, the error would only invoke the custom error + handler and wouldn't popup a Library error dialog. + - If a custom error handler is set by `addCustomErrorHandler(customErrorHandler, true)`, the error + would first popup an error dialog, and when the user clicks the button on the error dialog, the + custom error handler would be invoked. + - If no custom error handler is set, the error would not popup an error dialog. There is no + additional effect except the error log in the console. ## Session error handling When the session expiration error occurs: - If there is no `sessionErrorHandler` defined, the page will show the Library's logout page. -- If you define a `sessionErrorHandler`, the function will be executed. After 1 minute, the page will forcefully redirect to the OOTB MicroStrategy Library login page. +- If you define a `sessionErrorHandler`, the function will be executed. After 1 minute, the page + will forcefully redirect to the OOTB Strategy Library login page. The differences from custom error handling: -The `sessionErrorHandler` created during dashboard creation will not be deleted after dashboard 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 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. +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 dashboard creation -The session error handler is executed when the error occurs and you can get details of the error in the `sessionErrorHandler` parameter. +The session error handler is executed when the error occurs and you can get details of the error in +the `sessionErrorHandler` parameter. ```js microstrategy.dossier.create({ @@ -104,13 +128,20 @@ microstrategy.dossier.create({ }); ``` -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). +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 dashboard creation -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. +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. +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. | Class | Method | Description | | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -141,8 +172,14 @@ microstrategy.dossier ## Error handling way in Embedding SDK when checking input params -When using the Embedding SDK to embed a page by calling APIs, we will check the user input first. Different from other types of errors, for the input params error, under the default settings, we will directly pop up a pop-up window, so that users can get the most direct error feedback when developing code. It will throw an error after you click the OK button of this window, you can get it by adding a `catch` outside the called API. +When using the Embedding SDK to embed a page by calling APIs, we will check the user input first. +Different from other types of errors, for the input params error, under the default settings, we +will directly pop up a pop-up window, so that users can get the most direct error feedback when +developing code. It will throw an error after you click the OK button of this window, you can get it +by adding a `catch` outside the called API. ![error popup window](../images/error_popup_window.png) -If you don't want to see this pop-up window, you can close the pop-up window by adding `disableErrorPopupWindow` parameter to the input. It will notify you of this error by throwing an error directly. +If you don't want to see this pop-up window, you can close the pop-up window by adding +`disableErrorPopupWindow` parameter to the input. It will notify you of this error by throwing an +error directly. diff --git a/docs/add-functionality/filters.md b/docs/add-functionality/filters.md index 1384ce7..299143e 100644 --- a/docs/add-functionality/filters.md +++ b/docs/add-functionality/filters.md @@ -1,29 +1,40 @@ --- title: Retrieve and apply filters -description: Filters can be applied both during the execution of an embedded dashboard 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 dashboard 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 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. + 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 dashboard 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 dashboard is rendered](#retrieve-filters-after-a-dashboard-is-rendered) - 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. + 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 dashboard is rendered](#apply-a-filter-after-the-dashboard-is-rendered) - 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. + 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 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. + This section introduces how you can cache the results of several filters and apply them + together. :::tip @@ -42,7 +53,9 @@ To help you get started, we have provided a set of filter examples in the Embedd ## Retrieve filters after a dashboard is rendered -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. +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()` | | | ----------------- | --------------------------------------------------------- | @@ -51,7 +64,8 @@ After an embedded dashboard has been rendered, you can use the `getFilterList() | Description | Returns a list of filters defined in the current chapter. | | Example | `dossier.getFilterList()` | -`getFilterList()` returns an array of JSON objects that each describe a specific filter. Each JSON filter object has the following fields: +`getFilterList()` returns an array of JSON objects that each describe a specific filter. Each +JSON filter object has the following fields: | Field | Description | | -------------- | ------------------------------------------------------------------------------------------------------------- | @@ -79,7 +93,8 @@ The sections below show the filter details for each filter type. } ``` - If the filter operator is not "is null" or "is not null", the `filterDetail` will only have `operator`: + If the filter operator is not "is null" or "is not null", the `filterDetail` will only have + `operator`: ```json { @@ -98,7 +113,10 @@ The sections below show the filter details for each filter type. - `operator` - A `string` that refers to a specific function type used by the metric qualifier filter. Only the `qualByValue` qualify type is supported. Possible values are "equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", or "is not null". + A `string` that refers to a specific function type used by the metric qualifier filter. Only the + `qualByValue` qualify type is supported. Possible values are "equals", "not equals", "greater", + "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", or "is + not null". #### `metricQualByRank` @@ -108,25 +126,30 @@ The sections below show the filter details for each filter type. - `qualType` - A `string` that refers to a specific qualify type used by the metric qualifier filter. Qualify types include "highest", "lowest", "highest percent", "lowest percent". + A `string` that refers to a specific qualify type used by the metric qualifier filter. Qualify + types include "highest", "lowest", "highest percent", "lowest percent". #### `metricSliderByValue` - `max` - Maximum allowed value for the metric slider filter. If the user-inputted value is greater than this value, it will be set to max automatically. + Maximum allowed value for the metric slider filter. If the user-inputted value is greater than + this value, it will be set to max automatically. - `min` - Minimum allowed value for the metric slider filter. If the user-inputted value is less than this value, it will be set to min automatically. + Minimum allowed value for the metric slider filter. If the user-inputted value is less than this + value, it will be set to min automatically. - `from` - User-inputted value that specifies the beginning of the metric range used in the filter expression for the metric slider filter. + User-inputted value that specifies the beginning of the metric range used in the filter expression + for the metric slider filter. - `to` - User-inputted value that specifies the ending of the metric range used in the filter expression for the metric slider filter. + User-inputted value that specifies the ending of the metric range used in the filter expression + for the metric slider filter. - `indexInfo` @@ -145,19 +168,23 @@ The sections below show the filter details for each filter type. - `max` - Maximum allowed value for the metric slider filter. If the user-inputted value is greater than this value, it will be set to max automatically. + Maximum allowed value for the metric slider filter. If the user-inputted value is greater than + this value, it will be set to max automatically. - `min` - Minimum allowed value for the metric slider filter. If the user-inputted value is less than this value, it will be set to min automatically. + Minimum allowed value for the metric slider filter. If the user-inputted value is less than this + value, it will be set to min automatically. - `value` - User-inputted value that specifies the rank used in the filter expression for the metric slider filter. + User-inputted value that specifies the rank used in the filter expression for the metric slider + filter. - `qualType` - Number that refers to a specific qualify type used by the metric qualifier filter. Qualify types include "highest", "lowest", "highest percent", "lowest percent". + Number that refers to a specific qualify type used by the metric qualifier filter. Qualify types + include "highest", "lowest", "highest percent", "lowest percent". - `indexInfo` @@ -175,7 +202,8 @@ The sections below show the filter details for each filter type. - `supportMultiple` - Specifies whether multiple search selections can be applied to the metric slider filter. If it is not true, only one selection will be applied to the filter. + Specifies whether multiple search selections can be applied to the metric slider filter. If it is + not true, only one selection will be applied to the filter. - `items` @@ -193,7 +221,8 @@ The sections below show the filter details for each filter type. - `supportMultiple` - Specifies whether multiple selections can be applied to the metric slider filter. If it is not true, only one selection will be applied to the filter. + Specifies whether multiple selections can be applied to the metric slider filter. If it is not + true, only one selection will be applied to the filter. - `items` @@ -211,7 +240,8 @@ The sections below show the filter details for each filter type. - `supportMultiple` - Specifies whether multiple selections can be applied to the filter. If it is not true, only one selection will be applied to the filter. + Specifies whether multiple selections can be applied to the filter. If it is not true, only one + selection will be applied to the filter. - `indexInfo` @@ -568,7 +598,9 @@ or ## Apply a filter after the dashboard is rendered -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. +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) @@ -589,7 +621,9 @@ Select all the attributes for the filter with `key` and apply the change immedia Deselect all the attributes for the filter with `key` and save the change to client side. -Since `holdSubmit` is set to true, this change is applied and rendered together with other cached changes in an "Apply Filter request" where `holdSubmit` has a falsy value, typically `filterApplyAll`. +Since `holdSubmit` is set to true, this change is applied and rendered together with other cached +changes in an "Apply Filter request" where `holdSubmit` has a falsy value, typically +`filterApplyAll`. #### Example of `filterJson` parameter @@ -608,7 +642,9 @@ Select single attributes for the filter with `key`. Use this API for filters that support single selection. -Use either `name` or `value` to do the selection. `value` is the attribute element ID. You can get it from the `getFilterList` API. `name` should be the attribute element name, if you provide the name, it is converted to a value (ID). +Use either `name` or `value` to do the selection. `value` is the attribute element ID. You can get +it from the `getFilterList` API. `name` should be the attribute element name, if you provide the +name, it is converted to a value (ID). #### Example of `filterJson` parameter @@ -644,7 +680,9 @@ Select multiple attributes for the filter with `key`. Use this API for filters that support multiple selections. -Use either `name` or `value` to do the selection. `value` is the attribute element ID. You can get it from the `getFilterList` API. `name` should be the attribute element name, if you provide the name, it is converted to a value (ID). +Use either `name` or `value` to do the selection. `value` is the attribute element ID. You can get +it from the `getFilterList` API. `name` should be the attribute element name, if you provide the +name, it is converted to a value (ID). #### Example of `filterJson` parameter @@ -748,7 +786,8 @@ Use this API for filters that support multiple selection. ### Dossier.filterAttributeSingleSlider(filterJson) -Select single attributes for the filter with `key` using the slider style. Selection is the index of the attribute in the attributes items `getFilterInfos` result. +Select single attributes for the filter with `key` using the slider style. Selection is the index of +the attribute in the attributes items `getFilterInfos` result. Use this API for filters that support single selection. @@ -766,7 +805,9 @@ Use this API for filters that support single selection. ### Dossier.filterAttributeMultiSlider(filterJson) -Select multiple attributes for the filter with `key` using the slider style. The from and to values in `selections` refer to the starting and ending attribute indexes for attribute items in the `getFilterInfos` result. +Select multiple attributes for the filter with `key` using the slider style. The from and to values +in `selections` refer to the starting and ending attribute indexes for attribute items in the +`getFilterInfos` result. Use this API for filters that support multiple selection. @@ -790,7 +831,8 @@ If `from` is missing, the dataset start date is used. If `to` is missing, the dataset end date is used. -The from and to strings should a format recognized by the `Date.parse()` method. This format should beIETF-compliant RFC 2822 or ISO8601. +The from and to strings should a format recognized by the `Date.parse()` method. This format should +beIETF-compliant RFC 2822 or ISO8601. #### Example of `filterJson` parameter @@ -813,7 +855,8 @@ Apply a metric qualify by value filter. `key` - The filterKey -`operator` - An enum of "equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", or "is not null" +`operator` - An enum of "equals", "not equals", "greater", "greater equal", "less", "less equal", +"between", "not between", "in", "not in", "is null", or "is not null" `firstValue` – The number in the top input box @@ -874,7 +917,8 @@ Example: The step items are: [0, 10, 20, 30, 40, 50] -You enter a metric range of [13, 26], which is converted to the index of step items [1, 3]. This refers to the value range of 10~30. +You enter a metric range of [13, 26], which is converted to the index of step items [1, 3]. This +refers to the value range of 10~30. #### Example of `filterJson` parameter @@ -976,7 +1020,8 @@ No parameters ## 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: +This section introduces how you can cache the results of several filters and apply them together. +Let's say you have the following filters: :::note @@ -994,15 +1039,18 @@ The items in bold are selected. Take the following steps: -1. Apply [`filterSelectMultiAttributes`](#dossierfilterselectmultiattributesfilterjson), set `selections` as `Books` and `Movies`, and set `holdSubmit` as `true`. -1. Apply [`filterSelectSingleAttribute`](#dossierfilterselectsingleattributefilterjson), set `selection` as `Female`, and set `holdSubmit` as `true`. +1. Apply [`filterSelectMultiAttributes`](#dossierfilterselectmultiattributesfilterjson), + set `selections` as `Books` and `Movies`, and set `holdSubmit` as `true`. +1. Apply [`filterSelectSingleAttribute`](#dossierfilterselectsingleattributefilterjson), + set `selection` as `Female`, and set `holdSubmit` as `true`. 1. Apply [`filterApplyAll`](#dossierfilterapplyall). The result returned from server is filtered by Books, Movies, and Female. ## Events -There are two events that are fired on the embedded dashboard 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 3c89298..9a00a31 100644 --- a/docs/add-functionality/methods-and-properties.md +++ b/docs/add-functionality/methods-and-properties.md @@ -1,15 +1,25 @@ --- 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. +description: + When you embed a Strategy dashboard 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. +When you embed a Strategy 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 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. +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. +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,27 +27,38 @@ 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 dashboard 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 dashboard 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 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. +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. +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 Strategy Library page in no more than 4 to 6 containers. -The other similar APIs like `microstrategy.embeddingContexts.embedReportPage(props)` and `microstrategy.embeddingContexts.embedLibraryPage(props)` follow this rule. +The other similar APIs like `microstrategy.embeddingContexts.embedReportPage(props)` and +`microstrategy.embeddingContexts.embedLibraryPage(props)` follow this rule. The `props` parameter is explained in [Properties](#properties). ### Dossier.getDossierInstanceId() -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. +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 dashboard 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 +70,8 @@ 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 dashboard into a container. +The `instanceId` is a unique GUID, which is different each time you embed a dashboard into a +container. ## Properties @@ -67,19 +89,23 @@ No ### `url`, `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` -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: +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. -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`. +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`, `configAppId` is optional. +- `serverURL`, `applicationID`, and `objectID` are required, while `pageKey`, `configAppId` is + optional. #### Default value @@ -110,9 +136,11 @@ microstrategy.dossier.create({ The `containerHeight` property sets the height of the placeholder. - If the style of the placeholder has a height value, the `containerHeight` property is ignored. -- If the `enableResponsive` property is set to true, the `containerWidth` property is ignored and the `containerHeight` property takes effect. +- If the `enableResponsive` property is set to true, the `containerWidth` property is ignored and + the `containerHeight` property takes effect. - The `containerHeight` property is applied as a style: `style="height: $(containerHeight)"`. -- You should not set the `containerHeight` property to `100%` if the `
` container has no parent container, but is attached directly to the ``. +- You should not set the `containerHeight` property to `100%` if the `
` container has no parent + container, but is attached directly to the ``. #### Required? @@ -127,7 +155,8 @@ No The `containerWidth` property sets the width of the placeholder. - If the style of the placeholder has a width value, the `containerWidth` property is ignored. -- If the `enableResponsive` property is set to true, the `containerWidth` property is ignored and the width is adjusted to fit the viewport. +- If the `enableResponsive` property is set to true, the `containerWidth` property is ignored and + the width is adjusted to fit the viewport. #### Required? @@ -139,7 +168,9 @@ No ### `customAuthenticationType` -The `customAuthenticationType` property specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the `CustomAuthenticationType` enumeration. +The `customAuthenticationType` property specifies the token type returned by the `getLoginToken` +function. There are two possible values, which can be provided by the `CustomAuthenticationType` +enumeration. - `CustomAuthenticationType.IDENTITY_TOKEN` - `CustomAuthenticationType.AUTH_TOKEN` @@ -154,9 +185,12 @@ No ### `disableNotification` -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. +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 dashboard status. +Manipulations are not affected by this property. They persist in the same way as the default +dashboard status. #### Required? @@ -168,8 +202,8 @@ No ### `disableErrorPopupWindow` -The `disableErrorPopupWindow` property specifies to disable the popup window caused by the alert which will show when error happens, and throw the error directly. -The deatail of when the error will shown in alert, can be seen [at the error-handling page](error-handling.md#error-handling-before-starting-embed-page-to-library) +The `disableErrorPopupWindow` property specifies to disable the popup window caused by the alert +which will show when error happens, and throw the error directly. #### Required? @@ -199,7 +233,8 @@ The `dockedComment` object is used to configure the comments panel on the Dashbo - `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. -- `dockChangeable` - `Boolean`. If set to `false`, the dock pin button is hidden. The docked status of this panel is controlled by `isDocked`. +- `dockChangeable` - `Boolean`. If set to `false`, the dock pin button is hidden. The docked status + of this panel is controlled by `isDocked`. - `isDocked` - `Boolean`. This configures whether the panel is docked. #### Required? @@ -210,7 +245,7 @@ No `null` -If `dockedComment` is not specified, the MicroStrategy Library default behavior is used. +If `dockedComment` is not specified, the Strategy Library default behavior is used. #### Sample @@ -235,7 +270,8 @@ The `dockedFilter` object is used to configure the filter panel on the Dashboard - `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. -- `dockChangeable` - `Boolean`. If set to `false`, the dock pin button is hidden. The docked status of this panel is controlled by `isDocked`. +- `dockChangeable` - `Boolean`. If set to `false`, the dock pin button is hidden. The docked status + of this panel is controlled by `isDocked`. - `isDocked` - `Boolean`. This configures whether the panel is docked. #### Required? @@ -246,7 +282,7 @@ No `null` -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -270,9 +306,11 @@ microstrategy.dossier.create({ 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"`. +- `theme` - The color theme of the page. Only `"light"` or `"dark"` is accepted. The default is + `"light"`. - `canClose` - `Boolean`. If set to `false`, the panel is forced to appear. -- `dockChangeable` - `Boolean`. If set to `false`, the dock/pin button is hidden. The docked status of this panel is controlled by `isDocked`. +- `dockChangeable` - `Boolean`. If set to `false`, the dock/pin button is hidden. The docked status + of this panel is controlled by `isDocked`. - `isDocked` - `Boolean`. This configures whether the panel is docked. #### Required? @@ -283,7 +321,7 @@ No `null` -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -305,7 +343,9 @@ microstrategy.dossier.create({ 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. +- `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. #### Required? @@ -313,7 +353,7 @@ No #### Default value -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -331,7 +371,8 @@ microstrategy.dossier.create({ ### `enableCollaboration` -Use `enableCollaboration` property to enable or disable collaboration-related controls of the embedded page. +Use `enableCollaboration` property to enable or disable collaboration-related controls of the +embedded page. #### Required? @@ -371,7 +412,8 @@ User needs to log in from the default login page. Specifies whether to enable responsive design. -When this is set to `true`, the placeholder is adjusted to fit the width of the viewpoint and the existing width to height ratio is used to provide the height. +When this is set to `true`, the placeholder is adjusted to fit the width of the viewpoint and the +existing width to height ratio is used to provide the height. #### Required? @@ -383,10 +425,12 @@ No ### `filterFeature` -Use this property to customize the filter functionality on the page. All types of the properties below are `Boolean`. +Use this property to customize the filter functionality on the page. All types of the properties +below are `Boolean`. - `enabled` - Enable or disable filter features. The default is `true`. -- `edit` - Show or hide the filter edit function. Enable or disable editing on the filter panel. The default is `true`. +- `edit` - Show or hide the filter edit function. Enable or disable editing on the filter panel. The + default is `true`. - `summary` - Show or hide the filter summary bar. The default is `true`. #### Required? @@ -397,7 +441,7 @@ No `null` -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -415,7 +459,8 @@ microstrategy.dossier.create({ ### `filters` -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. +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: @@ -512,7 +557,9 @@ microstrategy.dossier.create({ ### `getLoginToken` -The `getLoginToken` property specifies a function that returns a promise, which is resolved with either the authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the `customAuthenticationType` property. +The `getLoginToken` property specifies a function that returns a promise, which is resolved with +either the authorization token (`authToken`) or the identity token (`identityToken`) The token type +is specified by the `customAuthenticationType` property. #### Required? @@ -524,7 +571,9 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. ```js microstrategy.dossier.create({ @@ -558,18 +607,25 @@ microstrategy.dossier.create({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to provide an identity token with `getLoginToken` function. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to +provide an identity token with `getLoginToken` function. -`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is based on login as a Library user, which uses the param of `applicationType:35`. +`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is +based on login as a Library user, which uses the param of `applicationType:35`. ### `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. +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. -- `partialManipulation` - `Boolean` that indicates the personal view's partial execution status. If this is set to `true`, a personal view is in partial execution. -- `status` - The personal view's partial execution status. If this is true, it indicates a personal view is in partial execution. +- `partialManipulation` - `Boolean` that indicates the personal view's partial execution status. If + this is set to `true`, a personal view is in partial execution. +- `status` - The personal view's partial execution status. If this is true, it indicates a personal + view is in partial execution. #### Required? @@ -596,7 +652,8 @@ microstrategy.dossier.create({ ### `navigationBar` -Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties below are `Boolean`. +Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties +below are `Boolean`. - `enabled` - Enable or disable the navigation bar. The default is `false`. - `gotoLibrary` - Show or hide the gotoLibrary icon. The default is `true`. @@ -651,10 +708,15 @@ microstrategy.dossier.create({ ### `customUi` -Use the `customUi` object to customize the UI component visibilities except the dashboard 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). +- `library` - This field is used to customized the UI components on the Strategy 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). #### Required? @@ -664,7 +726,8 @@ No `null` -If `customUi` or `customUi.library` is `null`, all the UI components on MicroStrategy Library home page would be visible. +If `customUi` or `customUi.library` is `null`, all the UI components on Strategy Library home page +would be visible. #### Sample @@ -701,7 +764,8 @@ microstrategy.dossier.create({ ### `optionsFeature` -Use the `optionsFeature` object to customize the Options feature on the page. All detailed properties below are `Boolean`, with `true` as the default value. +Use the `optionsFeature` object to customize the Options feature on the page. All detailed +properties below are `Boolean`, with `true` as the default value. - `enabled` - Enable or disable the options feature. - `help` - Show or hide help functionality. @@ -719,7 +783,8 @@ No `null` -If `optionsFeature` is `null`, the Options features are enabled. Whether you will see the interface is based on the `navigationBar` object. +If `optionsFeature` is `null`, the Options features are enabled. Whether you will see the interface +is based on the `navigationBar` object. #### Sample @@ -743,7 +808,8 @@ microstrategy.dossier.create({ ### `shareFeature` -Use the `shareFeature` object to customize the Share features on the page. All detailed properties below are Boolean, with `true` as the default value. +Use the `shareFeature` object to customize the Share features on the page. All detailed properties +below are Boolean, with `true` as the default value. - `enabled` - Enable or disable share features. - `invite` - Show or hide invite functionality. @@ -762,7 +828,8 @@ No `null` -If `optionsFeature` is `null`, the Share features are enabled. Whether you will see the interface is based on the `navigationBar` object. +If `optionsFeature` is `null`, the Share features are enabled. Whether you will see the interface is +based on the `navigationBar` object. #### Sample @@ -785,9 +852,12 @@ microstrategy.dossier.create({ ### `smartBanner` -Use the `smartBanner` property to enable or disable the smart banner feature when a user opens an embedded dashboard 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 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. +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? @@ -825,7 +895,7 @@ No `null` -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -843,7 +913,9 @@ microstrategy.dossier.create({ ### `uiMessage` -Use this property to customize the message features on the UI. If `disableNotification` is set to `true`, this property is ignored and all messages are hidden. All detailed properties below are `Boolean`. +Use this property to customize the message features on the UI. If `disableNotification` is set to +`true`, this property is ignored and all messages are hidden. All detailed properties below are +`Boolean`. - `enabled` - Enable or disable all messages. - `addToLibrary` - Show or hide the addToLibrary message. @@ -875,7 +947,8 @@ microstrategy.dossier.create({ ### `visibleTutorials` -Use this property to customize the visibility of tutorials. All detailed properties below are `Boolean`. +Use this property to customize the visibility of tutorials. All detailed properties below are +`Boolean`. - `welcome` - Enable or disable the welcome tutorial. - `library` - Enable or disable the Library tutorial. @@ -892,7 +965,7 @@ No `null` -If this object is not specified, the MicroStrategy Library default behavior is used. +If this object is not specified, the Strategy Library default behavior is used. #### Sample @@ -913,7 +986,10 @@ microstrategy.dossier.create({ ### `visualizationAppearances` -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. +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: @@ -928,8 +1004,10 @@ Format: ``` - `visualizationKey` - The key for the visualization. -- `size` - Set to `"normal"` or `"maximized"`, to restore or maximize this visualization. The default value is `"normal"`. -- `resizeButtonVisible` - Determines whether the resize button is visible. The default value is `true`. +- `size` - Set to `"normal"` or `"maximized"`, to restore or maximize this visualization. The + default value is `"normal"`. +- `resizeButtonVisible` - Determines whether the resize button is visible. The default value is + `true`. #### Required? @@ -943,15 +1021,19 @@ No visualization needs to be maximized or restored during initial loading. ### `authoring` -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. +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` -The custom error handler that is executed when an error occurs in the dossier-creating process. See [Custom error handling](./error-handling.md#custom-error-handling) for details. +The custom error handler that is executed when an error occurs in the dossier-creating process. See +[Custom error handling](./error-handling.md#custom-error-handling) for details. ### `sessionErrorHandler` -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. +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 dashboard @@ -963,7 +1045,8 @@ The config parameter: {"placeholder": placeholderDiv} ``` -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 `
`. +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 4945cb5..7014cca 100644 --- a/docs/add-functionality/panel-stacks.md +++ b/docs/add-functionality/panel-stacks.md @@ -1,32 +1,57 @@ --- title: Interact with panel stacks -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. +description: + Panel stacks provide end users with the ability to conveniently reuse segments of space within a + dashboard to represent data in multiple ways. Strategy 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 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. +The Strategy 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. +Strategy supports one level of nesting within panel stacks. You can switch panel stacks by using a +selector or the panel stack header. ![panel stacks](../images/panel_stacks.png) -Similar to providing navigation capabilities through provided embedded SDK functions, 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. +Similar to providing navigation capabilities through provided embedded SDK functions, 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. :::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 dashboard 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. ::: ## Embedding behavior details -1. Develop a JavaScript function call to support programmatic pagination through a given panel stack. This approach is similar to what is currently done for page navigation. This involves the following: +1. Develop a JavaScript function call to support programmatic pagination through a given panel + stack. This approach is similar to what is currently done for page navigation. This involves the + following: 1. Go to a specific panel, based on the panel identifier (key) 1. Get the current panel identifier 1. Get the available panels -1. Provide a JavaScript event handler to notify the parent application when the visible panel in a panel stack is changed. This approach should mimic the `pageSwitched` handler that currently exists for page navigation. +1. Provide a JavaScript event handler to notify the parent application when the visible panel in a + panel stack is changed. This approach should mimic the `pageSwitched` handler that currently + exists for page navigation. -1. Use hooks to interact or switch to the selected panel. This should work in both situations where a separate panel selector exists and when a normal panel selector exists in the panel header. -1. Incorporate the ability to register and unregister events for callback. This enables the parent application to know when a panel stack is switched and provide information about the new panel stack. +1. Use hooks to interact or switch to the selected panel. This should work in both situations where + a separate panel selector exists and when a normal panel selector exists in the panel header. +1. Incorporate the ability to register and unregister events for callback. This enables the parent + application to know when a panel stack is switched and provide information about the new panel + stack. ## Embedding workflow @@ -118,7 +143,8 @@ In which the callback parameters are: Error Message(`error.message`): - "You couldn’t get the current page panel stacks or switch to a panel when the page data is not ready. Please wait a few seconds to call this function again." + "You couldn’t get the current page panel stacks or switch to a panel when the page data is not + ready. Please wait a few seconds to call this function again." ### 2. Switch panels on the current page @@ -128,7 +154,9 @@ In which the callback parameters are: :::tip -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. +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. ::: @@ -204,11 +232,13 @@ in which the callback parameters are: Error Message(`error.message`): - "You couldn’t get the current page panel stacks or switch to a panel when the page data is not ready. Please wait a few seconds to call this function again." + "You couldn’t get the current page panel stacks or switch to a panel when the page data is not + ready. Please wait a few seconds to call this function again." ### 3. Raise a switch panel event -If the panel is switched in an inner or outer window, it raises a switch panel event that enables you to listen for it. The event detail is shown below. +If the panel is switched in an inner or outer window, it raises a switch panel event that enables +you to listen for it. The event detail is shown below. ```json // event: onPanelSwitched @@ -221,7 +251,8 @@ If the panel is switched in an inner or outer window, it raises a switch panel e ### 4. Modify the select visualization callback data -You must also change the callback data of the existing `ON_VIZ_SELECTION_CHANGED` event. Before any changes, the data returned from the event is similar to that shown below. +You must also change the callback data of the existing `ON_VIZ_SELECTION_CHANGED` event. Before any +changes, the data returned from the event is similar to that shown below. ```json { @@ -233,7 +264,8 @@ You must also change the callback data of the existing `ON_VIZ_SELECTION_CHANGED } ``` -This data only contains the selected visualization key and chapter key. If the visualization is inside a panel, you need to provide the panel and panel stack information for it. +This data only contains the selected visualization key and chapter key. If the visualization is +inside a panel, you need to provide the panel and panel stack information for it. You can add code to invoke the callback: @@ -266,7 +298,9 @@ in which the data format of selectedVis is similar to: ## Embedding SDK errors -Since you cannot set the callback parameters, it's impossible for these parameters to produce errors. When an error occurs for other reasons, the Embedding SDK returns a promise object that in turn returns an error object in rejected cases. The possible errors are shown below. +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. ### Dossier.getCurrentPagePanelStacks() @@ -278,7 +312,8 @@ Since you cannot set the callback parameters, it's impossible for these paramete ##### Error message -You couldn’t get the current page panel stacks or switch to a panel when the page data is not ready. Please wait a few seconds to call this function again. +You couldn’t get the current page panel stacks or switch to a panel when the page data is not ready. +Please wait a few seconds to call this function again. ### Dossier.switchPanel(panelKey) @@ -300,7 +335,8 @@ N/A ##### Error message -There isn’t a panel whose key is `${panelKey}` in the current page and selected panels. Please check whether your input parameter of `switchPanel` function is correct. +There isn’t a panel whose key is `${panelKey}` in the current page and selected panels. Please check +whether your input parameter of `switchPanel` function is correct. #### Error case: The API was called while the page was still loading and users cannot switch panels by manually clicking on them @@ -320,4 +356,5 @@ N/A ##### Error message -The manipulation API has encountered an error when switching to panel `${panelKey}`. Please try again later. +The manipulation API has encountered an error when switching to panel `${panelKey}`. Please try +again later. diff --git a/docs/add-functionality/use-custom-dossier-link.md b/docs/add-functionality/use-custom-dossier-link.md index 1de32e0..bbfa86c 100644 --- a/docs/add-functionality/use-custom-dossier-link.md +++ b/docs/add-functionality/use-custom-dossier-link.md @@ -3,27 +3,33 @@ 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 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: +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 dashboard 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 Dashboard Email](../images/dossier-email.png) The link in the email would be a url like: ```url -http://{hostWebPortal}?mstrLibraryLink=https%3A%2F%2Fdemo%2Emicrostrategy%2Ecom%3A8080%2FMicroStrategyLibrary%2Fapp%2F9D8A49D54E04E0BE62C877ACC18A5A0A%2F0627433046E1B80BCE681C87E48F5C28%2Fbookmarks%3Fids%3D77776092475755EE696EEABF94CF3A61 +http://{hostWebPortal}?mstrLibraryLink=https%3A%2F%2Fdemo%2Emicrostrategy%2Ecom%3A8080%2FStrategyLibrary%2Fapp%2F9D8A49D54E04E0BE62C877ACC18A5A0A%2F0627433046E1B80BCE681C87E48F5C28%2Fbookmarks%3Fids%3D77776092475755EE696EEABF94CF3A61 ``` -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 +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 dashboard page. It could get the embedded dashboard 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 dashboard URL. Would be used if there is no "mstrLibraryLink" parameter diff --git a/docs/config.md b/docs/config.md index 79ec7a4..3ef6faf 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,17 +1,27 @@ --- title: Configure Library Server for embedding -description: If you plan to use Embedding SDK on a different domain from your MicroStrategy environment, please enable Cross-Origin Resource Sharing (CORS) and allow SameSite cookies. +description: + If you plan to use Embedding SDK on a different domain from your Strategy environment, please + enable Cross-Origin Resource Sharing (CORS) and allow SameSite cookies. --- -If you plan to use Embedding SDK on a different domain from your MicroStrategy environment, please also meet the following requirements. +If you plan to use Embedding SDK on a different domain from your Strategy environment, please also +meet the following requirements. ## Enable Cross-Origin Resource Sharing (CORS) -Cross-Origin Resource Sharing (CORS) provides a way for a web application running in one origin (domain, protocol, and port) to access selected resources from a server in a different origin. A cross-origin HTTP request uses additional HTTP headers to tell the browser to let the web application share resources. For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts. This means that when a web application requests HTTP resources from a different origin, the response from the other origin must include the right CORS headers. +Cross-Origin Resource Sharing (CORS) provides a way for a web application running in one origin +(domain, protocol, and port) to access selected resources from a server in a different origin. A +cross-origin HTTP request uses additional HTTP headers to tell the browser to let the web +application share resources. For security reasons, browsers restrict cross-origin HTTP requests +initiated from within scripts. This means that when a web application requests HTTP resources from a +different origin, the response from the other origin must include the right CORS headers. :::note -Chrome Web Browser version 80 and above introduces new changes which may impact embedding. For more information, see [KB484005: Chrome v80 Cookie Behavior and the Impact on MicroStrategy Deployments](https://community.microstrategy.com/s/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-MicroStrategy-Deployments). +Chrome Web Browser version 80 and above introduces new changes which may impact embedding. For more +information, +see [KB484005: Chrome v80 Cookie Behavior and the Impact on Strategy Deployments](https://community.microstrategy.com/s/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-Strategy-Deployments). ::: @@ -22,13 +32,15 @@ To enable CORS for the REST Server: `https://:/MicroStrategyLibrary/admin` 1. Navigate to **Library Server -> Security Settings**. -1. Choose the appropriate setting for **Allow Library embedding in other sites** to reconfigure CORS. +1. Choose the appropriate setting for **Allow Library embedding in other sites** to reconfigure + CORS. ![Library Admin CORS Setting](./images/LibraryAdmin_CORSsetting.png) -Using the Library Admin page is the easiest way to enable CORS for the REST Server, but you can also configure CORS manually. +Using the Library Admin page is the easiest way to enable CORS for the REST Server, but you can also +configure CORS manually. -1. Navigate to `MicroStrategyLibrary/WEB-INF/classes/config/configOverride.properties`. +1. Navigate to `StrategyLibrary/WEB-INF/classes/config/configOverride.properties`. 1. Edit the `configOverride.properties` file in a text editor. 1. Add the following lines, or replace them if already present: @@ -36,27 +48,35 @@ Using the Library Admin page is the easiest way to enable CORS for the REST Ser `security.allowedOrigins=http://example.com:port` -1. Restart your MicroStrategy Library web application hosted on the application server. +1. Restart your Strategy Library web application hosted on the application server. -Alternatively, you can also configure this in MicroStrategy Workstation by [editing the properties of the environment](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/library_admin_settings.htm#View). +Alternatively, you can also configure this in Strategy Workstation by +[editing the properties of the environment](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/library_admin_settings.htm#View). ## Allow SameSite cookies -Google Chrome (version 80+) and Microsoft Edge (version 86+) introduced new changes that may impact embedding. +Google Chrome (version 80+) and Microsoft Edge (version 86+) introduced new changes that may impact +embedding. -For Embedding SDK to function as expected in a 3rd-party context, it is required to explicitly label session cookies with `SameSite=None; Secure`. +For Embedding SDK to function as expected in a 3rd-party context, it is required to explicitly label +session cookies with `SameSite=None; Secure`. -### For MicroStrategy 2021 Update 6 or after +### For Strategy 2021 Update 6 or after -Starting in MicroStrategy 2021 Update 6, you can manage SameSite Cookies for Library in Workstation, by following the steps in [this document](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/config_samesite_cookies.htm). +Starting in Strategy 2021 Update 6, you can manage SameSite Cookies for Library in Workstation, by +following the steps in +[this document](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/config_samesite_cookies.htm). ![SameSite Cookie](./images/SameSiteCookie.png) -### For MicroStrategy 2021 Update 5 or before +### For Strategy 2021 Update 5 or before -If you are using MicroStrategy 2021 Update 5 or before, make the following changes on your server instance. +If you are using Strategy 2021 Update 5 or before, make the following changes on your server +instance. -1. If `context.xml` doesn't already exist in the following folder location, create it: `[Tomcat Folder]\webapps\MicroStrategyLibrary\META-INF\context.xml`. Add the following to `context.xml`: +1. If `context.xml` doesn't already exist in the following folder location, create it: + `[Tomcat Folder]\webapps\MicroStrategyLibrary\META-INF\context.xml`. Add the following to + `context.xml`: ```xml @@ -64,7 +84,8 @@ If you are using MicroStrategy 2021 Update 5 or before, make the following chang ``` -1. In `[Tomcat Folder]\webapps\MicroStrategyLibrary\WEB-INF\web.xml`, change `sameSite` param-value blow to `NONE` to permit embedding. +1. In `[Tomcat Folder]\webapps\MicroStrategyLibrary\WEB-INF\web.xml`, change `sameSite` param-value blow + to `NONE` to permit embedding. ```xml @@ -82,18 +103,31 @@ If you are using MicroStrategy 2021 Update 5 or before, make the following chang 1. Ensure your Tomcat is configured to support HTTPS. 1. Restart Tomcat. -For more information, see [Chrome v80 Cookie Behavior and the Impact on MicroStrategy Deployments](https://community.microstrategy.com/s/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-MicroStrategy-Deployments?language=en_US). +For more information, see +[Chrome v80 Cookie Behavior and the Impact on Strategy Deployments](https://community.microstrategy.com/s/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-Strategy-Deployments?language=en_US). ## The Partitioned Cookie Change -Before MicroStrategy ONE June 2024, when the Library server and the client website are in different domains, the Embedding SDK requires third-party cookies to be allowed to work correctly. In the past, Chrome's default setting was only "Block third-party cookies in Incognito mode", so the customer can use Embedding SDK without changing the Chrome settings. +Before Strategy ONE June 2024, when the Library server and the client website are in different +domains, the Embedding SDK requires third-party cookies to be allowed to work correctly. In the +past, Chrome's default setting was only "Block third-party cookies in Incognito mode", so the +customer can use Embedding SDK without changing the Chrome settings. ![The default Chrome preference](./images/chrome-preference.png) -However, third-party cookies are on their way out. Google is expected to stop the use of third-party cookies by [2025 Q2](https://developers.google.com/privacy-sandbox/3pcd). At that time, Chrome will block third-party cookies by default, and the customer can't use Embedding SDK unless he changes the Chrome preference to enable the 3rd party cookies manually. +However, third-party cookies are on their way out. Google is expected to stop the use of third-party +cookies by [2025 Q2](https://developers.google.com/privacy-sandbox/3pcd). At that time, Chrome will +block third-party cookies by default, and the customer can't use Embedding SDK unless he changes the +Chrome preference to enable the 3rd party cookies manually. -To avoid the changes of third-party cookies default setting breaking the Embedding SDK workflow, we adopt [CHIPS](https://developer.chrome.com/docs/privacy-sandbox/chips/)(Cookies Having Independent Partitioned State) solution to put the Library server's cookie into partitioned storage. The user needs to enable the partitioned cookie in the Library settings to use this solution: +To avoid the changes of third-party cookies default setting breaking the Embedding SDK workflow, we +adopt [CHIPS](https://developer.chrome.com/docs/privacy-sandbox/chips/)(Cookies Having Independent +Partitioned State) solution to put the Library server's cookie into partitioned storage. The user +needs to enable the partitioned cookie in the Library settings to use this solution: ![The partitioned cookie setting](./images/partitioned-cookie.png) -After this change, the customer can use most of the Embedding SDK functionalities even if 3rd party cookies are blocked in the Chrome preference. But for the SAML/OIDC login, the old workflow changes, and the user need to do more to make it work. The details can be seen in [SAML or OIDC authentication after MicroStrategy ONE June 2024](./support-for-different-authentication-environments/authentication-saml.md#for-microstrategy-2024-update-6-or-after). +After this change, the customer can use most of the Embedding SDK functionalities even if 3rd party +cookies are blocked in the Chrome preference. But for the SAML/OIDC login, the old workflow changes, +and the user need to do more to make it work. The details can be seen in +[SAML or OIDC authentication after Strategy ONE June 2024](./support-for-different-authentication-environments/authentication-saml.md#for-strategy-one-june-2024-or-after). diff --git a/docs/embed-bot-consumption-page/embed-bot-consumption-page.md b/docs/embed-bot-consumption-page/embed-bot-consumption-page.md index 17de209..fcb7bce 100644 --- a/docs/embed-bot-consumption-page/embed-bot-consumption-page.md +++ b/docs/embed-bot-consumption-page/embed-bot-consumption-page.md @@ -1,19 +1,23 @@ --- -title: Embed MicroStrategy bot consumption page -description: The Embedding SDK allows you to quickly integrate a MicroStrategy bot consumption page into a web application in a responsive manner. +title: Embed Strategy bot consumption page +description: + The Embedding SDK allows you to quickly integrate a Strategy bot consumption page into a web + application in a responsive manner. --- -The Embedding SDK allows you to quickly integrate a MicroStrategy bot consumption page into a web application in a responsive manner. +The Embedding SDK allows you to quickly integrate a Strategy bot consumption page into a web +application in a responsive manner. -There are three basic steps for embedding a MicroStrategy bot consumption page. +There are three basic steps for embedding a Strategy bot consumption page. -1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. ```html ``` - Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy 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 bot consumption page. @@ -21,7 +25,8 @@ There are three basic steps for embedding a MicroStrategy bot consumption page.
``` -1. Call the `microstrategy.embeddingContexts.embedBotConsumptionPage(props)` method to embed the bot consumption page in the container. +1. Call the `microstrategy.embeddingContexts.embedBotConsumptionPage(props)` method to embed the bot + consumption page in the container. ```js microstrategy.embeddingContexts.embedBotConsumptionPage({ @@ -32,8 +37,9 @@ There are three basic steps for embedding a MicroStrategy bot consumption page. }); ``` -To help you get started, we have provided a number of simple applications with sample code and explanations. +To help you get started, we have provided a number of simple applications with sample code and +explanations. -- [Properties for an embedded MicroStrategy bot consumption page](./embed-bot-consumption-properties.md) +- [Properties for an embedded Strategy bot consumption page](./embed-bot-consumption-properties.md) - Describes the properties that can be set for an embedded MicroStrategy bot consumption page. + Describes the properties that can be set for an embedded Strategy bot consumption page. diff --git a/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md b/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md index cab70ee..0ba6464 100644 --- a/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md +++ b/docs/embed-bot-consumption-page/embed-bot-consumption-properties.md @@ -1,23 +1,29 @@ --- -title: Properties for an embedded MicroStrategy bot consumption page -description: Describes the properties that can be set for an embedded MicroStrategy bot consumption page. +title: Properties for an embedded Strategy bot consumption page +description: Describes the properties that can be set for an embedded Strategy bot consumption page. --- -When you embed a MicroStrategy bot consumption page into a web page, you use the `embedBotConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a Strategy bot consumption page into a web page, you use +the `embedBotConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedBotConsumptionPage(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 bot 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 Strategy bot consumption page URL (specified by the `serverUrl` +property). #### Return value -This method returns a promise, which is resolved when the MicroStrategy bot consumption page is loaded. +This method returns a promise, which is resolved when the Strategy bot 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 bot 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 Strategy bot 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: @@ -50,8 +56,8 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ The required parameters in the bot URL. -These properties build the full report page URL to be embedded. -The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. +These properties build the full report page URL to be embedded. The Embedding SDK builds the URL +using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Required? @@ -78,7 +84,8 @@ The optional parameters in the bot URL. Specifies the application and page that the user wants to show in the embedded page. -When these parameters are specified, the embeded page URL would become `serverUrl` + '/app/config/' + `customApplicationId` + '/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. +When these parameters are specified, the embeded page URL would become `serverUrl` + +'/app/config/' + `customApplicationId` + '/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Required? @@ -175,7 +182,8 @@ N/A ### `customAuthenticationType` -Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. +Specifies the token type returned by the `getLoginToken` function. There are two possible values, +which can be provided by the CustomAuthenticationType enumeration. #### Required? @@ -191,7 +199,9 @@ N/A ### `getLoginToken` -Specifies a function that returns a promise, which is resolved with either authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the customAuthenticationType property. +Specifies a function that returns a promise, which is resolved with either authorization token +(`authToken`) or the identity token (`identityToken`) The token type is specified by the +customAuthenticationType property. #### Required? @@ -203,9 +213,12 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. -The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) +The `getLoginToken` function can be found in +[the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) ```js microstrategy.embeddingContexts.embedBotConsumptionPage({ @@ -222,15 +235,18 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add a component to your web server. Refer to Use Custom Authentication for more information. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add +a component to your web server. Refer to Use Custom Authentication for more information. ### `disableCustomErrorHandlerOnCreate` To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. -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. +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 bot creation](../add-functionality/error-handling.md#custom-error-handling-during-bot-creation). +You could also refer to +[Custom error handling during bot creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-creation). #### Required? @@ -246,9 +262,13 @@ N/A ### `errorHandler` -The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when the error occurs in the initial loading process. It's a +callback function that contains one parameter, `error`. The error object has the property `message`, +which contains the detailed error message. -Whether `errorHandler` is set, the error occured inside the embeded page would output an error in the browser console. The detailed behavior could be seen in [The overall MicroStrategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-microstrategy-library-error-behavior-in-embed-case). +Whether `errorHandler` is set, the error occured inside the embeded page would output an error in +the browser console. The detailed behavior could be seen in +[The overall Strategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-strategy-library-error-behavior-in-embed-case). #### Required? @@ -275,12 +295,18 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `sessionErrorHandler` -The custom error handler that executes when an session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when an session expiration error occurs. It's a callback +function that contains one parameter, `error`. The error object has the property `message`, which +contains the detailed error message. When session expires: -- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login page. -- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like reauthentication and refresh page) to renew the session, the embedded page would redirect to the OOTB Library login page. +- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login + page. +- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded + page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like + reauthentication and refresh page) to renew the session, the embedded page would redirect to the + OOTB Library login page. #### Required? @@ -332,29 +358,34 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `customUi` -Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, bot consumption page，bot authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including Strategy Library home page, bot +consumption page，bot authoring page, and report consumption page. #### Properties ##### `addToLibraryBanner` -Use the `addToLibraryBanner` object to customize the "Add To Library" banner on the MicroStrategy bot consumption page. All detailed properties below are `Boolean`. +Use the `addToLibraryBanner` object to customize the "Add To Library" banner on the Strategy bot +consumption page. All detailed properties below are `Boolean`. - `enabled` - - Enable the Library "Add To Library" banner or not. If the banner is disabled in custom application, the true value wouldn’t take effect. + - Enable the Library "Add To Library" banner or not. If the banner is disabled in custom + application, the true value wouldn’t take effect. - Default value: `false`. #### `theme` -Use the `theme` object to customize the "theme" in the MicroStrategy Library including bot consumption page. All detailed properties below are `Boolean`. +Use the `theme` object to customize the "theme" in the Strategy Library including bot consumption page. All detailed properties below are `Boolean`. - `enabled` - - Enable the Library "theme" colors or not. The value can be true or false. If the value isn't defined, the default is true. + - Enable the Library "theme" colors or not. The value can be true or false. If the value isn't + defined, the default is true. ##### `botConsumption` -Use the `botConsumption` object to customize UI of the bot consumption page. All detailed properties below are `Boolean`. +Use the `botConsumption` object to customize UI of the bot consumption page. All detailed properties +below are `Boolean`. - `snapshot.enabled` @@ -373,7 +404,9 @@ Use the `botConsumption` object to customize UI of the bot consumption page. All - `aiBot` - - Enable title bars, the snapshot panel, topics panel, chat panel(show clear history, show give topics, show welcome page bot image, should load history, should save to history) on the bot consumption page or not. + - Enable title bars, the snapshot panel, topics panel, chat panel(show clear history, show give + topics, show welcome page bot image, should load history, should save to history) on the bot + consumption page or not. - Default value is undefined, which falls back to the following: ```javascript @@ -399,16 +432,37 @@ Use the `botConsumption` object to customize UI of the bot consumption page. All } ``` -- `aiBot.titleBar.enabled`: This field specifies whether to enable the title bar of chat panel, snapshot panel and topic panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. However, it's ignored when the field isn't defined or defined as true. Only when the value is false, the title bars of panels are hidden. -- `aiBot.snapshotPanel.enabled`: This field specifies whether to enable the snapshot panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.topicsPanel.enabled`: This field specifies whether to enable the topic panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showClearHistory`: This field specifies whether to show clear history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showGiveTopics`: This field specifies whether to show give topics in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showWelcomePageBotImg`: This field specifies whether to show bot image in the welcome page of the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.showCopyBtn`: This field specifies whether to show copy button in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.shouldExpandRelatedSuggestionsOnInit`: This field specifies whether to show the related suggestions list in the chat panel as expanded or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.shouldLoadHistory`: This field specifies whether to load chat history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. -- `aiBot.chatPanel.shouldSaveToHistory`: This field specifies whether to save chat history in the chat panel on the bot consumption page or not. The value can be true or false. If this field isn't defined, the default is true. +- `aiBot.titleBar.enabled`: This field specifies whether to enable the title bar of chat panel, + snapshot panel and topic panel on the bot consumption page or not. The value can be true or false. + If this field isn't defined, the default is true. However, it's ignored when the field isn't + defined or defined as true. Only when the value is false, the title bars of panels are hidden. +- `aiBot.snapshotPanel.enabled`: This field specifies whether to enable the snapshot panel on the + bot consumption page or not. The value can be true or false. If this field isn't defined, the + default is true. +- `aiBot.topicsPanel.enabled`: This field specifies whether to enable the topic panel on the bot + consumption page or not. The value can be true or false. If this field isn't defined, the default + is true. +- `aiBot.chatPanel.showClearHistory`: This field specifies whether to show clear history in the chat + panel on the bot consumption page or not. The value can be true or false. If this field isn't + defined, the default is true. +- `aiBot.chatPanel.showGiveTopics`: This field specifies whether to show give topics in the chat + panel on the bot consumption page or not. The value can be true or false. If this field isn't + defined, the default is true. +- `aiBot.chatPanel.showWelcomePageBotImg`: This field specifies whether to show bot image in the + welcome page of the chat panel on the bot consumption page or not. The value can be true or false. + If this field isn't defined, the default is true. +- `aiBot.chatPanel.showCopyBtn`: This field specifies whether to show copy button in the chat panel + on the bot consumption page or not. The value can be true or false. If this field isn't defined, + the default is true. +- `aiBot.chatPanel.shouldExpandRelatedSuggestionsOnInit`: This field specifies whether to show the + related suggestions list in the chat panel as expanded or not. The value can be true or false. If + this field isn't defined, the default is true. +- `aiBot.chatPanel.shouldLoadHistory`: This field specifies whether to load chat history in the chat + panel on the bot consumption page or not. The value can be true or false. If this field isn't + defined, the default is true. +- `aiBot.chatPanel.shouldSaveToHistory`: This field specifies whether to save chat history in the + chat panel on the bot consumption page or not. The value can be true or false. If this field isn't + defined, the default is true. #### Sample @@ -465,7 +519,10 @@ No ##### `allowClipboardWrite` -To grant the "ClipboardWrite" permission or not. Could be used to enable the copy functionality on a bot message or not. It's worthy note that the copy functionality also requires the Library server to be HTTPS. If it's an HTTP server, the copy functionality would be disabled, regardless of the value of this flag. +To grant the "ClipboardWrite" permission or not. Could be used to enable the copy functionality on a +bot message or not. It's worthy note that the copy functionality also requires the Library server to +be HTTPS. If it's an HTTP server, the copy functionality would be disabled, regardless of the value +of this flag. ##### Default value @@ -487,7 +544,8 @@ microstrategy.embeddingContexts.embedBotConsumptionPage({ ### `settings` -Specify the custom settings on the embedding pages. Including the non-UI settings of bot consumption page. +Specify the custom settings on the embedding pages. Including the non-UI settings of bot consumption +page. #### Required? @@ -497,7 +555,8 @@ No ##### `botConsumption` -Use the `botConsumption` object to customize the options on the bot consumption page. The detailed properties contain: +Use the `botConsumption` object to customize the options on the bot consumption page. The detailed +properties contain: - `disableManipulationsAutoSaving` diff --git a/docs/embed-document-consumption-page/embed-document-consumption-page.md b/docs/embed-document-consumption-page/embed-document-consumption-page.md new file mode 100644 index 0000000..31ca40f --- /dev/null +++ b/docs/embed-document-consumption-page/embed-document-consumption-page.md @@ -0,0 +1,39 @@ +--- +title: Embed Strategy document consumption page +description: The Embedding SDK allows you to quickly integrate a Strategy document consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as selecting components. +--- + +The Embedding SDK allows you to quickly integrate a Strategy document consumption page into a web application in a responsive manner. It also provides resources to add functionalities such as selecting components. + +There are three basic steps for embedding a Strategy document consumption page. + +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. + + ```html + + ``` + + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy 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 dashboard consumption page. + + ```html +
+ ``` + +1. Call the `microstrategy.embeddingContexts.embedDocumentConsumptionPage(props)` method to embed the dashboard consumption page in the container. + + ```js + microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + serverUrl: "{YOUR_LIBRARY_SERVER_URL}", + projectId: "{YOUR_PROJECT_ID}", + objectId: "{YOUR_OBJECT_ID}", + placeholder: document.getElementById("container"), + }); + ``` + +To help you get started, we have provided a number of simple applications with sample code and explanations. + +- [Properties for an embedded Strategy document consumption page](./embed-document-consumption-properties.md) + + Describes the properties that can be set for an embedded Strategy document consumption page. diff --git a/docs/embed-document-consumption-page/embed-document-consumption-properties.md b/docs/embed-document-consumption-page/embed-document-consumption-properties.md new file mode 100644 index 0000000..f59408e --- /dev/null +++ b/docs/embed-document-consumption-page/embed-document-consumption-properties.md @@ -0,0 +1,417 @@ +--- +title: Properties for an embedded Strategy document consumption page +description: Describes the properties that can be set for an embedded Strategy document consumption page. +--- + +When you embed a Strategy document consumption page into a web page, you use the `embedDocumentConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. + +## Method + +### `microstrategy.embeddingContexts.embedDocumentConsumptionPage(props)` + +This method creates an iFrame on the web page (in the location specified by the `placeholder` property) and inserts a link to the Strategy document consumption page URL (specified by the `serverUrl` property). + +#### Return value + +This method returns a promise, which is resolved when the Strategy document 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 Strategy document 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: + +## Properties + +### `placeholder` + +Reference for the container `
`. + +#### Required? + +Yes + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", +}); +``` + +### `serverUrl`, `projectId`, `objectId` + +The required parameters in the document URL. + +These properties build the full document page URL to be embedded. +The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId`. + +#### Required? + +Yes + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", +}); +``` + +### `customApplicationId`, `layoutKey` + +The optional parameters in the document URL. + +Specifies the application and layout that the user wants to show in the embedded page. + +When these parameters are specified, the embeded page URL would become `serverUrl` + '/app/config/' + `customApplicationId` + '/' + `projectId` + '/' + `objectId` + '/' + `layoutKey`. + +#### Required? + +No + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedDossierConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + customApplicationId: "2AAC5EA4C57449FE9C0F69FE751DCFDB", + layoutKey: "K53", +}); +``` + +### `containerHeight` + +Sets the height of the placeholder. + +If the style of the placeholder has a height value, the containerHeight property is ignored. + +The `containerHeight` property is applied as a style: style="height: $(containerHeight)". + +#### Required? + +No + +#### Default value + +600px + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + containerHeight: "600px", +}); +``` + +### `containerWidth` + +Sets the width of the placeholder. + +If the style of the placeholder has a width value, the containerWidth property is ignored. + +#### Required? + +No + +#### Default value + +800px + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + containerWidth: "800px", +}); +``` + +### `enableCustomAuthentication` + +Specifies whether custom authentication is enabled. + +#### Required? + +No + +#### Default value + +`false` + +User needs to log in from the default login page. + +#### Sample + +N/A + +### `customAuthenticationType` + +Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. + +#### Required? + +No + +#### Default value + +microstrategy.dossier.CustomAuthenticationType.IDENTITY_TOKEN + +#### Sample + +N/A + +### `getLoginToken` + +Specifies a function that returns a promise, which is resolved with either authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the customAuthenticationType property. + +#### Required? + +No + +#### Default value + +See the sample code in the next column for the default implementation of this function. + +#### Sample + +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. + +The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + placeholder: document.getElementById("container"), + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + enableCustomAuthentication: true, + customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN, + // The following function is the default implementation. User can provide custom implementation. + getLoginToken() { + // The similar logic as getLoginToken in existing Embedding SDK + }, +}); +``` + +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add a component to your web server. Refer to Use Custom Authentication for more information. + +### `disableCustomErrorHandlerOnCreate` + +To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. + +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 dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-creation). + +#### Required? + +No + +#### Default value + +false + +#### Sample + +N/A + +### `customErrorHandler` + +The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. + +`customErrorHandler` is similar as `errorHandler`(see [The overall Strategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-strategy-library-error-behavior-in-embed-case)). However, `errorHandler` will be unregistered automatically when the initial loading finishes, but `customErrorHandler` will not. + +#### Required? + +No + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedDossierConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + customErrorHandler: (error) => { + console.log(`catch error during creation: ${error.message}`); + // Do something to handle the error + }, +}); +``` + +### `sessionErrorHandler` + +The custom error handler that executes when an session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. + +When session expires: + +- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login page. +- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like reauthentication and refresh page) to renew the session, the embedded page would redirect to the OOTB Library login page. + +#### Required? + +No + +#### Default value + +N/A + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + sessionErrorHandler: (error) => { + console.log(`catch session error: ${error.message}`); + // Do something to handle the error + }, +}); +``` + +### `instance` + +Use this `instance` object to specify a document instance for the embedded document. If you would like to make some manipulation to the document 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 new document instance. + +- `mid` - This instance ID. + +#### Required? + +No + +#### Default value + +`null` + +#### Sample + +Passing existing instance: + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + instance: { + mid: "CC9F19A411EA1084548F0080EF05D751", + }, +}); +``` + +### `dockedToc` + +Specify the docked properties of the TOC panel. The detailed properties contain: + +- `isDocked` + + - Pin or unpin TOC panel. + - Default value: `false`. + +- `isOpen` + - Open or close TOC panel. + - Default value: `false`. + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + dockedToc: { + isDocked: true, + isOpen: true, + }, +}); +``` + +### `customUi` + +Specifies the custom UI settings on the embedded pages, including Strategy Library home page, dashboard consumption page，dashboard authoring page, document consumption page, and report consumption page. + +#### Properties + +Please see all the properties in [The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md) + +### `settings` + +Specify the custom settings on the embedding pages. Including the non-UI settings of document consumption page. + +#### Required? + +No + +#### Properties + +##### `documentConsumption` + +Use the `documentConsumption` object to customize the options on the document consumption page. The detailed properties contain: + +- `componentSelection.layout.enabled` + + - To assign whether the component selection mode is enabled. + - Default value: `true`. + +- `componentSelection.multipleSelections` + + - To assign whether using the multiple selection mode. + - Default value: `false`. + +#### Sample + +```js +microstrategy.embeddingContexts.embedDocumentConsumptionPage({ + serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary", + projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F", + objectId: "D9AB379D11EC92C1D9DC0080EFD415BB", + placeholder: document.getElementById("container"), + settings: { + documentConsumption: { + componentSelection: { + layout: { + enabled: true, + }, + multipleSelections: false, + }, + }, + }, +}); +``` 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 394ff65..196c843 100644 --- a/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md +++ b/docs/embed-dossier-consumption-page/embed-dossier-consumption-page.md @@ -1,19 +1,25 @@ --- -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. +title: Embed Strategy dashboard consumption page +description: + The Embedding SDK allows you to quickly integrate a Strategy 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 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 Strategy 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 dashboard consumption page. +There are three basic steps for embedding a Strategy dashboard consumption page. -1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. ```html ``` - Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy 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 dashboard consumption page. @@ -21,7 +27,8 @@ There are three basic steps for embedding a MicroStrategy dashboard consumption
``` -1. Call the `microstrategy.embeddingContexts.embedDossierConsumptionPage(props)` method to embed the dashboard 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 +39,20 @@ There are three basic steps for embedding a MicroStrategy dashboard consumption }); ``` -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. +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. +To help you get started, we have provided a number of simple applications with sample code and +explanations. -- [Properties for an embedded MicroStrategy dashboard consumption page](./embed-dossier-consumption-properties.md) +- [Properties for an embedded Strategy dashboard consumption page](./embed-dossier-consumption-properties.md) - Describes the properties that can be set for an embedded MicroStrategy dashboard consumption page. + Describes the properties that can be set for an embedded Strategy dashboard consumption page. - [Dashboard consumption page APIs](../embedding-context/dossier-consumption-page-apis.md) - Describes which Embedding SDK APIs are available on the MicroStrategy dashboard consumption page. + Describes which Embedding SDK APIs are available on the Strategy 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 94755b6..a3f251f 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,31 @@ --- -title: Properties for an embedded MicroStrategy dashboard consumption page -description: Describes the properties that can be set for an embedded MicroStrategy dashboard consumption page. +title: Properties for an embedded Strategy dashboard consumption page +description: Describes the properties that can be set for an embedded Strategy dashboard consumption page. --- -When you embed a MicroStrategy dashboard consumption page into a web page, you use the `embedDossierConsumptionPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a Strategy 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 dashboard 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 Strategy dashboard consumption page URL (specified by the +`serverUrl` property). #### Return value -This method returns a promise, which is resolved when the MicroStrategy dashboard consumption page is loaded. +This method returns a promise, which is resolved when the Strategy 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 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 contains required key:value pairs that defines the Library Server URL and +the `
` placeholder where the iFrame containing the Strategy 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: @@ -50,7 +58,7 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ The required parameters in the dashboard URL. -These properties build the full report page URL to be embedded. +These properties build the full dashboard page URL to be embedded. The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Required? @@ -78,7 +86,8 @@ The optional parameters in the dashboard URL. Specifies the application and page that the user wants to show in the embedded page. -When these parameters are specified, the embeded page URL would become `serverUrl` + '/app/config/' + `customApplicationId` + '/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. +When these parameters are specified, the embeded page URL would become `serverUrl` + +'/app/config/' + `customApplicationId` + '/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Required? @@ -175,7 +184,8 @@ N/A ### `customAuthenticationType` -Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. +Specifies the token type returned by the `getLoginToken` function. There are two possible values, +which can be provided by the CustomAuthenticationType enumeration. #### Required? @@ -191,7 +201,9 @@ N/A ### `getLoginToken` -Specifies a function that returns a promise, which is resolved with either authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the customAuthenticationType property. +Specifies a function that returns a promise, which is resolved with either authorization token +(`authToken`) or the identity token (`identityToken`) The token type is specified by the +customAuthenticationType property. #### Required? @@ -203,9 +215,12 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. -The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) +The `getLoginToken` function can be found in +[the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) ```js microstrategy.embeddingContexts.embedDossierConsumptionPage({ @@ -222,15 +237,18 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add a component to your web server. Refer to Use Custom Authentication for more information. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add +a component to your web server. Refer to Use Custom Authentication for more information. ### `disableCustomErrorHandlerOnCreate` To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. -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. +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 dashboard 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-dashboard-creation). #### Required? @@ -246,9 +264,13 @@ N/A ### `errorHandler` -The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when the error occurs in the initial loading process. It's a +callback function that contains one parameter, `error`. The error object has the property `message`, +which contains the detailed error message. -Whether `errorHandler` is set, the error occured inside the embeded page would output an error in the browser console. The detailed behavior could be seen in [The overall MicroStrategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-microstrategy-library-error-behavior-in-embed-case). +Whether `errorHandler` is set, the error occured inside the embeded page would output an error in +the browser console. The detailed behavior could be seen in +[The overall Strategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-strategy-library-error-behavior-in-embed-case). #### Required? @@ -275,12 +297,18 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ ### `sessionErrorHandler` -The custom error handler that executes when an session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when an session expiration error occurs. It's a callback +function that contains one parameter, `error`. The error object has the property `message`, which +contains the detailed error message. When session expires: -- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login page. -- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like reauthentication and refresh page) to renew the session, the embedded page would redirect to the OOTB Library login page. +- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login + page. +- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded + page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like + reauthentication and refresh page) to renew the session, the embedded page would redirect to the + OOTB Library login page. #### Required? @@ -307,15 +335,18 @@ microstrategy.embeddingContexts.embedDossierConsumptionPage({ ### `customUi` -Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dashboard consumption page，dashboard authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including Strategy Library home page, +dashboard consumption page，dashboard authoring page, and report consumption page. #### Properties -Please see all the properties in [The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md) +Please see all the properties in +[The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md) ### `settings` -Specify the custom settings on the embedding pages. Including the non-UI settings of dashboard consumption page. +Specify the custom settings on the embedding pages. Including the non-UI settings of dashboard +consumption page. #### Required? @@ -325,7 +356,8 @@ No ##### `dossierConsumption` -Use the `dossierConsumption` object to customize the options on the dashboard consumption page. The detailed properties contain: +Use the `dossierConsumption` object to customize the options on the dashboard consumption page. The +detailed properties contain: - `componentSelectionMode` 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 1ea1b4b..4b8edd9 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,12 +1,17 @@ --- 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, dashboard consumption page, dashboard authoring page, and report consumption page. +description: + The Embedding SDK enables you to customize the UI components of all embedded pages, like Strategy + 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, 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: +The Embedding SDK supports the user to customize the UI components of all embedded pages, including +Strategy 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)` +- `microstrategy.embeddingContexts.embedDocumentConsumptionPage(props)` - `microstrategy.embeddingContexts.embedReportPage(props)` Here is an example: @@ -163,22 +168,29 @@ 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 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. +In the example above, the user uses `microstrategy.embeddingContexts.embedLibraryPage` to embed a +Strategy 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: ### `props.customUi.library` -This field is used to customized the UI components on the MicroStrategy Library home page. It has 2 properties: `sidebar` and `navigationBar`. +This field is used to customized the UI components on the Strategy Library home page. It has 2 +properties: `sidebar` and `navigationBar`. #### Properties ##### `sidebar` -Use the `sidebar` object to customize the sidebar on the MicroStrategy Library home page. All detailed properties below are `Boolean`. +Use the `sidebar` object to customize the sidebar on the Strategy Library home page. All detailed +properties below are `Boolean`. - `show` - - Show the Library home page sidebar or not. If the sidebar is disabled in custom application, or `prop.customUi.library.sidebar.enabled` is false, the true value wouldn’t take effect. + - Show the Library home page sidebar or not. If the sidebar is disabled in custom application, or + `prop.customUi.library.sidebar.enabled` is false, the true value wouldn’t take effect. - Default value: `false`. - `enabled` - Show the "show sidebar" icon or not. @@ -186,10 +198,13 @@ Use the `sidebar` object to customize the sidebar on the MicroStrategy Library h ##### `navigationBar` -Use the `navigationBar` object to customize navigation bar on the MicroStrategy Library home page. All detailed properties below are `Boolean`. +Use the `navigationBar` object to customize navigation bar on the Strategy 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 dashboard 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. @@ -219,17 +234,20 @@ No ### `props.customUi.dossierConsumption` -This field is used to customized the UI components on the dashboard 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 ##### `navigationBar` -Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties below are `Boolean`. +Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties +below are `Boolean`. - `enabled` - Enable or disable the navigation bar. - - Default value: `false` if this field is in `microstrategy.dossier.create()`, and `true` if this field is in `microstrategy.embedddingContexts.embedLibraryPage()`. + - Default value: `false` if this field is in `microstrategy.dossier.create()`, and `true` if this + field is in `microstrategy.embedddingContexts.embedLibraryPage()`. - `gotoLibrary` - Show or hide the gotoLibrary icon. - Default value: `true`. @@ -285,13 +303,15 @@ No ### `props.customUi.dossierAuthoring` -This field is used to customized the UI components on the dashboard 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 dashboard 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 dashboard authoring page toolbar or not. @@ -351,7 +371,8 @@ Use the `toolbar` object to customize the visibilities of the toolbar icons on t - 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 dashboard 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 dashboard authoring page toolbar or not. @@ -368,7 +389,8 @@ Use the `toolbar` object to customize the visibilities of the toolbar icons on t ##### `menubar` -Use the `menubar` object to customize the visibilities of the menubar items on the dashboard 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 dashboard authoring page menubar or not. @@ -376,13 +398,15 @@ Use the `menubar` object to customize the visibilities of the menubar items on t ### `props.customUi.reportConsumption` -This field is used to customize the UI components on the report consumption page. It has 1 property: `navigationBar`. +This field is used to customize the UI components on the report consumption page. It has 1 property: +`navigationBar`. #### Properties ##### `navigationBar` -Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties below are `Boolean`. +Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties +below are `Boolean`. - `enabled` - Enable or disable the navigation bar in report consumption page. @@ -415,3 +439,21 @@ Use the `navigationBar` object to customize the navigation bar on the page. All #### Required? No + +### `props.customUi.documentConsumption` + +This field is used to customize the UI components on the document consumption page. It has 1 property: `navigationBar`. + +#### Properties + +##### `navigationBar` + +Use the `navigationBar` object to customize the navigation bar on the page. All detailed properties below are `Boolean`. + +- `gotoLibrary` + - Show or hide the gotoLibrary icon. + - Default value: `true`. + +#### Required? + +No diff --git a/docs/embed-library-main-page/embed-library-main-page.md b/docs/embed-library-main-page/embed-library-main-page.md index 4f41d49..ca60584 100644 --- a/docs/embed-library-main-page/embed-library-main-page.md +++ b/docs/embed-library-main-page/embed-library-main-page.md @@ -1,19 +1,25 @@ --- -title: Embed MicroStrategy Library home page -description: The Embedding SDK allows you to quickly integrate a MicroStrategy Library home page into a web application in a responsive manner. It also provides resources to add functionality such as toggling the navigation bar and sidebar, and getting group data for the current user. +title: Embed Strategy Library home page +description: + The Embedding SDK allows you to quickly integrate a Strategy Library home page into a web + application in a responsive manner. It also provides resources to add functionality such as + toggling the navigation bar and sidebar, and getting group data for the current user. --- -The Embedding SDK allows you to quickly integrate a MicroStrategy Library home page into a web application in a responsive manner. It also provides resources to add functionality such as toggling the navigation bar and sidebar, and getting group data for the current user. +The Embedding SDK allows you to quickly integrate a Strategy Library home page into a web +application in a responsive manner. It also provides resources to add functionality such as toggling +the navigation bar and sidebar, and getting group data for the current user. -There are three basic steps for embedding a MicroStrategy Library home page. +There are three basic steps for embedding a Strategy Library home page. -1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. ```html ``` - Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy 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 Library home page. @@ -21,7 +27,8 @@ There are three basic steps for embedding a MicroStrategy Library home page.
``` -1. Call the `microstrategy.embeddingContexts.embedLibraryPage(props)` method when the application has finished loading. +1. Call the `microstrategy.embeddingContexts.embedLibraryPage(props)` method when the application + has finished loading. ```js microstrategy.embeddingContexts.embedLibraryPage({ @@ -30,12 +37,13 @@ There are three basic steps for embedding a MicroStrategy Library home page. }); ``` -To help you get started, we have provided a number of simple applications with sample code and explanations. +To help you get started, we have provided a number of simple applications with sample code and +explanations. -- [Properties for an embedded MicroStrategy Library home page](./embed-library-properties.md) +- [Properties for an embedded Strategy Library home page](./embed-library-properties.md) - Describes the properties that can be set for an embedded MicroStrategy Library home page. + Describes the properties that can be set for an embedded Strategy Library home page. - [Library page APIs](../embedding-context/library-page-apis.md) - Describes which Embedding SDK APIs are available on the MicroStrategy Library home page. + Describes which Embedding SDK APIs are available on the Strategy Library home page. diff --git a/docs/embed-library-main-page/embed-library-properties.md b/docs/embed-library-main-page/embed-library-properties.md index 70a6716..54c16d0 100644 --- a/docs/embed-library-main-page/embed-library-properties.md +++ b/docs/embed-library-main-page/embed-library-properties.md @@ -1,21 +1,27 @@ --- -title: Properties for an embedded MicroStrategy Library home page -description: Describes the properties that can be set for an embedded MicroStrategy Library home page. +title: Properties for an embedded Strategy Library home page +description: Describes the properties that can be set for an embedded Strategy Library home page. --- -When you embed a MicroStrategy Library home page into a web page, you use the `embedLibraryPage(props)` method under the `microstrategy.embeddingContexts` namespace. +When you embed a Strategy Library home page into a web page, you use +the `embedLibraryPage(props)` method under the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedLibraryPage(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 Library home 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 Strategy Library home page URL (specified by the `serverUrl` +property). #### Return value -This method returns a promise, which is resolved when the MicroStrategy Library home page is loaded. +This method returns a promise, which is resolved when the Strategy Library home page is loaded. -The `props` parameter contains required key:value pairs that defines the Library Server URL and the `
` placeholder where the iFrame containing the MicroStrategy Library home 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 Strategy Library home 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: @@ -39,7 +45,7 @@ N/A ### `serverUrl` -`serverUrl` refers to the MicroStrategy Library server URL. +`serverUrl` refers to the Strategy Library server URL. #### Required? @@ -128,7 +134,8 @@ N/A ### `customAuthenticationType` -Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the CustomAuthenticationType enumeration. +Specifies the token type returned by the `getLoginToken` function. There are two possible values, +which can be provided by the CustomAuthenticationType enumeration. #### Required? @@ -144,7 +151,9 @@ N/A ### `getLoginToken` -Specifies a function that returns a promise, which is resolved with either authorization token (`authToken`) or the identity token (`identityToken`) The token type is specified by the customAuthenticationType property. +Specifies a function that returns a promise, which is resolved with either authorization token +(`authToken`) or the identity token (`identityToken`) The token type is specified by the +customAuthenticationType property. #### Required? @@ -156,9 +165,12 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. -The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) +The `getLoginToken` function can be found in +[the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) ```js microstrategy.embeddingContexts.embedLibraryPage({ @@ -173,15 +185,20 @@ microstrategy.embeddingContexts.embedLibraryPage({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add a component to your web server. Refer to Use Custom Authentication for more information. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you need to add +a component to your web server. Refer to Use Custom Authentication for more information. ### `disableCustomErrorHandlerOnCreate` To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. -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. +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 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. +You could also refer to +[Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-creation) +to see the usage of this parameter in `microstrategy.dossier.create`, which has the same effect as +in `microstrategy.embeddingContexts.embedLibraryPage` function. #### Required? @@ -203,9 +220,13 @@ microstrategy.embeddingContexts.embedLibraryPage({ ### `errorHandler` -The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when the error occurs in the initial loading process. It's a +callback function that contains one parameter, `error`. The error object has the property `message`, +which contains the detailed error message. -Whether `errorHandler` is set, the error occured inside the library home page would output an error in the browser console. The detailed behavior could be seen in [The overall MicroStrategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-microstrategy-library-error-behavior-in-embed-case). +Whether `errorHandler` is set, the error occured inside the library home page would output an error +in the browser console. The detailed behavior could be seen in +[The overall Strategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-strategy-library-error-behavior-in-embed-case). #### Required? @@ -230,12 +251,18 @@ microstrategy.embeddingContexts.embedLibraryPage({ ### `sessionErrorHandler` -The custom error handler that executes when an session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has the property `message`, which contains the detailed error message. +The custom error handler that executes when an session expiration error occurs. It's a callback +function that contains one parameter, `error`. The error object has the property `message`, which +contains the detailed error message. When session expires: -- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login page. -- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like reauthentication and refresh page) to renew the session, the embedded page would redirect to the OOTB Library login page. +- If `sessionErrorHandler` is not set, the embedded page would redirect to the OOTB library login + page. +- If `sessionErrorHandler` is set, the session error handler would be triggered and the embedded + page would not change for 1 minute. If after 1 minute, the error handler doesn't do anything(like + reauthentication and refresh page) to renew the session, the embedded page would redirect to the + OOTB Library login page. #### Required? @@ -262,10 +289,12 @@ microstrategy.embeddingContexts.embedLibraryPage({ Specifies the application that the user wants to show in the embedded page. -The application in MicroStrategy has 2 categories: +The application in Strategy 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 dashboard as its home screen, the embedding would fail and an error would occur. +- 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 dashboard as its home screen, the embedding would fail and an error + would occur. #### Required? @@ -281,15 +310,19 @@ N/A ### `customUi` -Specifies the custom UI settings on the embedded pages, including MicroStrategy Library home page, dashboard consumption page，dashboard authoring page, and report consumption page. +Specifies the custom UI settings on the embedded pages, including Strategy Library home page, +dashboard consumption page，dashboard authoring page, and report consumption page. #### Properties -Please see all the properties in [The customized UI settings in Embedding SDK](./embed-custom-ui-on-all-pages.md) +Please see all the properties in +[The customized UI settings in Embedding SDK](./embed-custom-ui-on-all-pages.md) #### The navigation bar custom setting behavior -The property `customUi.library.navigationBar.enabled` would affect the library home page UI together with the navigation bar setting in the application settings. There are 2 related item in the application settings in MicroStrategy Workstation: +The property `customUi.library.navigationBar.enabled` would affect the library home page UI together +with the navigation bar setting in the application settings. There are 2 related item in the +application settings in Strategy Workstation: - Disable toolbar - Collapse toolbar by default @@ -298,32 +331,44 @@ The property `customUi.library.navigationBar.enabled` would affect the library h The detailed embedding behavior is as below: -- If `customUi.library.navigationBar.enabled` is false, the navigation bar is disabled by the Embedding SDK settings, and it would never be shown on the embedded library page. +- If `customUi.library.navigationBar.enabled` is false, the navigation bar is disabled by the + Embedding SDK settings, and it would never be shown on the embedded library page. -- If `customUi.library.navigationBar.enabled` is true, the setting would still be combined with the settings in the application, to determine the final visibility of the navigation bar: +- If `customUi.library.navigationBar.enabled` is true, the setting would still be combined with the + settings in the application, to determine the final visibility of the navigation bar: - If the current application disables the navigation bar, the navigation bar would never be shown. - If the current application enables the navigation bar: - - If you choose "Collapse toolbar by default" in application settings, the navigation bar is collapsible: + - If you choose "Collapse toolbar by default" in application settings, the navigation bar is + collapsible: - - If `customUi.library.sidebar.show` is false or not set, on the embedded library page, the navigation bar would be collapsed at the start, and only would be expanded/visible when the user expands it manually. + - If `customUi.library.sidebar.show` is false or not set, on the embedded library page, the + navigation bar would be collapsed at the start, and only would be expanded/visible when the + user expands it manually. - - If `customUi.library.sidebar.show` is true, as on the OOTB library page, the sidebar couldn’t be expand unless the navigation bar is visible, the navigation bar would be expanded and shown in this case. + - If `customUi.library.sidebar.show` is true, as on the OOTB library page, the sidebar + couldn’t be expand unless the navigation bar is visible, the navigation bar would be + expanded and shown in this case. - - If you don't choose "Collapse toolbar by default", the navigation bar would be shown on the embedded library page. + - If you don't choose "Collapse toolbar by default", the navigation bar would be shown on the + embedded library page. #### The sidebar custom setting behavior -`customUi.library.navigationBar.enabled` would also affect the library home page UI together with the sidebar setting in the application settings: +`customUi.library.navigationBar.enabled` would also affect the library home page UI together with +the sidebar setting in the application settings: ![Application sidebar settings](../images/custom-app-sidebar-setting.png) 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. +- 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` @@ -368,11 +413,17 @@ Specifies the page on the sidebar entries that you want to embed. }; ``` -- `currentPage.key`: This field specifies the key of the page that the user wants to embed. Its available values are the menu items in the sidebar, which could be in ['home', 'insights', 'subscriptions', 'defaultGroups', 'myGroups', 'contentDiscovery']. +- `currentPage.key`: This field specifies the key of the page that the user wants to embed. Its + available values are the menu items in the sidebar, which could be in ['home', 'insights', + 'subscriptions', 'defaultGroups', 'myGroups', 'contentDiscovery']. -- `currentPage.targetGroup`: This field is only necessary when `currentPage.key` is 'defaultGroups' or 'myGroups', as on library home page the user can't select these 2 menu items but only could select the group items under them. It specifies which group item the user wants to select. +- `currentPage.targetGroup`: This field is only necessary when `currentPage.key` is 'defaultGroups' + or 'myGroups', as on library home page the user can't select these 2 menu items but only could + select the group items under them. It specifies which group item the user wants to select. -- `currentPage.targetGroup.id`: The id of the group the user wants to select. Its available values could be got from the API `EmbeddingContext.libraryPage.getAllMyGroups()` or `EmbeddingContext.libraryPage.getAllDefaultGroups()`. +- `currentPage.targetGroup.id`: The id of the group the user wants to select. Its available values + could be got from the API `EmbeddingContext.libraryPage.getAllMyGroups()` or + `EmbeddingContext.libraryPage.getAllDefaultGroups()`. - `currentPage.targetGroup.name`: The name of the group the user wants to select. @@ -380,7 +431,9 @@ Specifies the page on the sidebar entries that you want to embed. - `currentPage`: Not required - `currentPage.key`: Required if `currentPage` is provided -- `currentPage.targetGroup.id` and `currentPage.targetGroup.name`: The user must at least provide one of them. When both of them are provided, `currentPage.targetGroup.id` would have higher priority. +- `currentPage.targetGroup.id` and `currentPage.targetGroup.name`: The user must at least provide + one of them. When both of them are provided, `currentPage.targetGroup.id` would have higher + priority. #### Default value diff --git a/docs/embed-report-page/embed-report-page.md b/docs/embed-report-page/embed-report-page.md index c534fa1..b2849e0 100644 --- a/docs/embed-report-page/embed-report-page.md +++ b/docs/embed-report-page/embed-report-page.md @@ -1,19 +1,25 @@ --- -title: Embed MicroStrategy report page -description: The Embedding SDK allows you to quickly integrate a MicroStrategy report 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 Strategy report page +description: + The Embedding SDK allows you to quickly integrate a Strategy report 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 report 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 Strategy report 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 report page. +There are three basic steps for embedding a Strategy report page. -1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. ```html ``` - Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy 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 report. @@ -21,7 +27,8 @@ There are three basic steps for embedding a MicroStrategy report page.
``` -1. Call the `microstrategy.embeddingContexts.embedReportPage(props)` method when the application has finished loading. +1. Call the `microstrategy.embeddingContexts.embedReportPage(props)` method when the application has + finished loading. ```js microstrategy.embeddingContexts.embedReportPage({ @@ -32,8 +39,9 @@ There are three basic steps for embedding a MicroStrategy report page. }); ``` -To help you get started, we have provided a number of simple applications with sample code and explanations. +To help you get started, we have provided a number of simple applications with sample code and +explanations. -- [Properties for an embedded MicroStrategy report page](./embed-report-properties.md) +- [Properties for an embedded Strategy report page](./embed-report-properties.md) - Describes the properties that can be set for an embedded MicroStrategy report page. + Describes the properties that can be set for an embedded Strategy report page. diff --git a/docs/embed-report-page/embed-report-properties.md b/docs/embed-report-page/embed-report-properties.md index e48daf1..d6a0876 100644 --- a/docs/embed-report-page/embed-report-properties.md +++ b/docs/embed-report-page/embed-report-properties.md @@ -1,26 +1,30 @@ --- -title: Properties for an embedded MicroStrategy report page -description: Describes the properties that can be set for an embedded MicroStrategy report page. +title: Properties for an embedded Strategy report page +description: Describes the properties that can be set for an embedded Strategy report page. --- -To embed a MicroStrategy report page into a web page, use the `embedReportPage(props)` method under the `microstrategy.embeddingContexts` namespace. +To embed a Strategy report page into a web page, use the `embedReportPage(props)` method under +the `microstrategy.embeddingContexts` namespace. ## Method ### `microstrategy.embeddingContexts.embedReportPage(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 report page URL. The report page URL is built using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. +This method creates an iFrame on the web page, in the location specified by the `placeholder` +property, and inserts a link to the Strategy report page URL. The report page URL is built using +`serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Return value -This method returns a promise, which is resolved when the MicroStrategy report page is loaded. +This method returns a promise, which is resolved when the Strategy report page is loaded. The `props` parameter contains following required key-value pairs: - `serverUrl`, `projectId`, and `objectId` define the full report page URL. -- `placeholder` specifies where the iFrame containing the MicroStrategy report page will be created. +- `placeholder` specifies where the iFrame containing the Strategy report page will be created. -It can also contain other optional key-value pairs to customize the UI, authentication, and custom error handler. +It can also contain other optional key-value pairs to customize the UI, authentication, and custom +error handler. The `props` parameter can contain the following key-value pairs: @@ -44,8 +48,8 @@ N/A ### `serverUrl`,`projectId`,`objectId`, and `pageKey` -These properties build the full report page URL to be embedded. -The Embedding SDK builds the URL using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. +These properties build the full report page URL to be embedded. The Embedding SDK builds the URL +using `serverUrl` + '/app/' + `projectId` + '/' + `objectId` + '/' + `pageKey`. #### Required? @@ -140,7 +144,8 @@ N/A ### `customAuthenticationType` -Specifies the token type returned by the `getLoginToken` function. There are two possible values, which can be provided by the `CustomAuthenticationType` enumeration. +Specifies the token type returned by the `getLoginToken` function. There are two possible values, +which can be provided by the `CustomAuthenticationType` enumeration. #### Required? @@ -156,7 +161,9 @@ N/A ### `getLoginToken` -Specifies a function that returns a promise, which is resolved with either an authorization (`authToken`) or identity (`identityToken`) token. The token type is specified by the `customAuthenticationType` property. +Specifies a function that returns a promise, which is resolved with either an authorization +(`authToken`) or identity (`identityToken`) token. The token type is specified by the +`customAuthenticationType` property. #### Required? @@ -168,9 +175,12 @@ See the sample code in the next column for the default implementation of this fu #### Sample -When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do this using an `XMLHttpRequest`, if your browser does not support `fetch`. +When `customAuthenticationType` is set to `CustomAuthenticationType.AUTH_TOKEN`, the following +sample demonstrates how to send a fetch request to get `authToken` with your credentials. You can do +this using an `XMLHttpRequest`, if your browser does not support `fetch`. -The `getLoginToken` function can be found in [the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) +The `getLoginToken` function can be found in +[the `getLoginToken` doc](../add-functionality/methods-and-properties#getlogintoken) ```js microstrategy.embeddingContexts.embedReportPage({ @@ -187,15 +197,22 @@ microstrategy.embeddingContexts.embedReportPage({ }); ``` -When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you must add a component to your web server. Refer to [Use Custom Authentication](../support-for-different-authentication-environments/seamless-login.md) for more information. +When `customAuthenticationType` is set to `CustomAuthenticationType.IDENTITY_TOKEN`, you must add a +component to your web server. Refer to +[Use Custom Authentication](../support-for-different-authentication-environments/seamless-login.md) +for more information. ### `disableCustomErrorHandlerOnCreate` To disable the custom error handler, set `disableCustomErrorHandlerOnCreate` to true. -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. +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 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. +Refer to +[Custom error handling during dashboard creation](../add-functionality/error-handling.md#custom-error-handling-during-dashboard-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? @@ -219,9 +236,13 @@ microstrategy.embeddingContexts.embedReportPage({ ### `errorHandler` -The custom error handler that executes when the error occurs in the initial loading process. It's a callback function that contains one parameter, `error`. The error object has a `message` property, which contains the detailed error message. +The custom error handler that executes when the error occurs in the initial loading process. It's a +callback function that contains one parameter, `error`. The error object has a `message` property, +which contains the detailed error message. -When `errorHandler` is set, errors that occur inside the report page produce an error in the browser console. See the detailed behavior in [The overall MicroStrategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-microstrategy-library-error-behavior-in-embed-case). +When `errorHandler` is set, errors that occur inside the report page produce an error in the browser +console. See the detailed behavior in +[The overall Strategy Library error behavior in embed case](../add-functionality/error-handling.md#the-overall-strategy-library-error-behavior-in-embed-case). #### Required? @@ -248,12 +269,17 @@ microstrategy.embeddingContexts.embedReportPage({ ### `sessionErrorHandler` -The custom error handler that executes when a session expiration error occurs. It's a callback function that contains one parameter, `error`. The error object has a `message` property that contains the detailed error message. +The custom error handler that executes when a session expiration error occurs. It's a callback +function that contains one parameter, `error`. The error object has a `message` property that +contains the detailed error message. When the session expires: - If `sessionErrorHandler` is not set, the embedded page redirects to the OOTB Library login page. -- If `sessionErrorHandler` is set, the session error handler is triggered and the embedded page does not change for one minute. If the error handler doesn't do anything after one minute, such as reauthentication and refreshing the page to renew the session, the embedded page redirects to the OOTB Library login page. +- If `sessionErrorHandler` is set, the session error handler is triggered and the embedded page does + not change for one minute. If the error handler doesn't do anything after one minute, such as + reauthentication and refreshing the page to renew the session, the embedded page redirects to the + OOTB Library login page. #### Required? @@ -282,10 +308,12 @@ microstrategy.embeddingContexts.embedReportPage({ Specifies the application that the user wants to show in the embedded page. -The application in MicroStrategy has two categories: +The application in Strategy 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 dashboard as its home screen, the embedding fails and an error occurs. +- 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 dashboard as its home screen, the embedding fails and an error + occurs. #### Required? @@ -301,29 +329,37 @@ N/A ### `customUi` -Specifies the custom UI settings on the embedded pages, including the MicroStrategy Library home, dashboard consumption，dashboard authoring, and report consumption pages. +Specifies the custom UI settings on the embedded pages, including the Strategy Library home, +dashboard consumption，dashboard authoring, and report consumption pages. #### Properties -See all properties in [The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md). +See all properties in +[The customized UI settings in Embedding SDK](../embed-library-main-page/embed-custom-ui-on-all-pages.md). #### The navigation bar custom setting behavior -The `customUi.reportConsumption.navigationBar.enabled` property affects the report page UI together with the navigation bar setting in the application settings. There are two related items in the MicroStrategy Workstation application settings: +The `customUi.reportConsumption.navigationBar.enabled` property affects the report page UI together +with the navigation bar setting in the application settings. There are two related items in the +Strategy Workstation application settings: - Disable toolbar - Collapse toolbar by default The detailed embedding behavior is below: -- If `customUi.reportConsumption.navigationBar.enabled` is false, the navigation bar is disabled by the Embedding SDK settings and it is not shown on the embedded report page. +- If `customUi.reportConsumption.navigationBar.enabled` is false, the navigation bar is disabled by + the Embedding SDK settings and it is not shown on the embedded report page. -- If `customUi.reportConsumption.navigationBar.enabled` is true, the setting is combined with the settings in the application, to determine the final visibility of the navigation bar: +- If `customUi.reportConsumption.navigationBar.enabled` is true, the setting is combined with the + settings in the application, to determine the final visibility of the navigation bar: - If the current application disables the navigation bar, the navigation bar is not shown. - If the current application enables the navigation bar: - - If you choose "Collapse toolbar by default" in the application settings, the navigation bar is collapsed at the start and is only expanded/visible when the user expands it manually. + - If you choose "Collapse toolbar by default" in the application settings, the navigation bar is + collapsed at the start and is only expanded/visible when the user expands it manually. - - If you don't choose "Collapse toolbar by default", the navigation bar is shown on the embedded report page. + - If you don't choose "Collapse toolbar by default", the navigation bar is shown on the embedded + report page. diff --git a/docs/embedding-context/bot-consumption-page-apis.md b/docs/embedding-context/bot-consumption-page-apis.md index 2b565f3..ed56396 100644 --- a/docs/embedding-context/bot-consumption-page-apis.md +++ b/docs/embedding-context/bot-consumption-page-apis.md @@ -1,11 +1,13 @@ --- title: Bot consumption page APIs -description: Describes which Embedding SDK APIs are available on the MicroStrategy Bot consumption page. +description: Describes which Embedding SDK APIs are available on the Strategy Bot consumption page. --- -The `embedBotConsumptionPage` object is the manipulator of the MicroStrategy dashboard consumption page. It could be got by `embeddingContext.embedBotConsumptionPage`. +The `embedBotConsumptionPage` object is the manipulator of the Strategy dashboard consumption page. +It could be got by `embeddingContext.embedBotConsumptionPage`. -The details of the `embeddingContext` object could be seen in [Embedding context](./embedding-context.md). +The details of the `embeddingContext` object could be seen in +[Embedding context](./embedding-context.md). The APIs under embed botConsumption page object are as below. @@ -13,8 +15,8 @@ The APIs under embed botConsumption page object are as below. #### Description -This API can be used to ask a question to a bot consumption page which is already loaded. -If the bot consumption page is loading then the question will be triggered after it is initialized +This API can be used to ask a question to a bot consumption page which is already loaded. If the bot +consumption page is loading then the question will be triggered after it is initialized #### Class diff --git a/docs/embedding-context/document-consumption-page-apis.md b/docs/embedding-context/document-consumption-page-apis.md new file mode 100644 index 0000000..1884b50 --- /dev/null +++ b/docs/embedding-context/document-consumption-page-apis.md @@ -0,0 +1,51 @@ +--- +title: Document consumption page APIs +description: Describes which Embedding SDK APIs are available on the Strategy Document consumption page. +--- + +The `documentConsumption` object is the manipulator of the Strategy dashboard consumption page. It could be got by `embeddingContext.documentConsumption`. + +The details of the `embeddingContext` object could be seen in [Embedding context](./embedding-context.md). + +The APIs under embed botConsumption page object are as below. + +### `selectLayouts(layoutKeys)` + +#### Description + +This API can be used to select layouts on an embedded document consumption page which is already loaded. +If the document consumption page is loading, then the layout selection will be triggered after it is initialized. + +#### Class + +`DocumentConsumptionService` + +#### Input Parameters + +- `layoutKeys`: + + **Data Type** + + `array` + + **Required?** + + Yes + +#### Return type + +This API would return a Promise object that resolves to nothing. + +#### Example + +```js +await embeddingContext.documentConsumption.selectLayouts(["K52", "W63"]); +``` + +#### API errors + +This API would report an error in these cases: + +- When the document page is not in the component selection mode. +- When the layout key does not exist. +- When the document page is in the single selection mode, but the `layoutKeys` contain more than 1 layout key. diff --git a/docs/embedding-context/dossier-consumption-page-apis.md b/docs/embedding-context/dossier-consumption-page-apis.md index 8b8c388..f9f8c21 100644 --- a/docs/embedding-context/dossier-consumption-page-apis.md +++ b/docs/embedding-context/dossier-consumption-page-apis.md @@ -1,11 +1,13 @@ --- title: Dashboard consumption page APIs -description: Describes which Embedding SDK APIs are available on the MicroStrategy dashboard consumption page. +description: Describes which Embedding SDK APIs are available on the Strategy dashboard consumption page. --- -The `dossierConsumption` object is the manipulator of the MicroStrategy dashboard consumption page. It could be got by `embeddingContext.dossierConsumption`. +The `dossierConsumption` object is the manipulator of the Strategy 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 details of the `embeddingContext` object could be seen in +[Embedding context](./embedding-context.md). The APIs under Library page object are as below. @@ -15,7 +17,8 @@ The APIs under Library page object are as below. #### Description -This API is used for getting the dashboard definition. Its result contains the dashboard 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 +26,8 @@ This API is used for getting the dashboard definition. Its result contains the d #### Return type -This API would return a Promise object that resolves to an object that contains the dashboard 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 { @@ -49,7 +53,8 @@ This API would return a Promise object that resolves to an object that contains } ``` -If the API encounters an error in its executing process, the error would be thrown and could be caught. +If the API encounters an error in its executing process, the error would be thrown and could be +caught. #### Example @@ -74,7 +79,8 @@ This API could be used to get the currently chapter and page information. #### Return type -This API would return a Promise object that resolves to an object that contains the current chapter and page. Its serialized JSON string is as below: +This API would return a Promise object that resolves to an object that contains the current chapter +and page. Its serialized JSON string is as below: ```json { @@ -118,7 +124,8 @@ This API could be used to select visualizations or groups on a dashboard consump #### Return type -This API would return a Promise object that resolves to void. If it encounters an error in its executing process, the error would be thrown and could be caught. +This API would return a Promise object that resolves to void. If it encounters an error in its +executing process, the error would be thrown and could be caught. #### Example @@ -137,7 +144,8 @@ try { #### Description -This API could be used to get currently selected visualizations and groups on a dashboard consumption page. +This API could be used to get currently selected visualizations and groups on a dashboard +consumption page. #### Class @@ -145,7 +153,8 @@ This API could be used to get currently selected visualizations and groups on a #### Return type -This API would return a Promise object that resolves to an object that contains the selected components. Its serialized JSON string is as below: +This API would return a Promise object that resolves to an object that contains the selected +components. Its serialized JSON string is as below: ```json { @@ -168,7 +177,8 @@ This API would return a Promise object that resolves to an object that contains } ``` -If the API encounters an error in its executing process, the error would be thrown and could be caught. +If the API encounters an error in its executing process, the error would be thrown and could be +caught. #### Example @@ -185,223 +195,267 @@ try { #### Description -The API details are identical to [Dossier.getDossierInstanceId()](../add-functionality/methods-and-properties#dossiergetdossierinstanceid) +The API details are identical to +[Dossier.getDossierInstanceId()](../add-functionality/methods-and-properties#dossiergetdossierinstanceid) ### `getCurrentPageVisualizationList()` #### Description -The API details are identical to [Dossier.getCurrentPageVisualizationList()](../add-functionality/add-nav#getcurrentpagevisualizationlist) +The API details are identical to +[Dossier.getCurrentPageVisualizationList()](../add-functionality/add-nav#getcurrentpagevisualizationlist) ### `changeVisualizationSize(props)` #### Description -The API details are identical to [Dossier.changeVisualizationSize(props)](../add-functionality/embed-vis#1-change-the-visualization-size) +The API details are identical to +[Dossier.changeVisualizationSize(props)](../add-functionality/embed-vis#1-change-the-visualization-size) ### `getCurrentPagePanelStacks()` #### Description -The API details are identical to [Dossier.getCurrentPagePanelStacks()](../add-functionality/panel-stacks#1-get-the-panel-stack-definitions-from-the-current-page) +The API details are identical to +[Dossier.getCurrentPagePanelStacks()](../add-functionality/panel-stacks#1-get-the-panel-stack-definitions-from-the-current-page) ### `switchPanel(panelKey)` #### Description -The API details are identical to [Dossier.switchPanel(panelKey)](../add-functionality/panel-stacks#2-switch-panels-on-the-current-page) +The API details are identical to +[Dossier.switchPanel(panelKey)](../add-functionality/panel-stacks#2-switch-panels-on-the-current-page) ### `getAvailableElements(vizKey)` #### Description -The API details are identical to [Dossier.getAvailableElements(visKey)](../add-functionality/attribute-element-selection#api-for-getting-available-elements) +The API details are identical to +[Dossier.getAvailableElements(visKey)](../add-functionality/attribute-element-selection#api-for-getting-available-elements) ### `selectVisualizationElements(props)` #### Description -The API details are identical to [Dossier.selectVizElement(props)](../add-functionality/attribute-element-selection#api-for-attribute-element-selection-in-a-dossier) +The API details are identical to +[Dossier.selectVizElement(props)](../add-functionality/attribute-element-selection#api-for-attribute-element-selection-in-a-dossier) ### `getTableContent()` #### Description -This API is deprecated. You can use [getDossierDefinition()](./dossier-consumption-page-apis#getdossierdefinition) to get table content. -The API details are identical to [Dossier.getTableContent()](../add-functionality/add-nav#gettablecontent). +This API is deprecated. You can use +[getDossierDefinition()](./dossier-consumption-page-apis#getdossierdefinition) to get table content. +The API details are identical to +[Dossier.getTableContent()](../add-functionality/add-nav#gettablecontent). ### `getChapterList()` #### Description -This API is deprecated. You can use [getDossierDefinition()](./dossier-consumption-page-apis#getdossierdefinition) to get table content. -The API details are identical to [Dossier.getChapterList()](../add-functionality/add-nav#getchapterlist). +This API is deprecated. You can use +[getDossierDefinition()](./dossier-consumption-page-apis#getdossierdefinition) to get table content. +The API details are identical to +[Dossier.getChapterList()](../add-functionality/add-nav#getchapterlist). ### `getCurrentChapter()` #### Description -This API is deprecated. You can use [getCurrentPageInfo()](./dossier-consumption-page-apis#getcurrentpageinfo) to get the current chapter and page information. -The API details are identical to [Dossier.getCurrentChapter()](../add-functionality/add-nav#getcurrentchapter). +This API is deprecated. You can use +[getCurrentPageInfo()](./dossier-consumption-page-apis#getcurrentpageinfo) to get the current +chapter and page information. The API details are identical to +[Dossier.getCurrentChapter()](../add-functionality/add-nav#getcurrentchapter). ### `getCurrentPage()` #### Description -This API is deprecated. You can use [getCurrentPageInfo()](./dossier-consumption-page-apis#getcurrentpageinfo) to get the current chapter and page information. -The API details are identical to [Dossier.getCurrentPage()](../add-functionality/add-nav#getcurrentpage). +This API is deprecated. You can use +[getCurrentPageInfo()](./dossier-consumption-page-apis#getcurrentpageinfo) to get the current +chapter and page information. The API details are identical to +[Dossier.getCurrentPage()](../add-functionality/add-nav#getcurrentpage). ### `getPageByNodeKey(nodeKey)` #### Description -This API is deprecated. You can use [EmbeddingContext.goToPage(pageInfo)](../embedding-context/#gotopagepageinfo) to navigate to a page without such preparations. -The API details are identical to [Dossier.getPageByNodeKey(nodeKey)](../add-functionality/add-nav#getpagebynodekeynodekey). +This API is deprecated. You can use +[EmbeddingContext.goToPage(pageInfo)](../embedding-context/#gotopagepageinfo) to navigate to a page +without such preparations. The API details are identical to +[Dossier.getPageByNodeKey(nodeKey)](../add-functionality/add-nav#getpagebynodekeynodekey). ### `goToPrevPage()` #### Description -The API details are identical to [Dossier.goToPrevPage()](../add-functionality/add-nav#gotoprevpage). +The API details are identical to +[Dossier.goToPrevPage()](../add-functionality/add-nav#gotoprevpage). ### `goToNextPage()` #### Description -The API details are identical to [Dossier.goToNextPage()](../add-functionality/add-nav#gotonextpage). +The API details are identical to +[Dossier.goToNextPage()](../add-functionality/add-nav#gotonextpage). ### `navigateToPage(page)` #### Description -The API details are identical to [Dossier.navigateToPage(page)](../add-functionality/add-nav#navigatetopagepage). +The API details are identical to +[Dossier.navigateToPage(page)](../add-functionality/add-nav#navigatetopagepage). ### `openFilterSummaryBar()` #### Description -The API details are identical to [Dossier.openFilterSummaryBar()](../add-functionality/add-nav#openfiltersummarybar). +The API details are identical to +[Dossier.openFilterSummaryBar()](../add-functionality/add-nav#openfiltersummarybar). ### `closeFilterSummaryBar()` #### Description -The API details are identical to [Dossier.closeFilterSummaryBar()](../add-functionality/add-nav#closefiltersummarybar). +The API details are identical to +[Dossier.closeFilterSummaryBar()](../add-functionality/add-nav#closefiltersummarybar). ### `filterSelectAllAttributes(filterJson)` #### Description -This API is deprecated. You can use [filterSelectAllAttributeElements(filterJson)](./dossier-consumption-page-apis#filterselectallattributeelementsfilterjson) instead. +This API is deprecated. You can use +[filterSelectAllAttributeElements(filterJson)](./dossier-consumption-page-apis#filterselectallattributeelementsfilterjson) +instead. -The API details are identical to [Dossier.filterSelectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterselectallattributesfilterjson). +The API details are identical to +[Dossier.filterSelectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterselectallattributesfilterjson). ### `filterSelectAllAttributeElements(filterJson)` #### Description -The API details are identical to [Dossier.filterSelectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterselectallattributesfilterjson). +The API details are identical to +[Dossier.filterSelectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterselectallattributesfilterjson). ### `filterDeselectAllAttributes(filterJson)` #### Description -This API is deprecated. You can use [filterDeselectAllAttributeElements(filterJson)](./dossier-consumption-page-apis#filterdeselectallattributeelementsfilterjson)instead. +This API is deprecated. You can use +[filterDeselectAllAttributeElements(filterJson)](./dossier-consumption-page-apis#filterdeselectallattributeelementsfilterjson)instead. -The API details are identical to [Dossier.filterDeselectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterdeselectallattributesfilterjson). +The API details are identical to +[Dossier.filterDeselectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterdeselectallattributesfilterjson). ### `filterDeselectAllAttributeElements(filterJson)` #### Description -The API details are identical to [Dossier.filterDeselectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterdeselectallattributesfilterjson). +The API details are identical to +[Dossier.filterDeselectAllAttributes(filterJson)](../add-functionality/filters#dossierfilterdeselectallattributesfilterjson). ### `filterSelectMultiAttributes(filterJson)` #### Description -The API details are identical to [Dossier.filterSelectMultiAttributes(filterJson)](../add-functionality/filters#dossierfilterselectmultiattributesfilterjson). +The API details are identical to +[Dossier.filterSelectMultiAttributes(filterJson)](../add-functionality/filters#dossierfilterselectmultiattributesfilterjson). ### `filterSelectSingleAttribute(filterJson)` #### Description -The API details are identical to [Dossier.filterSelectSingleAttribute(filterJson)](../add-functionality/filters#dossierfilterselectsingleattributefilterjson). +The API details are identical to +[Dossier.filterSelectSingleAttribute(filterJson)](../add-functionality/filters#dossierfilterselectsingleattributefilterjson). ### `filterSearchSingleAttribute(filterJson)` #### Description -The API details are identical to [Dossier.filterSearchSingleAttribute(filterJson)](../add-functionality/filters#dossierfiltersearchsingleattributefilterjson). +The API details are identical to +[Dossier.filterSearchSingleAttribute(filterJson)](../add-functionality/filters#dossierfiltersearchsingleattributefilterjson). ### `filterSearchMultiAttributes(filterJson)` #### Description -The API details are identical to [Dossier.filterSearchMultiAttributes(filterJson)](../add-functionality/filters#dossierfilterselectmultiattributesfilterjson). +The API details are identical to +[Dossier.filterSearchMultiAttributes(filterJson)](../add-functionality/filters#dossierfilterselectmultiattributesfilterjson). ### `filterSetDateRange(filterJson)` #### Description -The API details are identical to [Dossier.filterSetDateRange(filterJson)](../add-functionality/filters#dossierfiltersetdaterangefilterjson). +The API details are identical to +[Dossier.filterSetDateRange(filterJson)](../add-functionality/filters#dossierfiltersetdaterangefilterjson). ### `filterSetMetricQualByValue(filterJson)` #### Description -The API details are identical to [Dossier.filterSetMetricQualByValue(filterJson)](../add-functionality/filters#dossierfiltersetmetricqualbyvaluefilterjson). +The API details are identical to +[Dossier.filterSetMetricQualByValue(filterJson)](../add-functionality/filters#dossierfiltersetmetricqualbyvaluefilterjson). ### `filterSetMetricQualByRank(filterJson)` #### Description -The API details are identical to [Dossier.filterSetMetricQualByRank(filterJson)](../add-functionality/filters#dossierfiltersetmetricqualbyrankfilterjson). +The API details are identical to +[Dossier.filterSetMetricQualByRank(filterJson)](../add-functionality/filters#dossierfiltersetmetricqualbyrankfilterjson). ### `filterAttributeSingleSlider(filterJson)` #### Description -The API details are identical to [Dossier.filterAttributeSingleSlider(filterJson)](../add-functionality/filters#dossierfilterattributesinglesliderfilterjson). +The API details are identical to +[Dossier.filterAttributeSingleSlider(filterJson)](../add-functionality/filters#dossierfilterattributesinglesliderfilterjson). ### `filterAttributeMultiSlider(filterJson)` #### Description -The API details are identical to [Dossier.filterAttributeMultiSlider(filterJson)](../add-functionality/filters#dossierfilterattributemultisliderfilterjson). +The API details are identical to +[Dossier.filterAttributeMultiSlider(filterJson)](../add-functionality/filters#dossierfilterattributemultisliderfilterjson). ### `filterApplyAll()` #### Description -The API details are identical to [Dossier.filterApplyAll()](../add-functionality/filters#dossierfilterapplyall). +The API details are identical to +[Dossier.filterApplyAll()](../add-functionality/filters#dossierfilterapplyall). ### `filterClearAll()` #### Description -The API details are identical to [Dossier.filterClearAll()](../add-functionality/filters#dossierfilterclearall). +The API details are identical to +[Dossier.filterClearAll()](../add-functionality/filters#dossierfilterclearall). ### `filterClear(filterJson)` #### Description -The API details are identical to [Dossier.filterClear(filterJson)](../add-functionality/filters#dossierfilterclearfilterjson). +The API details are identical to +[Dossier.filterClear(filterJson)](../add-functionality/filters#dossierfilterclearfilterjson). ### `filterSetInclude(filterJson)` #### Description -The API details are identical to [Dossier.filterSetInclude(filterJson)](../add-functionality/filters#dossierfiltersetincludefilterjson). +The API details are identical to +[Dossier.filterSetInclude(filterJson)](../add-functionality/filters#dossierfiltersetincludefilterjson). ### `filterSetExclude(filterJson)` #### Description -The API details are identical to [Dossier.filterSetExclude(filterJson)](../add-functionality/filters#dossierfiltersetexcludefilterjson). +The API details are identical to +[Dossier.filterSetExclude(filterJson)](../add-functionality/filters#dossierfiltersetexcludefilterjson). ### `getFilterList()` #### Description -The API details are identical to [Dossier.getFilterList()](../add-functionality/filters#retrieve-filters-after-a-dashboard-is-rendered). +The API details are identical to +[Dossier.getFilterList()](../add-functionality/filters#retrieve-filters-after-a-dashboard-is-rendered). diff --git a/docs/embedding-context/embedding-context.md b/docs/embedding-context/embedding-context.md index 35a6069..fe3939b 100644 --- a/docs/embedding-context/embedding-context.md +++ b/docs/embedding-context/embedding-context.md @@ -1,6 +1,8 @@ --- title: Embedding context -description: Describes the object that is used for manipulating the embeded pages in the whole embedding lifecycle. +description: + Describes the object that is used for manipulating the embeded pages in the whole embedding + lifecycle. --- The `embeddingContext` object a service object that would persist in the whole embedding lifecycle. @@ -18,20 +20,26 @@ try { } ``` -The `embedLibraryPage()` function above can be replaced to the other functions under the `embeddingContexts` namespace, include: +The `embedLibraryPage()` function above can be replaced to the other functions under the +`embeddingContexts` namespace, include: - `embedDossierConsumptionPage(props)` - `embedReportPage(props)` -This `embeddingContext` object could be used when the user navigates between different types of pages. It has several fields: +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 dashboard consumption page. The detailed APIs could be seen in [Dashboard consumption page APIs](./dossier-consumption-page-apis.md) +- `documentConsumption`: used for call the APIs that interact with the document consumption page. The detailed APIs could be seen in [Document consumption page APIs](./document-consumption-page-apis.md) - `botConsumptionService` used for call the APIs that interact withe the bot consumption page. The detailed APIs could be seen in [Bot consumption page APIs](./bot-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. +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. -Besides the APIs on different types of pages, there are still some APIs that could be used on all kinds of pages, so we put them under the `embeddingContext` object. Include: +Besides the APIs on different types of pages, there are still some APIs that could be used on all +kinds of pages, so we put them under the `embeddingContext` object. Include: ## Embedding context APIs @@ -43,7 +51,8 @@ Besides the APIs on different types of pages, there are still some APIs that cou #### Description -See the identical function in [Event handlers](../add-functionality/add-event#registereventhandlerevtname-handler). +See the identical function in +[Event handlers](../add-functionality/add-event#registereventhandlerevtname-handler). ### `removeEventHandler(evtName, handler)` @@ -53,7 +62,8 @@ See the identical function in [Event handlers](../add-functionality/add-event#re #### Description -See the identical function in [Event handlers](../add-functionality/add-event#removeeventhandlerevtname-handler). +See the identical function in +[Event handlers](../add-functionality/add-event#removeeventhandlerevtname-handler). ### `addCustomErrorHandler(handler, showErrorPopup)` @@ -63,7 +73,8 @@ See the identical function in [Event handlers](../add-functionality/add-event#re #### Description -See the identical function in [Custom error handling after dashboard 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-dashboard-creation). ### `removeCustomErrorHandler()` @@ -73,7 +84,8 @@ See the identical function in [Custom error handling after dashboard creation](. #### Description -See the identical function in [Custom error handling after dashboard 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-dashboard-creation). ### `addSessionErrorHandler(handler)` @@ -83,7 +95,8 @@ See the identical function in [Custom error handling after dashboard creation](. #### Description -See the identical function in [Session error handling after dashboard 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-dashboard-creation). ### `removeSessionErrorhandler()` @@ -93,7 +106,8 @@ See the identical function in [Session error handling after dashboard creation]( #### Description -See the identical function in [Session error handling after dashboard 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-dashboard-creation). ### `goToPage(pageInfo)` @@ -127,7 +141,8 @@ This API would return a Promise that resolves to an object, whose serialized jso } ``` -The value of the `redirect` field denotes the page is changed or not. For the case that input `pageInfo` points to the current page, the value of `redirect` would be `false`. +The value of the `redirect` field denotes the page is changed or not. For the case that input +`pageInfo` points to the current page, the value of `redirect` would be `false`. If it encounters an error in its executing process, the error would be thrown and could be caught. diff --git a/docs/embedding-context/library-page-apis.md b/docs/embedding-context/library-page-apis.md index 3eec51e..22f7c48 100644 --- a/docs/embedding-context/library-page-apis.md +++ b/docs/embedding-context/library-page-apis.md @@ -1,11 +1,13 @@ --- title: Library page APIs -description: Describes which Embedding SDK APIs are available on the MicroStrategy Library home page. +description: Describes which Embedding SDK APIs are available on the Strategy Library home page. --- -The `LibraryPage` object is the manipulator of the MicroStrategy Library home page. It could be got by `embeddingContext.libraryPage`. +The `LibraryPage` object is the manipulator of the Strategy Library home page. It could be got by +`embeddingContext.libraryPage`. -The details of the `embeddingContext` object could be seen in [Embedding context](./embedding-context.md). +The details of the `embeddingContext` object could be seen in +[Embedding context](./embedding-context.md). The APIs under Library page object are as below. @@ -23,7 +25,8 @@ This API is used for getting all the group items under "My Groups". #### Return type -This API would return a Promise object that resolves to an object that contains the information of all groups contained in “My Groups“ and “Default Groups“. Its serialized JSON string is as below: +This API would return a Promise object that resolves to an object that contains the information of +all groups contained in “My Groups“ and “Default Groups“. Its serialized JSON string is as below: ```json [ @@ -56,7 +59,8 @@ This API is used for getting all the group items under "Default Groups". #### Return type -This API would return a Promise object that resolves to an object that contains the information of all groups contained in “My Groups“ and “Default Groups“. Its serialized JSON string is as below: +This API would return a Promise object that resolves to an object that contains the information of +all groups contained in “My Groups“ and “Default Groups“. Its serialized JSON string is as below: ```json [ diff --git a/docs/index.md b/docs/index.md index 7bef34a..e2d501d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,34 @@ --- title: Introduction to the Embedding SDK slug: / -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. +description: + The Embedding SDK allows you to quickly integrate a Strategy 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 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 Strategy 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 dashboard. -1. In the initial page of your web application, add a link to the MicroStrategy JavaScript Embedding SDK. +1. In the initial page of your web application, add a link to the Strategy JavaScript Embedding SDK. ```html ``` - Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual MicroStrategy Library Server URL, e.g., [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). + Replace `{YOUR_LIBRARY_SERVER_URL}` with your actual Strategy Library Server URL, e.g., + [https://demo.microstrategy.com/MicroStrategyLibrary](https://demo.microstrategy.com/MicroStrategyLibrary). :::tip - If the application server is different from the server running the MicroStrategyLibrary application, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](./config.md). + If the application server is different from the server running the StrategyLibrary application, + you may need to + [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](./config.md). ::: @@ -40,11 +50,15 @@ There are three basic steps for embedding a dashboard. :::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 dashboard. + 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. ::: -To help you get started, we have provided a number of simple applications with sample code and explanations. +To help you get started, we have provided a number of simple applications with sample code and +explanations. - [Support for different authentication environments](./support-for-different-authentication-environments/support-for-different-authentication-environments.md) @@ -52,10 +66,13 @@ To help you get started, we have provided a number of simple applications with s - [Add functionality](./add-functionality/add-functionality.md) - Examples that add functionality, such as controlling navigation, retrieving and applying filters, setting properties, and managing events like page changes + Examples that add functionality, such as controlling navigation, retrieving and applying filters, + setting properties, and managing events like page changes - [Embedding SDK Playground](https://microstrategy.github.io/playground/) - A playground for developers to build impactful, interactive analytics experiences that integrate seamlessly with websites and applications. + A playground for developers to build impactful, interactive analytics experiences that integrate + seamlessly with websites and applications. -To see changes to the Embedding SDK in the current release, refer to [What's new](./whats-new-in-the-embedding-sdk.md). +To see changes to the Embedding SDK in the current release, refer +to [What's new](./whats-new-in-the-embedding-sdk.md). diff --git a/docs/native-embedding-architecture/apply-filter.md b/docs/native-embedding-architecture/apply-filter.md index 213fd73..466ee56 100644 --- a/docs/native-embedding-architecture/apply-filter.md +++ b/docs/native-embedding-architecture/apply-filter.md @@ -1,11 +1,18 @@ --- title: Retrieve and apply filters -description: Filters can be applied both during the execution of an embedded dashboard 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 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. +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, Strategy only supports attribute element list +selectors. Let's say you already have the `MstrEnvironment` and `MstrDossier` objects: @@ -35,7 +42,10 @@ try { ## Get available filter elements -To apply filters to the dashboard, the client may need to get the list of available attribute elements of the filters or selectors. You can use the `MstrDossier.getFilterAvailableElements()` function in the Native Embedding SDK to retrieve the available attribute elements of the filters or selectors. +To apply filters to the dashboard, the client may need to get the list of available attribute +elements of the filters or selectors. You can use the `MstrDossier.getFilterAvailableElements()` +function in the Native Embedding SDK to retrieve the available attribute elements of the filters or +selectors. | `getFilterAvailableElements()` | | | ------------------------------ | -------------------------------------------------------- | @@ -76,11 +86,14 @@ 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()` function to manipulate it. -:::note -For filters and selectors, we currently only support manipulating the selector type of the attribute element list. -::: +:::note For filters and selectors, we currently only support manipulating the selector type of the +attribute element list. ::: | `applyFilter()` | | | --------------- | --------------------------------------------- | @@ -96,7 +109,11 @@ 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 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. +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 +137,11 @@ try { #### On-Page selectors -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. +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,11 +165,17 @@ try { #### Visualizations used as filters -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. +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 - To select multiple attribute elements in the visualizations used as filters, you can use `MstrDossier.applyFilter()` with the following input: + To select multiple attribute elements in the visualizations used as filters, you can use + `MstrDossier.applyFilter()` with the following input: ```js try { @@ -180,7 +207,10 @@ For a visualization used as a filter, you need its key from the dashboard defini - metric element selection - To select multiple metric elements in the visualizations used as filters, you need to provide the full list of attributes in the visualization and every metric element selection should be the combination of attribute elements from every attribute. You can use `MstrDossier.applyFilter()` with the following input: + To select multiple metric elements in the visualizations used as filters, you need to provide the + full list of attributes in the visualization and every metric element selection should be the + combination of attribute elements from every attribute. You can use `MstrDossier.applyFilter()` + with the following input: ```js try { @@ -330,7 +360,8 @@ To apply selections to on-page selectors, use the same input as chapter-level fi - Select attribute elements of the visualization -Select the `June, April` elements of the `Month of Year` attribute and the `2014` element of the `Year` attribute. +Select the `June, April` elements of the `Month of Year` attribute and the `2014` element of the +`Year` attribute. ```js try { diff --git a/docs/native-embedding-architecture/destroy-multiple-viz.md b/docs/native-embedding-architecture/destroy-multiple-viz.md index 7813620..94a6dc5 100644 --- a/docs/native-embedding-architecture/destroy-multiple-viz.md +++ b/docs/native-embedding-architecture/destroy-multiple-viz.md @@ -7,7 +7,9 @@ description: Destroy visualizations on a page ## Purpose -After using [Native Embedding SDK](embed-multiple-viz.md) to embed multiple visualizations in a client's webpage, you can also destroy them to clear your page, or embed the visualizations from another dossier. +After using [Native Embedding SDK](embed-multiple-viz.md) to embed multiple visualizations in a +client's webpage, you can also destroy them to clear your page, or embed the visualizations from +another dossier. ## Example code @@ -67,8 +69,11 @@ This piece of code contains a function from the following namespace and classes: - [`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. + This class is the object returned from the + `microstrategy.embeddingComponent.environments.create()` function, which is responsible for + creating and destroying `MstrDossier` objects. - [`MstrDossier`](mstr-dossier.md) Class - This class is returned from the `MstrEnvironment.loadDossier()` function, which is responsible for showing visualizations in containers. + This class is returned from the `MstrEnvironment.loadDossier()` function, which is responsible for + showing visualizations in containers. diff --git a/docs/native-embedding-architecture/dossier-info-api.md b/docs/native-embedding-architecture/dossier-info-api.md index fa9ca87..92698d6 100644 --- a/docs/native-embedding-architecture/dossier-info-api.md +++ b/docs/native-embedding-architecture/dossier-info-api.md @@ -1,11 +1,16 @@ --- title: Getting dashboard info via APIs -description: You can get dashboard information, such as definition and visualization data, with Native Embedding SDK. +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 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. +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: @@ -29,7 +34,8 @@ try { ## Get dashboard definition -You can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to retrieve the definition of the dashboard. +You can use the `MstrDossier.getDossierDefinition()` function in the Native Embedding SDK to +retrieve the definition of the dashboard. | `getDossierDefinition()` | | | ------------------------ | ------------------------------------ | @@ -110,7 +116,8 @@ try { ## Get visualization data -You can use the `MstrDossier.getVisualizationData()` function in the Native Embedding SDK to retrieve the data of a single visualization. +You can use the `MstrDossier.getVisualizationData()` function in the Native Embedding SDK to +retrieve the data of a single visualization. | `getVisualizationData()` | | | ------------------------ | -------------------------------------------------------- | diff --git a/docs/native-embedding-architecture/embed-bot-visualizations.md b/docs/native-embedding-architecture/embed-bot-visualizations.md index bfdb6fb..3607f34 100644 --- a/docs/native-embedding-architecture/embed-bot-visualizations.md +++ b/docs/native-embedding-architecture/embed-bot-visualizations.md @@ -3,11 +3,12 @@ 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. +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 @@ -24,8 +25,8 @@ You must use the js bundle, `native-embedding-sdk.js`: ### Embed visualizations from one bot -To embed multiple visualizations from one dashboard, after referring `native-embedding-sdk.js`, use the code shown below: -(please use `` character encoding tag) +To embed multiple visualizations from one dashboard, after referring `native-embedding-sdk.js`, use +the code shown below: (please use `` character encoding tag) ```html @@ -108,7 +109,8 @@ To embed multiple visualizations from one dashboard, after referring `native-emb ### 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: +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 { @@ -142,8 +144,11 @@ This piece of code contains a function from the following namespace and classes: - [`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. + 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. + 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 ce5d2c9..2c9a66a 100644 --- a/docs/native-embedding-architecture/embed-multiple-viz.md +++ b/docs/native-embedding-architecture/embed-multiple-viz.md @@ -7,11 +7,15 @@ 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 dashboard 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). +Custom visualizations are also supported. To embed custom visualizations, you should deploy them on +Strategy Library first. To deploy custom visualizations on Strategy Library, refer to +[Deploy a custom visualization](https://www2.microstrategy.com/producthelp/Current/VisSDK/Content/topics/HTML5/Deploying_a_custom_visualization.htm). -Here is a live demo for this in [Embedding Playground](https://microstrategy.github.io/playground/?example=g28). +Here is a live demo for this in +[Embedding Playground](https://microstrategy.github.io/playground/?example=g28). ## Requirements @@ -30,8 +34,8 @@ 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 dashboard, after referring `native-embedding-sdk.js`, use the code shown below: -(please use `` character encoding tag) +To embed multiple visualizations from one dashboard, after referring `native-embedding-sdk.js`, use +the code shown below: (please use `` character encoding tag) ```html @@ -105,12 +109,14 @@ To embed multiple visualizations from one dashboard, after referring `native-emb ``` -`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`. +`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`. ### Display a loading bar during the entire visualization embedding process -During the existing visualization embedding process, the Native Embedding SDK knows which container to use when you call the `dossier.refresh` API, and the loading bar appears at that time. -If you want to see the loading bar during the entire embedding process, create an implementation like this: +During the existing visualization embedding process, the Native Embedding SDK knows which container +to use when you call the `dossier.refresh` API, and the loading bar appears at that time. If you +want to see the loading bar during the entire embedding process, create an implementation like this: ```html @@ -143,10 +149,12 @@ If you want to see the loading bar during the entire embedding process, create a } ``` -You need to set the height and length with the container element. -We haven't had a default height and length when we call `dossier.refresh` API to embed a viz. If the container element hasn't had the height and length, you can't see your embed visualization. +You need to set the height and length with the container element. We haven't had a default height +and length when we call `dossier.refresh` API to embed a viz. If the container element hasn't had +the height and length, you can't see your embed visualization. -Find the `getAuthToken` function in [the Native Embedding SDK doc](./embed-multiple-viz.md#example-code) +Find the `getAuthToken` function in +[the Native Embedding SDK doc](./embed-multiple-viz.md#example-code) ```js try { @@ -196,7 +204,8 @@ try { ### Embed visualizations from multiple dossiers -If you want to embed visualizations from multiple dossiers, you must turn on this functionality by setting the feature flag as shown below before calling the APIs: +If you want to embed visualizations from multiple dossiers, you must turn on this functionality by +setting the feature flag as shown below before calling the APIs: ```js window.microstrategy.nativeEmbedding.featureFlags.multipleDossiers = true; @@ -280,7 +289,8 @@ After you embed multiple visualizations on a page, you can do some deeper manipu - [Visualization manipulation on graphics](vis-manipulation.md) - This introductory shows what kinds of manipulation can we do and some behavior in the Native Embedding SDK. + This introductory shows what kinds of manipulation can we do and some behavior in the Native + Embedding SDK. - [Add event handling](event-handling.md) @@ -288,7 +298,8 @@ After you embed multiple visualizations on a page, you can do some deeper manipu - [Retrieve and apply filters](apply-filter.md) - 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. + 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 dashboard info via APIs](dossier-info-api.md) @@ -304,8 +315,11 @@ This piece of code contains a function from the following namespace and classes: - [`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. + This class is the object returned from the + `microstrategy.embeddingComponent.environments.create()` function, which is responsible for + creating and destroying `MstrDossier` objects. - [`MstrDossier`](mstr-dossier.md) Class - This class is returned from the `MstrEnvironment.loadDossier()` function, which is responsible for showing visualizations in containers. + This class is returned from the `MstrEnvironment.loadDossier()` function, which is responsible for + showing visualizations in containers. diff --git a/docs/native-embedding-architecture/embedding-components.md b/docs/native-embedding-architecture/embedding-components.md index 1a9f186..3f2e7bc 100644 --- a/docs/native-embedding-architecture/embedding-components.md +++ b/docs/native-embedding-architecture/embedding-components.md @@ -17,10 +17,10 @@ This is the entry point of the Native Embedding SDK. #### Input Parameters -| Parameter Name | Data Type | Description | Is Required | -| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| props.serverUrl | String | The base URL of the Library server | true | -| props.getAuthToken | function | The function for getting the login token.
This function is similar to `getAuthToken` in `microstrategy.dossier.create`.
In 2021 Update 9, MicroStrategy only supports auth token. You can get the auth token with any auth mode. | true | +| Parameter Name | Data Type | Description | Is Required | +| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| props.serverUrl | String | The base URL of the Library server | true | +| props.getAuthToken | function | The function for getting the login token.
This function is similar to `getAuthToken` in `microstrategy.dossier.create`.
In 2021 Update 9, Strategy only supports auth token. You can get the auth token with any auth mode. | true | #### Response @@ -28,7 +28,8 @@ This API returns a promise object that resolves to a `MstrEnvironment` object. #### Example -Find the `getAuthToken` function in [the Native Embedding SDK doc](./embed-multiple-viz.md#example-code) +Find the `getAuthToken` function in +[the Native Embedding SDK doc](./embed-multiple-viz.md#example-code) ```js try { diff --git a/docs/native-embedding-architecture/event-handling.md b/docs/native-embedding-architecture/event-handling.md index 8435193..ff33e18 100644 --- a/docs/native-embedding-architecture/event-handling.md +++ b/docs/native-embedding-architecture/event-handling.md @@ -1,13 +1,23 @@ --- title: Add event handling -description: Events allow the custom application page to listen to events from the embedded visualizations. You can listen to these events and provide event handler functions to respond to them. For example, you can add code to capture element selection events from embedded visualizations and apply them as a filter. +description: + Events allow the custom application page to listen to events from the embedded visualizations. You + can listen to these events and provide event handler functions to respond to them. For example, + you can add code to capture element selection events from embedded visualizations and apply them + as a filter. --- -Event handling allows a custom application page to listen to events from embedded visualizations. You can listen to these events and handle the events in the handler functions. For example, you can add code to capture element selection events from embedded visualizations and apply them as a filter. +Event handling allows a custom application page to listen to events from embedded visualizations. +You can listen to these events and handle the events in the handler functions. For example, you can +add code to capture element selection events from embedded visualizations and apply them as a +filter. -Let's say you already have `MstrEnvironment` and `MstrDossier` objects. Then you can use `MstrDossier.registerEventHandler` to register handlers for events. You can also use `MstrDossier.registerErrorHandler` to register handlers for errors that occur during graphic manipulations of embedded visualizations. +Let's say you already have `MstrEnvironment` and `MstrDossier` objects. Then you can use +`MstrDossier.registerEventHandler` to register handlers for events. You can also use +`MstrDossier.registerErrorHandler` to register handlers for errors that occur during graphic +manipulations of embedded visualizations. ```js try { @@ -60,7 +70,8 @@ There is a method for registering an error handler. #### Description -Register the `handler` error handler to handle errors during graphic manipulations of embedded visualizations. +Register the `handler` error handler to handle errors during graphic manipulations of embedded +visualizations. ## Events @@ -78,7 +89,8 @@ Raised when elements in visualizations are selected or unselected in graphics. #### Content -Attribute element list or metric element list for the currently selected elements in the visualization. +Attribute element list or metric element list for the currently selected elements in the +visualization. #### Code example @@ -189,7 +201,8 @@ The event data passed to the registered event handler is as follows: - map layer element selection - For map visualizations, each layer has its corresponding attribute element selection object or metric element selection object. + For map visualizations, each layer has its corresponding attribute element selection object or + metric element selection object.
Example for map layer element selection diff --git a/docs/native-embedding-architecture/mstr-bot-visualization.md b/docs/native-embedding-architecture/mstr-bot-visualization.md index 6376f8e..49c3897 100644 --- a/docs/native-embedding-architecture/mstr-bot-visualization.md +++ b/docs/native-embedding-architecture/mstr-bot-visualization.md @@ -3,9 +3,10 @@ title: MstrBotVisualization class description: MstrBotVisualization class --- - + -The object returned from the `MstrBot.renderVisualization()` function, which allows access to the MicroStrategy bot visualization object. +The object returned from the `MstrBot.renderVisualization()` function, which allows access to the +Strategy bot visualization object. ## APIs diff --git a/docs/native-embedding-architecture/mstr-bot.md b/docs/native-embedding-architecture/mstr-bot.md index a6465e7..7a34e0f 100644 --- a/docs/native-embedding-architecture/mstr-bot.md +++ b/docs/native-embedding-architecture/mstr-bot.md @@ -3,9 +3,10 @@ title: MstrBot class description: MstrBot class --- - + -The object returned from the `MstrEnvironment.loadBot()` function, which allows access to the MicroStrategy bot object. +The object returned from the `MstrEnvironment.loadBot()` function, which allows access to the +Strategy bot object. ## APIs @@ -21,7 +22,8 @@ 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: +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: diff --git a/docs/native-embedding-architecture/mstr-dossier.md b/docs/native-embedding-architecture/mstr-dossier.md index 6a24ce4..a532ec4 100644 --- a/docs/native-embedding-architecture/mstr-dossier.md +++ b/docs/native-embedding-architecture/mstr-dossier.md @@ -5,7 +5,8 @@ description: MstrDossier class -The object returned from the `MstrEnvironment.loadDossier()` function, which allows access to the MicroStrategy dashboard object. +The object returned from the `MstrEnvironment.loadDossier()` function, which allows access to the +Strategy dashboard object. ## APIs diff --git a/docs/native-embedding-architecture/mstr-environment.md b/docs/native-embedding-architecture/mstr-environment.md index bfeb544..7c1d4e8 100644 --- a/docs/native-embedding-architecture/mstr-environment.md +++ b/docs/native-embedding-architecture/mstr-environment.md @@ -5,7 +5,10 @@ description: MstrEnvironment class -The instance of this class is the object returned from the `microstrategy.embeddingComponent.environments.create()` function, which allows access to the MicroStrategy application. `MstrEnvironment` class represents one MicroStrategy Library Application identified by a URL. +The instance of this class is the object returned from the +`microstrategy.embeddingComponent.environments.create()` function, which allows access to the +Strategy application. `MstrEnvironment` class represents one Strategy Library Application identified +by a URL. ## APIs @@ -24,7 +27,8 @@ The instance of this class is the object returned from the `microstrategy.embedd | props.instanceId | String | The dashboard instance ID, if it already exists. | false | | props.applicationId | String | the dashboard application ID, if not specified, the default application will be used | false | -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. +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 @@ -104,7 +108,8 @@ try { | 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 | | props.applicationId | String | the bot application ID, if not specified, the default application will be used | false | -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. +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 diff --git a/docs/native-embedding-architecture/native-embedding-architecture.md b/docs/native-embedding-architecture/native-embedding-architecture.md index 880d5d2..d65a3b6 100644 --- a/docs/native-embedding-architecture/native-embedding-architecture.md +++ b/docs/native-embedding-architecture/native-embedding-architecture.md @@ -5,12 +5,15 @@ description: The Native Embedding SDK -To improve performance when embedding multiple visualizations, use the Native Embedding SDK. See the following pages for more information: +To improve performance when embedding multiple visualizations, use the Native Embedding SDK. See the +following pages for more information: - [Embed multiple visualizations on a page](embed-multiple-viz.md) - This introductory sample embeds multiple visualizations in a simple application. This sample can be used as is. + This introductory sample embeds multiple visualizations in a simple application. This sample can + be used as is. - [Destroy visualizations on a page](destroy-multiple-viz.md) - This introductory sample shows how to destroy the current visualizations before embedding a new set of visualizations. + This introductory sample shows how to destroy the current visualizations before embedding a new + set of visualizations. diff --git a/docs/native-embedding-architecture/vis-manipulation.md b/docs/native-embedding-architecture/vis-manipulation.md index 7523f34..ca97459 100644 --- a/docs/native-embedding-architecture/vis-manipulation.md +++ b/docs/native-embedding-architecture/vis-manipulation.md @@ -5,11 +5,15 @@ 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 dashboard pages. +The embedded visualizations can be manipulated the same way as they are seen on Strategy 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 +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 -Let's say we already have the `MstrEnvironment` and `MstrDossier` objects, and embedded visualizations have been rendered. +Let's say we already have the `MstrEnvironment` and `MstrDossier` objects, and embedded +visualizations have been rendered. ```js try { @@ -37,21 +41,33 @@ try { ## Element selection in the visualization -Once the embedded visualizations are rendered, clicking on the elements in the visualization highlights the selected attribute or metric elements. Additionally, when the visualization is a filtered source that targets other embedded visualizations on the same page, selecting an element triggers filtering, and all target visualizations are updated to display the latest data. However, if the target visualizations are on a different page than the filtered source visualization, the auto-refresh feature is not triggered. +Once the embedded visualizations are rendered, clicking on the elements in the visualization +highlights the selected attribute or metric elements. Additionally, when the visualization is a +filtered source that targets other embedded visualizations on the same page, selecting an element +triggers filtering, and all target visualizations are updated to display the latest data. However, +if the target visualizations are on a different page than the filtered source visualization, the +auto-refresh feature is not triggered. ## Right click menu in the visualization -After the embedded visualizations have been rendered, you can right-click on the visualization. Normally, this manipulation triggers a pop-up menu and you can click a menu option to apply an action. +After the embedded visualizations have been rendered, you can right-click on the visualization. +Normally, this manipulation triggers a pop-up menu and you can click a menu option to apply an +action. -MicroStrategy supports most of the manipulations in the right-click menu within Library, except clicking the `Show Data` and `Go To Page` items in the right-click menu of visualization. These two icons are hidden. +Strategy supports most of the manipulations in the right-click menu within Library, except clicking +the `Show Data` and `Go To Page` items in the right-click menu of visualization. These two icons are +hidden. ## Click, drag, and scroll in the visualization -After the embedded visualizations have been rendered, you can click the icon to open a pop-up menu with multiple actions you can select. -You can also click a column line and drag it, click the legend and drag it, scroll down to load more data, and so on. +After the embedded visualizations have been rendered, you can click the icon to open a pop-up menu +with multiple actions you can select. You can also click a column line and drag it, click the legend +and drag it, scroll down to load more data, and so on. -MicroStrategy supports most of the manipulations within Library, except clicking the menu or maximize icons in the top-right corner of visualization. These two icons are hidden. +Strategy supports most of the manipulations within Library, except clicking the menu or maximize +icons in the top-right corner of visualization. These two icons are hidden. ## How actions affect the loading bar -When interacting with the visualization, if any action sends an XHR request, the loading icon overloads all of the visualizations in the same environment. +When interacting with the visualization, if any action sends an XHR request, the loading icon +overloads all of the visualizations in the same environment. diff --git a/docs/playground.md b/docs/playground.md index 5fe62fb..5a9d70a 100644 --- a/docs/playground.md +++ b/docs/playground.md @@ -1,21 +1,33 @@ --- title: Embedding SDK Playground -description: MicroStrategy’s Embedding SDK Playground is the one-stop shop for developers to build impactful, interactive analytics experiences that integrate seamlessly with websites and applications. +description: + Strategy’s Embedding SDK Playground is the one-stop shop for developers to build impactful, + interactive analytics experiences that integrate seamlessly with websites and applications. --- -MicroStrategy’s Embedding SDK Playground is the one-stop shop for developers to build impactful, interactive analytics experiences that integrate seamlessly with websites and applications. +Strategy’s Embedding SDK Playground is the one-stop shop for developers to build impactful, +interactive analytics experiences that integrate seamlessly with websites and applications. -Just use the intuitive drag-and-drop interfaces to define the perfect user experience, test it out in real time, and then let the platform automatically generate the code for you. You’ll turn your application into platform for Intelligence Everywhere in no time. +Just use the intuitive drag-and-drop interfaces to define the perfect user experience, test it out +in real time, and then let the platform automatically generate the code for you. You’ll turn your +application into platform for Intelligence Everywhere in no time. -Start building your application using the [Embedding SDK Playground](https://microstrategy.github.io/playground/). The [Playground User Manual](https://github.com/MicroStrategy/playground) provides the instructions for how to get started. +Start building your application using the +[Embedding SDK Playground](https://microstrategy.github.io/playground/). The +[Playground User Manual](https://github.com/MicroStrategy/playground) provides the instructions for +how to get started. ![Embedding SDK Playground](./images/embedded-analytics-sandbox.png) -There are four types of embedding use cases in [Embedding SDK Playground](https://microstrategy.github.io/playground/): Bot, Dashboard, Visualization, and Library. For each type, corresponding operations and examples are filtered and displayed when the embedding type is selected. +There are four types of embedding use cases in +[Embedding SDK Playground](https://microstrategy.github.io/playground/): Bot, Dashboard, +Visualization, and Library. For each type, corresponding operations and examples are filtered and +displayed when the embedding type is selected. ## Examples in playground -You can view examples in the Embedding SDK Playground by opening the Examples Gallery from "Start Over" button. Please save your work before opening an example. +You can view examples in the Embedding SDK Playground by opening the Examples Gallery from "Start +Over" button. Please save your work before opening an example. Here are some examples in the gallery so far. diff --git a/docs/samples.md b/docs/samples.md index bad18a6..a9b1ec4 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -1,8 +1,17 @@ --- title: More examples -description: There are examples hosted on [GitHub](https://microstrategy.github.io/playground/), from the simple example to showcase one specific feature of Embedding SDK to more complicated application with a lot of integration with MicroStrategy's REST API and third-party SDK. +description: + There are examples hosted on [GitHub](https://microstrategy.github.io/playground/), from the + simple example to showcase one specific feature of Embedding SDK to more complicated application + with a lot of integration with Strategy's REST API and third-party SDK. --- -There are examples hosted on [GitHub](https://microstrategy.github.io/playground/), from the simple example to showcase one specific feature of Embedding SDK to more complicated application with a lot of integration with MicroStrategy's REST API and third-party SDK. +There are examples hosted on [GitHub](https://microstrategy.github.io/playground/), from the simple +example to showcase one specific feature of Embedding SDK to more complicated application with a lot +of integration with Strategy's REST API and third-party SDK. -MicroStrategy REST API is the backbone of MicroStrategy’s open architecture. MicroStrategy REST API is widely used in the examples. For more information about MicroStrategy REST API, please visit [the documentation](https://microstrategy.github.io/rest-api-docs/), play with the live [API Explorer](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html), and play with our [REST API Playground](https://github.com/MicroStrategy/rest-api-playground). +Strategy REST API is the backbone of Strategy’s open architecture. Strategy REST API is widely used +in the examples. For more information about Strategy REST API, please visit +[the documentation](https://microstrategy.github.io/rest-api-docs/), play with the live +[API Explorer](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html), and play +with our [REST API Playground](https://github.com/MicroStrategy/rest-api-playground). diff --git a/docs/support-for-different-authentication-environments/authentication-saml.md b/docs/support-for-different-authentication-environments/authentication-saml.md index a115df5..8e7dade 100644 --- a/docs/support-for-different-authentication-environments/authentication-saml.md +++ b/docs/support-for-different-authentication-environments/authentication-saml.md @@ -1,11 +1,14 @@ --- title: Use SAML or OIDC authentication -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. +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 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 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/playground/?example=g17). Also check out [other examples](https://microstrategy.github.io/playground). +A live example can be seen on [GitHub](https://microstrategy.github.io/playground/?example=g17). +Also check out [other examples](https://microstrategy.github.io/playground). ## The workflow @@ -13,29 +16,49 @@ Here is the workflow of the example. 1. Client Application checks if auth token is still valid. If yes, jumps to Step 4. -1. Client Application opens the MicroStrategy Library Web login page (`https://[Your MicroStrategy Environment]/MicroStrategyLibrary/auth/login-dialog.jsp`) in a new tab. The login page will be responsible for showing a login dialog. +1. Client Application opens the Strategy Library Web login page + (`https://[Your Strategy Environment]/MicroStrategyLibrary/auth/login-dialog.jsp`) in a new tab. + The login page will be responsible for showing a login dialog. -1. After the user finishes logging in, the login page will send a JavaScript message to inform the Client Application. +1. After the user finishes logging in, the login page will send a JavaScript message to inform the + Client Application. -1. The Client Application gets the message, fetches the auth token, and uses it to make REST API calls or uses it in MicroStrategy’s Embedding SDK. +1. The Client Application gets the message, fetches the auth token, and uses it to make REST API + calls or uses it in Strategy’s Embedding SDK. You may encounter some difficulties in this workflow: -- The MicroStrategy Library Web login page couldn't be opened in a new tab. +- The Strategy Library Web login page couldn't be opened in a new tab. - This might be caused by your Chrome site settings doesn't allow pop-ups. - - In this case, you will see an icon on the right of location bar, which notifies you the pop-ups are blocked: - ![pop-ups are blocked](../images/popup-blocked.png) - You need to unblock the pop-ups like this: - ![unblock pop-ups](../images/unblock-popup.png) -- The user finishes logging in, but the Client Application doesn't proceed. The MicroStrategy Library Web login page isn't closed and the embeded dossier doesn't show. - - This might be caused by your strict CSP settings. If your [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)(Cross-Origin-Opener-Policy) setting is [same-origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy#same-origin), the MicroStrategy Library Web login page can't get the Client Application window so can't send messages to it. - - In this case, you need to change your COOP setting to [unsafe-none](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy#unsafe-none), which is the default value. Then the login process will work. - -## For MicroStrategy ONE June 2024 or after - -In MicroStrategy ONE June 2024, we add the [partitioned cookie change](../config#the-partitioned-cookie-change) to enable the customer to use the Embedding SDK even if third-party cookies are blocked. But if third-party cookies are blocked, the old SAML or OIDC login process can't work. - -You can unblock the third-party cookies manually to support the old workflow, but we recommend you use the new [embedding auth APIs](../support-for-different-authentication-environments/new-authentication-apis.md), which can work in the third-party cookies blocked case, and simplify the SAML or OIDC login logic. You can see the examples in the [playground](https://microstrategy.github.io/playground/?example=g17). A simple code piece would be like this: + - In this case, you will see an icon on the right of location bar, which notifies you the pop-ups + are blocked: ![pop-ups are blocked](../images/popup-blocked.png) You need to unblock the pop-ups + like this: ![unblock pop-ups](../images/unblock-popup.png) +- The user finishes logging in, but the Client Application doesn't proceed. The Strategy Library Web + login page isn't closed and the embeded dossier doesn't show. + - This might be caused by your strict CSP settings. If your + [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)(Cross-Origin-Opener-Policy) + setting is + [same-origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy#same-origin), + the Strategy Library Web login page can't get the Client Application window so can't send + messages to it. + - In this case, you need to change your COOP setting to + [unsafe-none](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy#unsafe-none), + which is the default value. Then the login process will work. + +## For Strategy ONE June 2024 or after + +In Strategy ONE June 2024, we add the +[partitioned cookie change](../config#the-partitioned-cookie-change) to enable the customer to use +the Embedding SDK even if third-party cookies are blocked. But if third-party cookies are blocked, +the old SAML or OIDC login process can't work. + +You can unblock the third-party cookies manually to support the old workflow, but we recommend you +use the new +[embedding auth APIs](../support-for-different-authentication-environments/new-authentication-apis.md), +which can work in the third-party cookies blocked case, and simplify the SAML or OIDC login logic. +You can see the examples in the +[playground](https://microstrategy.github.io/playground/?example=g17). A simple code piece would be +like this: ```js microstrategy.embeddingContexts.embedLibraryPage({ @@ -47,7 +70,12 @@ microstrategy.embeddingContexts.embedLibraryPage({ }); ``` -The new API [microstrategy.auth.samlLogin(serverUrl)](./new-authentication-apis#microstrategyauthsamlloginserverurl) or [microstrategy.auth.oidcLogin(serverUrl)](./new-authentication-apis#microstrategyauthoidcloginserverurl) creates an identity token to share the sessions, so you must ensure you have a secret key to create identity tokens first. You can check it in the Library settings here: +The new API +[microstrategy.auth.samlLogin(serverUrl)](./new-authentication-apis#microstrategyauthsamlloginserverurl) +or +[microstrategy.auth.oidcLogin(serverUrl)](./new-authentication-apis#microstrategyauthoidcloginserverurl) +creates an identity token to share the sessions, so you must ensure you have a secret key to create +identity tokens first. You can check it in the Library settings here: ![The secret key](../images/secret-key.png) 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 bb002e0..d525e46 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,15 +1,29 @@ --- title: Use guest authentication -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. +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 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. +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 dashboard and nothing else, and it embeds an existing dashboard 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 Strategy 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 dashboard 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 Strategy 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. +Please also check out the examples in +[Embedding SDK Playground](https://microstrategy.github.io/playground/) from the "Start over" +button. ```html @@ -54,17 +68,25 @@ Run the code in browser or in the Playground. You should see the dashboard shown :::tip -Because this simple embedding example uses a dashboard on the demo server, you are not prompted for credentials. However, when you use a dashboard in your environment, you will be prompted for credentials unless you enable single sign-on. In the other topics, you will learn how to enable single sign-on. +Because this simple embedding example uses a dashboard on the demo server, you are not prompted for +credentials. However, when you use a dashboard in your environment, you will be prompted for +credentials unless you enable single sign-on. In the other topics, you will learn how to enable +single sign-on. :::tip -**To customize the example to use your MicroStrategy Library Server**: +**To customize the example to use your Strategy Library Server**: -1. Decide where you want to have the HTML page. If the domain is different from your MicroStrategy Library Server's domain, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](../config.md). +1. Decide where you want to have the HTML page. If the domain is different from your Strategy + Library Server's domain, you may need to + [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](../config.md). -1. In an IDE, text editor or [Embedding SDK Playground](https://microstrategy.github.io/playground/), open the HTML file and configure it to reflect the values in your environment: +1. In an IDE, text editor or + [Embedding SDK Playground](https://microstrategy.github.io/playground/), open the HTML file and + configure it to reflect the values in your environment: - - Set the value of the `src` attribute in the first ` ``` - The `embeddinglib.js` file, which contains the Embedding SDK, is included in the MicroStrategyLibrary web application. + The `embeddinglib.js` file, which contains the Embedding SDK, is included in + the StrategyLibrary web application. - - Set the value for url to reference a dashboard in a project in your environment. First, replace `demo.microstrategy.com` with your server path and then replace `B7CA92F04B9FAE8D941C3E9B7E0CD754` and `27D332AC6D43352E0928B9A1FCAF4AB0` with your Project ID and Dashboard ID. + - Set the value for url to reference a dashboard in a project in your environment. First, + replace `demo.microstrategy.com` with your server path and then + replace `B7CA92F04B9FAE8D941C3E9B7E0CD754` and `27D332AC6D43352E0928B9A1FCAF4AB0` with your + Project ID and Dashboard ID. ```js url = @@ -84,7 +110,8 @@ Because this simple embedding example uses a dashboard on the demo server, you a :::tip - You can obtain the value of your Project ID and Dashboard ID by running a dashboard in MicroStrategy Library and copying the URL. + You can obtain the value of your Project ID and Dashboard ID by running a dashboard in Strategy + Library and copying the URL. ::: @@ -92,12 +119,24 @@ Because this simple embedding example uses a dashboard on the demo server, you a 1. Configure your environment so that only guest authentication is enabled. - If guest authentication is the only authentication mode that is enabled, the application will open and the dashboard will be displayed without asking for credentials. However, if multiple authentication modes are enabled, the dashboard will not be displayed seamlessly. You need to add additional code that enables guest authentication. [Using guest authentication when there are multiple authentication modes](./multiple-modes.md) provides a simple example and an explanation of how to add the necessary code. + If guest authentication is the only authentication mode that is enabled, the application will + open and the dashboard will be displayed without asking for credentials. However, if multiple + authentication modes are enabled, the dashboard will not be displayed seamlessly. You need to add + additional code that enables guest authentication. + [Using guest authentication when there are multiple authentication modes](./multiple-modes.md) + provides a simple example and an explanation of how to add the necessary code. -1. Open the page URL in a browser or run it in [Embedding SDK Playground](https://microstrategy.github.io/playground/). The embedded dashboard should be displayed in the application. +1. Open the page URL in a browser or run it in + [Embedding SDK Playground](https://microstrategy.github.io/playground/). The embedded dashboard + should be displayed in the application. :::tip -If the dashboard does not render on the page, you can use the browser developer tools to review any exceptions or errors being thrown. When you make an XHR request for `POST /auth/login`, you only need to wait until the response headers are returned. The expected status code will be 204 (Success no content). Review [the documentation on `XMLHTTPRequest.readyState`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState) to understand what is necessary to obtain the request header. +If the dashboard does not render on the page, you can use the browser developer tools to review any +exceptions or errors being thrown. When you make an XHR request for `POST /auth/login`, you only +need to wait until the response headers are returned. The expected status code will be 204 (Success +no content). +Review [the documentation on `XMLHTTPRequest.readyState`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState) +to understand what is necessary to obtain the request header. ::: diff --git a/docs/support-for-different-authentication-environments/multiple-modes.md b/docs/support-for-different-authentication-environments/multiple-modes.md index d6627d9..4d1e175 100644 --- a/docs/support-for-different-authentication-environments/multiple-modes.md +++ b/docs/support-for-different-authentication-environments/multiple-modes.md @@ -1,19 +1,23 @@ --- title: Use guest authentication with multiple authentication modes enabled -description: The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest authentication when multiple authentication modes are enabled. +description: + The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest + authentication when multiple authentication modes are enabled. --- -The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest authentication when multiple authentication modes are enabled. +The example in this topic illustrates how to seamlessly display an embedded dashboard using Guest +authentication when multiple authentication modes are enabled. ## Set up Library Server -Enable Guest and other authentications in MicroStrategy Library Admin. +Enable Guest and other authentications in Strategy Library Admin. ![MSTR Library Admin Guest Auth](../images/MstrLibraryAdmin_GuestAuth.png) ## Configure the example -1. A live example can be seen on [GitHub](https://microstrategy.github.io/playground/?example=g17). Also check out [other examples](https://microstrategy.github.io/playground). +1. A live example can be seen on [GitHub](https://microstrategy.github.io/playground/?example=g17). + Also check out [other examples](https://microstrategy.github.io/playground). ```html @@ -75,11 +79,14 @@ Enable Guest and other authentications in MicroStrategy Library Admin. ``` -`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is based on login as a Library user, which uses the param of `applicationType:35`. +`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is +based on login as a Library user, which uses the param of `applicationType:35`. 1. To use a dashboard from your Library Server, make the following changes to the code: - 1. Configure the path to the Embedding SDK javascript file, replacing `https://demo.microstrategy.com/MicroStrategyLibraryInsights` with your Library Server URL. + 1. Configure the path to the Embedding SDK javascript file, + replacing `https://demo.microstrategy.com/MicroStrategyLibraryInsights` with your Library + Server URL. ```html ``` - The `embeddinglib.js` file, which contains the Embedding SDK, is included in the `MicroStrategyLibrary` web application. + The `embeddinglib.js` file, which contains the Embedding SDK, is included in + the `StrategyLibrary` web application. - 1. Configure variables to set the values for the path to the MicroStrategy Library installation, the project ID, and the dashboard ID. + 1. Configure variables to set the values for the path to the Strategy Library installation, the + project ID, and the dashboard ID. - - Set the value of the `baseURL` variable to the path to your MicroStrategy Library by replace `https://demo.microstrategy.com/MicroStrategyLibraryInsights` with your Library Server URL. + - Set the value of the `baseURL` variable to the path to your Strategy Library by + replace `https://demo.microstrategy.com/MicroStrategyLibraryInsights` with your Library + Server URL. ```js const baseURL = "https://demo.microstrategy.com/MicroStrategyLibraryInsights"; ``` - - Set the value of the `projectId` variable to the ID for the project containing the dashboard you want to embed. + - Set the value of the `projectId` variable to the ID for the project containing the dashboard + you want to embed. ```js const projectId = "EC70648611E7A2F962E90080EFD58751"; @@ -112,14 +124,21 @@ Enable Guest and other authentications in MicroStrategy Library Admin. :::tip - You can obtain the project ID and dashboard ID by running the dashboard in MicroStrategy Library and copying the URL. + You can obtain the project ID and dashboard ID by running the dashboard in Strategy Library + and copying the URL. ::: -1. Once you have configured the code, save your HTML file and open it in a browser. The embedded dashboard is seamlessly displayed in the browser. +1. Once you have configured the code, save your HTML file and open it in a browser. The embedded + dashboard is seamlessly displayed in the browser. :::tip -If the dashboard does not render on the page, you can use the browser developer tools to review any exceptions or errors being thrown. When you make an XHR request for `POST /auth/login`, you only need to wait until the response headers are returned. The expected status code will be 204 (Success no content). Review [the documentation on `XMLHTTPRequest.readyState`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState) to understand what is necessary to obtain the request header. +If the dashboard does not render on the page, you can use the browser developer tools to review any +exceptions or errors being thrown. When you make an XHR request for `POST /auth/login`, you only +need to wait until the response headers are returned. The expected status code will be 204 (Success +no content). +Review [the documentation on `XMLHTTPRequest.readyState`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState) +to understand what is necessary to obtain the request header. ::: diff --git a/docs/support-for-different-authentication-environments/new-authentication-apis.md b/docs/support-for-different-authentication-environments/new-authentication-apis.md index efa2b61..df266fd 100644 --- a/docs/support-for-different-authentication-environments/new-authentication-apis.md +++ b/docs/support-for-different-authentication-environments/new-authentication-apis.md @@ -3,7 +3,9 @@ title: SAML and OIDC authentication APIs description: Describes the Embedding SDK APIs that are available for SAML and OIDC authentication. --- -To simplify the SAML and OIDC login workflow, we expose 2 new APIs `microstrategy.auth.samlLogin(serverUrl)` and `microstrategy.auth.oidcLogin(serverUrl)`. You can see the examples in the [playground](https://microstrategy.github.io/playground/?example=g17). +To simplify the SAML and OIDC login workflow, we expose 2 new APIs +`microstrategy.auth.samlLogin(serverUrl)` and `microstrategy.auth.oidcLogin(serverUrl)`. You can see +the examples in the [playground](https://microstrategy.github.io/playground/?example=g17). The details of these 2 APIs are as below: @@ -15,7 +17,8 @@ This API can be used to start the SAML login workflow on the embedding scenario. #### Input Parameters -The input parameter `serverUrl` is the url of a Library server, which has configured the SAML login mode successfully. +The input parameter `serverUrl` is the url of a Library server, which has configured the SAML login +mode successfully. #### Return type @@ -38,7 +41,9 @@ microstrategy.embeddingContexts.embedLibraryPage({ This API would have the wrong behavior or report an error in the cases below: - When `serverUrl` is not a Library server that supports SAML login. -- When the client application can't get the MicroStrategy login window because of [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) setting is too strict. +- When the client application can't get the Strategy login window because of + [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) + setting is too strict. ### `microstrategy.auth.oidcLogin(serverUrl)` @@ -48,7 +53,8 @@ This API can be used to start the OIDC login workflow on the embedding scenario. #### Input Parameters -The input parameter `serverUrl` is the url of a Library server, which has configured the OIDC login mode successfully. +The input parameter `serverUrl` is the url of a Library server, which has configured the OIDC login +mode successfully. #### Return type @@ -71,4 +77,6 @@ microstrategy.embeddingContexts.embedLibraryPage({ This API would have the wrong behavior or report an error in the cases below: - When `serverUrl` is not a Library server that supports OIDC login. -- When the client application can't get the MicroStrategy login window because of [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) setting is too strict. +- When the client application can't get the Strategy login window because of + [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) + setting is too strict. diff --git a/docs/support-for-different-authentication-environments/seamless-login.md b/docs/support-for-different-authentication-environments/seamless-login.md index 14d7765..67a9cfa 100644 --- a/docs/support-for-different-authentication-environments/seamless-login.md +++ b/docs/support-for-different-authentication-environments/seamless-login.md @@ -3,11 +3,19 @@ title: Seamless login using identity token description: How to do seamless login with identity token --- -When you embed a MicroStrategy dashboard in your application, you can provide a seamless login experience for users who are already authenticated on your server so that they don't have to authenticate again on the MicroStrategy Server. +When you embed a Strategy dashboard in your application, you can provide a seamless login experience +for users who are already authenticated on your server so that they don't have to authenticate again +on the Strategy Server. -For example, assume that a user is already authenticated with a third-party server and this 3rd-party server is managing the user credentials so that it can authenticate with other applications on the user's behalf. (The third-party server is responsible for securing the data and initiating authentication on HTTPS.) If a user has already logged into MicroStrategy Web, you can also get an identity token using MicroStrategy Task API. +For example, assume that a user is already authenticated with a third-party server and this +3rd-party server is managing the user credentials so that it can authenticate with other +applications on the user's behalf. (The third-party server is responsible for securing the data and +initiating authentication on HTTPS.) If a user has already logged into Strategy Web, you can also +get an identity token using Strategy Task API. -MicroStrategy Embedding SDK supports [identity token](../add-functionality/methods-and-properties.md#customauthenticationtype) as a custom authentication type. +Strategy Embedding SDK supports +[identity token](../add-functionality/methods-and-properties.md#customauthenticationtype) as a +custom authentication type. ## Getting identity token from Library Server @@ -15,32 +23,50 @@ The authentication workflow is the following: ![Seamless login](../images/seamless_login.png) -1. The third-party application server logs in, invoking the REST API login endpoint (`POST /api/auth/login`) and providing the user's credential information. -1. Once the user is logged in, the identity token can be retrieved with the authorization token, using `POST /api/auth/identityToken`. The MicroStrategy Library Server returns an identity token to the caller in the response header. The identity token has a very short duration. -1. The client provides the identity token to the Embedding SDK, which is used for embedding a dashboard. -1. The SDK will exchange the identity token for an authorization token and use the authorization token to communicate with the Library Server in the subsequent requests. +1. The third-party application server logs in, invoking the REST API login endpoint + (`POST /api/auth/login`) and providing the user's credential information. +1. Once the user is logged in, the identity token can be retrieved with the authorization token, + using `POST /api/auth/identityToken`. The Strategy Library Server returns an identity token to + the caller in the response header. The identity token has a very short duration. +1. The client provides the identity token to the Embedding SDK, which is used for embedding a + dashboard. +1. The SDK will exchange the identity token for an authorization token and use the authorization + token to communicate with the Library Server in the subsequent requests. :::tip -A live example can be seen on [GitHub](https://microstrategy.github.io/playground/?example=g17) with 'Identity Token Authentication' operation under 'Authentication' tag, which shows how to pass the identity token to Embedding SDK. Also check out [other examples](https://microstrategy.github.io/playground). +A live example can be seen on [GitHub](https://microstrategy.github.io/playground/?example=g17) with +'Identity Token Authentication' operation under 'Authentication' tag, which shows how to pass the +identity token to Embedding SDK. Also check out +[other examples](https://microstrategy.github.io/playground). ::: -## Getting identity token from MicroStrategy Web +## Getting identity token from Strategy Web -If your user has already logged into MicroStrategy Web, you can get identity token from MicroStrategy Web and use the identity token in Embedding SDK. +If your user has already logged into Strategy Web, you can get identity token from Strategy Web and +use the identity token in Embedding SDK. The authentication workflow is the following: ![Web Seamless Login](../images/web_seamless_login.jpg) -1. User has already logged into MicroStrategy Web. The client application calls `createIdentityToken` task. `POST /servlet/taskProc` with `taskId=createIdentityToken&taskContentType=json&taskEnv=xhr` in payload. See [Web SDK](https://www2.microstrategy.com/producthelp/Current/WEBSDK/Content/topics/taskinfr/TI_QuickStartGuide_UseTasks.htm) for how to use tasks. -1. The MicroStrategy Web returns an identity token to the caller in the response body. The identity token has a very short duration. -1. The client application provides the identity token to the Embedding SDK, which is used for embedding a dashboard. -1. The SDK will exchange the identity token for an authorization token and use the authorization token to communicate with the Library Server in the subsequent requests. +1. User has already logged into Strategy Web. The client application calls `createIdentityToken` + task. `POST /servlet/taskProc` with `taskId=createIdentityToken&taskContentType=json&taskEnv=xhr` + in payload. See + [Web SDK](https://www2.microstrategy.com/producthelp/Current/WEBSDK/Content/topics/taskinfr/TI_QuickStartGuide_UseTasks.htm) + for how to use tasks. +1. The Strategy Web returns an identity token to the caller in the response body. The identity token + has a very short duration. +1. The client application provides the identity token to the Embedding SDK, which is used for + embedding a dashboard. +1. The SDK will exchange the identity token for an authorization token and use the authorization + token to communicate with the Library Server in the subsequent requests. :::tip -You need to enable seamless login between MicroStrategy Web and Library to use this workflow. See [this document](https://www2.microstrategy.com/producthelp/current/InstallConfig/en-us/Content/enable_seamless_login_web_library.htm) for details. +You need to enable seamless login between Strategy Web and Library to use this workflow. See +[this document](https://www2.microstrategy.com/producthelp/current/InstallConfig/en-us/Content/enable_seamless_login_web_library.htm) +for details. ::: diff --git a/docs/support-for-different-authentication-environments/standard-authentication.md b/docs/support-for-different-authentication-environments/standard-authentication.md index a5b5c35..60b1fe6 100644 --- a/docs/support-for-different-authentication-environments/standard-authentication.md +++ b/docs/support-for-different-authentication-environments/standard-authentication.md @@ -1,11 +1,17 @@ --- title: Use standard or LDAP authentication -description: The example in this topic illustrates how to seamlessly display an embedded dashboard using standard or LDAP authentication +description: + The example in this topic illustrates how to seamlessly display an embedded dashboard using + standard or LDAP authentication --- -The example in this topic showcases how to display an embedded dashboard using Standard or LDAP authentication +The example in this topic showcases how to display an embedded dashboard using Standard or LDAP +authentication -To help you get started, we have provided [a live example](https://microstrategy.github.io/playground/?example=g17) 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 authenticate using Standard authentication. +To help you get started, we have provided +[a live example](https://microstrategy.github.io/playground/?example=g17) 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 authenticate using Standard authentication. The workflow consists of: @@ -17,13 +23,16 @@ The workflow consists of: ## Set up Library Server -Enable Standard and optionally other authentication modes in MicroStrategy Library Admin. +Enable Standard and optionally other authentication modes in Strategy Library Admin. ![MSTR Library Admin Guest Auth](../images/MstrLibraryAdmin_GuestAuth.png) ## Import Embedding SDK -Import Embedding SDK from your Library Server to your HTML page. In the code sample below, the SDK is imported into the head section of the HTML file. You can replace the url, `https://demo.microstrategy.com/MicroStrategyLibraryInsights/javascript/embeddinglib.js`, with your own typically in the form `https://{env-url}/{libraryName}/javascript/embeddinglib.js`. +Import Embedding SDK from your Library Server to your HTML page. In the code sample below, the SDK +is imported into the head section of the HTML file. You can replace the url, +`https://demo.microstrategy.com/MicroStrategyLibraryInsights/javascript/embeddinglib.js`, with your +own typically in the form `https://{env-url}/{libraryName}/javascript/embeddinglib.js`. ```html @@ -36,14 +45,17 @@ Import Embedding SDK from your Library Server to your HTML page. In the code sam ## Embed dashboard with custom authentication properties -The sample code below shows how to embed a sample dashboard with properties set to enable custom authentication mode where you have to provide the auth token to log in. Note: the `login` function will be implemented in the [next section](#authentication-through-rest-api-using-standard-or-ldap-authentication). +The sample code below shows how to embed a sample dashboard with properties set to enable custom +authentication mode where you have to provide the auth token to log in. Note: the `login` function +will be implemented in the +[next section](#authentication-through-rest-api-using-standard-or-ldap-authentication). ```html
``` -`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is based on login as a Library user, which uses the param of `applicationType:35`. +`applicationType` must be unset or equal to `35`. Because the implementation of Embedding SDK is +based on login as a Library user, which uses the param of `applicationType:35`. ## Putting it all together -Here's how it would look if you follow the steps above. -Adjust as needed. +Here's how it would look if you follow the steps above. Adjust as needed. ```html @@ -180,7 +201,7 @@ Adjust as needed.