From 1c407782ec2861eaa6c70694fc00ecb456ae6510 Mon Sep 17 00:00:00 2001 From: Brad Morris Date: Thu, 15 Aug 2024 09:38:47 -0400 Subject: [PATCH] update va-report-components v2.13.0 doc and changelog (#72) --- sdk/va-report-components/CHANGELOG.md | 6 + .../version-2.13.0/api-reference.md | 44 ++++++ .../version-2.13.0/api/setFormatterLocale.md | 45 ++++++ .../version-2.13.0/api/setLoadingTheme.md | 67 +++++++++ .../version-2.13.0/api/setLocale.md | 45 ++++++ .../version-2.13.0/getting-started.md | 88 ++++++++++++ .../version-2.13.0/guides/esm.md | 130 ++++++++++++++++++ .../version-2.13.0-sidebars.json | 35 +++++ .../documentation/website/versions.json | 1 + 9 files changed, 461 insertions(+) create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api-reference.md create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setFormatterLocale.md create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLoadingTheme.md create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLocale.md create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/getting-started.md create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/guides/esm.md create mode 100644 sdk/va-report-components/documentation/website/versioned_sidebars/version-2.13.0-sidebars.json diff --git a/sdk/va-report-components/CHANGELOG.md b/sdk/va-report-components/CHANGELOG.md index 71065e0..c3d655d 100644 --- a/sdk/va-report-components/CHANGELOG.md +++ b/sdk/va-report-components/CHANGELOG.md @@ -1,3 +1,9 @@ +## 2.13.0 (August 15, 2024) + +### Added +- SAS Viya 2024.08 support (Report Package version 48) +- [ES Module imports](https://developer.sas.com/sdk/va/docs/guides/esm) support + ## 2.12.0 (July 18, 2024) ### Added diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api-reference.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api-reference.md new file mode 100644 index 0000000..470658b --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api-reference.md @@ -0,0 +1,44 @@ +--- +id: version-2.13.0-api-reference +title: API Reference +original_id: api-reference +--- + +The SAS Visual Analytics SDK provides a set of components and APIs that enable you to render reports and report parts. It also enables you +to use SAS data to drive your own components or visualizations. + +## Top-Level Exports + +- [`SASReportElement`](api/SASReportElement.md) +- [`SASReportPageElement`](api/SASReportPageElement.md) +- [`SASReportObjectElement`](api/SASReportObjectElement.md) +- [`connectToServer`](api/connectToServer.md) +- [`registerDataDrivenContent`](api/registerDataDrivenContent.md) +- [`DataDrivenContentHandle`](api/DataDrivenContentHandle.md) +- [`setUseHighContrastReportTheme`](api/setUseHighContrastReportTheme.md) +- [`setLoadingTheme`](api/setLoadingTheme.md) +- [`setLocale`](api/setLocale.md) +- [`setFormatterLocale`](api/setFormatterLocale.md) + +## Loading with \ + +When you load the library with a script element, the `vaReportComponents` global variable is not ready to use until all of the other +assets are loaded. The `vaReportComponents.loaded` event is dispatched once it is ready. + +```html + + +``` + +## Loading with imports + +When you load the library as an ES module, APIs are available as named imports. See the [ES module imports guide](guides/esm.md) for more information about loading the library as a module. + +```ts +import { connectToServer } from '@sassoftware/va-report-components'; +``` diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setFormatterLocale.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setFormatterLocale.md new file mode 100644 index 0000000..311fe2c --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setFormatterLocale.md @@ -0,0 +1,45 @@ +--- +id: version-2.13.0-setFormatterLocale +title: setFormatterLocale +original_id: setFormatterLocale +--- + +``` +setFormatterLocale(locale): void +``` + +`setFormatterLocale` enables the user to set the language that is used to format numeric values and dates. If not specified, the language will fallback to the one that is specified by calling setLocale or the one is specified in the browser settings. + +## Arguments + +### `locale: string | null` + +The locale should be specified as a language code and an optional country code. This is the same format that is used by [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) + +## Examples + +### Script Tag + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setFormatterLocale("fr"); +}); +``` + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setFormatterLocale("fr-CA"); +}); +``` + +### ESM + +```javascript +import { setFormatterLocale } from "@sassoftware/va-report-components"; +setFormatterLocale("fr"); +``` + +```javascript +import { setFormatterLocale } from "@sassoftware/va-report-components"; +setFormatterLocale("fr-CA"); +``` diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLoadingTheme.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLoadingTheme.md new file mode 100644 index 0000000..6432630 --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLoadingTheme.md @@ -0,0 +1,67 @@ +--- +id: version-2.13.0-setLoadingTheme +title: setLoadingTheme +original_id: setLoadingTheme +--- + +``` +setLoadingTheme(options): void +``` + +`setLoadingTheme` allows the user to set the theme of the sdk before a report loads. You might want to set the theme for the initial loading state to match the website that the SAS Visual Analytic SDK is embedded in. You also might want to set the loading theme to be consistent with the report that will be loaded. + +`setLoadingTheme` only affects the initial loading and logon states. It does not affect the report theme once a report has been loaded. + +## Arguments + +### `options: Object | 'light' | 'dark' | 'high-contrast'` + +When you select `'light'`, `'dark'`, or `'high-contrast'`, then the loading theme is based on one of the built-in themes. + +Alternatively, you can specify theme values. The following optional properties are supported: + +- `baseTheme: 'light' | 'dark'`: The base theme that is used for loading the theme values. The theme values are used when no defaults are provided. For example, if backgroundColor is not specified and the baseTheme is light, then the backgoundColor will be white since that is the theme's background color. **default**:`light` + +You can further customize the loading style with additional style properties. Some examples are provided below to show you how certain options affect the theme. The following style overrides are available: + +- `primary: string`: The logon button background and loading indicator. +- `backgroundColor: string` +- `textColor: string` +- `textColorInverse: string` The button text color for the logon state. +- `fontFamily: string` + +## Examples + +### Script Tag + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setLoadingTheme("dark"); +}); +``` + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setLoadingTheme({ + baseTheme: "dark", + primary: "#FFA500", + fontFamily: "Gothic", + }); +}); +``` + +### ESM + +```javascript +import { setLoadingTheme } from "@sassoftware/va-report-components"; +setLoadingTheme("dark"); +``` + +```javascript +import { setLoadingTheme } from "@sassoftware/va-report-components"; +setLoadingTheme({ + baseTheme: "dark", + primary: "#FFA500", + fontFamily: "Gothic", +}); +``` diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLocale.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLocale.md new file mode 100644 index 0000000..d48311d --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/api/setLocale.md @@ -0,0 +1,45 @@ +--- +id: version-2.13.0-setLocale +title: setLocale +original_id: setLocale +--- + +``` +setLocale(locale): void +``` + +`setLocale` enables the user to set an override for the language that is specified in the browser settings. + +## Arguments + +### `locale: string | null` + +The locale should be specified as a language code and an optional country code. This is the same format that is used by [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) + +## Examples + +### Script Tag + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setLocale("fr"); +}); +``` + +```javascript +window.addEventListener("vaReportComponents.loaded", function() { + vaReportComponents.setLocale("fr-CA"); +}); +``` + +### ESM + +```javascript +import { setLocale } from "@sassoftware/va-report-components"; +setLocale("fr"); +``` + +```javascript +import { setLocale } from "@sassoftware/va-report-components"; +setLocale("fr-CA"); +``` diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/getting-started.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/getting-started.md new file mode 100644 index 0000000..0d5cfc6 --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/getting-started.md @@ -0,0 +1,88 @@ +--- +id: version-2.13.0-getting-started +title: Getting started +original_id: getting-started +--- + +The SAS Visual Analytics SDK enables you to use the power of SAS Visual Analytics in your own websites and HTML applications. +You can embed entire reports with the `` custom HTML element, embed a single object with the +`` element, or connect to your reports with our JavaScript API. + +## Installation + +### NPM + +The `@sassoftware/va-report-components` library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` can then be loaded with either a `script` tag or with an ES module import. + +```bash +# From the root directory of your project +npm install @sassoftware/va-report-components +``` + +When using a `script` tag, the contents of the `va-report-components/dist` folder must be deployed with your page. + +```bash +# Copy the contents of the package to an asset folder for deployment +cp -r ./node_modules/@sassoftware/va-report-components ./sdk-assets +``` + +The library can then be loaded out of the deployed assets folder. + +```html + +``` + +If your site is built using a code bundler, it might be more convenient to load the library through ES module imports. See the [ES module guide](guides/esm.md) for more details. + +```js +import "@sassoftware/va-report-components" +``` + +### CDN (Content Delivery Network) + +Accessing the `va-report-components` library from the SAS Developer CDN is easy. It does not require installation or +hosting of the library code and assets. Here is an example of loading the latest version of `va-report-components` from the CDN using an HTML `script` tag. + +```html + +``` + +When the library is used in production, consider pinning it to an explicit version. This is done with a URL like `https://cdn.developer.sas.com/packages/va-report-components/${VERSION}/dist/umd/va-report-components.js`, where `${VERSION}` is the full `major.minor.patch` semantic version. + +## SAS Viya setup + +The SAS Visual Analytics SDK requires either connecting directly to SAS Viya or exporting a SAS Report Package. Server setup requirements for connecting to SAS Viya are covered in the [SAS Viya Setup Guide](guides/viya-setup.md). + +## Create a custom HTML tag + +To build the custom HTML tag that you will embed in your web page: + +1. Open a report in SAS Visual Analytics. +1. Open the menu in the report toolbar (which is displayed in the image below) or right-click an individual object, and then select Copy Link. The Copy Link window is displayed. +1. If you are using guest access, expand the Options heading and select the Guest access check box. +1. Click Copy Link. + +![Report Overflow Menu](assets/report-overflow-menu.png) + +Once the report link or object link has been copied to your clipboard, paste it below, and the output will show a custom HTML +tag that is ready to use. + + +
+ +
+
+ + +For a complete list of options, see the documentation for [`SASReportElement`](api/SASReportElement.md) and +[`SASReportObjectElement`](api/SASReportObjectElement.md) + +## See our examples + +Our examples demonstrate a few different +ways to start using the SAS Visual Analytics SDK in your HTML application. diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/guides/esm.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/guides/esm.md new file mode 100644 index 0000000..64bfb6b --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.13.0/guides/esm.md @@ -0,0 +1,130 @@ +--- +id: version-2.13.0-esm +title: ES Module Imports +original_id: esm +--- + +Sites built using a code bundler may choose to load `@sassoftware/va-report-components` with ES module imports. When loaded this way, the APIs are available as named imports. + +[SASReportElement](api/SASReportElement.md) and the other custom elements are defined through side effects, so care must be taken to ensure `@sassoftware/va-report-components` is included at runtime. One way to do this is by adding a side effect import in the build's entry point or in the modules where `va-report-components` is used. + +```js +import "@sassoftware/va-report-components"; +``` + +A side effect import might not be necessary if the code uses an imported API directly. + +```js +import { SASReportElement } from "@sassoftware/va-report-components"; +const report = new SASReportElement(); +document.body.appendChild(report); +``` + +For TypeScript applications, type imports are insufficent for ensuring that `va-report-components` will be included in the build. + +```ts +// Type imports are NOT included at runtime +import type { SASReportElement } from "@sassoftware/va-report-components"; +// This report will not load unless va-report-components is imported elsewhere +const report = document.getElementById("my-report") as SASReportElement; +``` + +## Usage notes + +### Webpack + +#### Configuration + +`va-report-components` contains CSS files that might not work as intended when processed by webpack loaders. If your build uses loaders such as style-loader or css-loader, you should exclude `va-report-components`. + +```js +// webpack.config.js +export default { + module: { + rules: [ + { + test: /\.css$/, + use: ["style-loader", "css-loader"], + exclude: /va-report-components/, + }, + ], + }, +}; +``` + +#### SAS Report Packages + +If your site hosts [exported SAS Report Packages](guides/export-report-package.md) alongside your webpack build, they can be referenced relative to `__webpack_public_path__`. + +```js +import { SASReportElement } from "@sassoftware/va-report-components"; +const report = new SASReportElement(); +report.packageUri = `${__webpack_public_path__}reports/ExampleReport.sasreportpkg`; +``` + +### Vite + +#### Configuration + +`va-report-components` references some assets with the `new URL("...", import.meta.url)` syntax, a feature not yet fully supported in Vite dev builds. In order to load `va-report-components` in Vite dev builds, `@sassoftware/va-report-components` must be excluded from `optimizeDeps` in the Vite config. Then, all CommonJS modules imported by the package, both directly and indirectly, must be re-included. + +```ts +// vite.config.js +export default defineConfig({ + optimizeDeps: { + exclude: ["@sassoftware/va-report-components"], + include: [ + "@tanstack/react-query", + "classnames", + "handlebars", + "hoist-non-react-statics", + "prop-types", + "react-dom", + "react-fast-compare", + "react-redux", + "void-elements", + "warning", + ], + }, +}); +``` + +Known CommonJS dependencies are listed above, but the actual list can vary between applications. When a module needs to be added to the list, a message is logged in the browser console. Here is an example: + +```text +SyntaxError: The requested module '/node_modules/prop-types/index.js?v=4776a820' does not provide an export named 'default' +``` + +Production builds are not affected by this issue. + +#### SAS Report Packages + +If you include [exported SAS Report Packages](guides/export-report-package.md) in your Vite project's +`public` directory, the packages can be referenced relative to `import.meta.env.BASE_URL`. + +```js +import { SASReportElement } from "@sassoftware/va-report-components"; +const report = new SASReportElement(); +report.packageUri = `${import.meta.env.BASE_URL}reports/ExampleReport.sasreportpkg`; +``` + +### React + +Custom elements such as `sas-report` can be rendered in React, but the `class` prop should be used rather than `className`. + +```jsx +import '@sassoftware/va-report-components'; + +export const MyComponent(props) { + return ( + + ) +} +``` + +For more information, see [Custom HTML elements](https://react.dev/reference/react-dom/components#custom-html-elements) in the React documentation. diff --git a/sdk/va-report-components/documentation/website/versioned_sidebars/version-2.13.0-sidebars.json b/sdk/va-report-components/documentation/website/versioned_sidebars/version-2.13.0-sidebars.json new file mode 100644 index 0000000..c3a54dd --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_sidebars/version-2.13.0-sidebars.json @@ -0,0 +1,35 @@ +{ + "version-2.13.0-docs": { + "Introduction": [ + "version-2.13.0-getting-started" + ], + "Guides": [ + "version-2.13.0-guides/viya-setup", + "version-2.13.0-guides/export-report-package", + "version-2.13.0-guides/data-driven-content", + "version-2.13.0-guides/esm" + ], + "API Reference": [ + "version-2.13.0-api-reference", + "version-2.13.0-api/SASReportElement", + "version-2.13.0-api/SASReportPageElement", + "version-2.13.0-api/SASReportObjectElement", + "version-2.13.0-api/ReportHandle", + "version-2.13.0-api/ObjectHandle", + "version-2.13.0-api/ExportPDFOptions", + "version-2.13.0-api/ExportDataOptions", + "version-2.13.0-api/MenuItemProvider", + "version-2.13.0-api/connectToServer", + "version-2.13.0-api/registerDataDrivenContent", + "version-2.13.0-api/DataDrivenContentHandle", + "version-2.13.0-api/ReportObjectResultData", + "version-2.13.0-api/setUseHighContrastReportTheme", + "version-2.13.0-api/setLoadingTheme", + "version-2.13.0-api/setLocale", + "version-2.13.0-api/setFormatterLocale" + ], + "Resources": [ + "version-2.13.0-faq" + ] + } +} diff --git a/sdk/va-report-components/documentation/website/versions.json b/sdk/va-report-components/documentation/website/versions.json index 308a8ef..2e1c976 100644 --- a/sdk/va-report-components/documentation/website/versions.json +++ b/sdk/va-report-components/documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "2.13.0", "2.12.0", "2.11.0", "2.10.0",