update version 0.19.0 doc (#49)

sassoftware · Jul 21, 2021 · 23bc2f6 · 23bc2f6
1 parent 94e19e2
commit 23bc2f6
Show file tree

Hide file tree

Showing 15 changed files with 250 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -96,3 +96,9 @@
 - Add getObjectHandle API
 - Add refreshData API (ReportHandle and ObjectHandle)
 - Bug fixes
+
+## 0.19.0 (July 21, 2021)
+
+- SAS Viya 2021.1.3 support
+- Add setLoadingTheme API
+- Bug fixes
diff --git a/README.md b/README.md
@@ -35,11 +35,11 @@ The library can then be loaded out of the deployed assets folder using a `script
 
 Accessing the `va-report-components` library from a CDN is easy. It does not require installation or
 hosting of the library code and assets. There are several public options for accessing NPM content through a CDN, such
-as <a target="_blank" href="https://unpkg.com/">UNPKG</a> and <a target="_blank" href="https://www.jsdelivr.com/">jsDelivr</a>. Here is an example of loading the 0.18.0 version of `va-report-components` from UNPKG
+as <a target="_blank" href="https://unpkg.com/">UNPKG</a> and <a target="_blank" href="https://www.jsdelivr.com/">jsDelivr</a>. Here is an example of loading the 0.19.0 version of `va-report-components` from UNPKG
 using an HTML `script` tag. When used in production, the version should be pinned to the full `major.minor.patch` semantic version.
 
 ```html
-<script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## Getting Started

diff --git a/documentation/docs/api-reference.md b/documentation/docs/api-reference.md
@@ -23,7 +23,7 @@ When you load the library with a script element, the `vaReportComponents` global
 assets are loaded. The `vaReportComponents.loaded` event is dispatched once it is ready.
 
 ```html
-<script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
 <script>
   window.addEventListener('vaReportComponents.loaded', function() {
     // The SAS Visual Analytics SDK is loaded and ready

diff --git a/documentation/docs/getting-started.md b/documentation/docs/getting-started.md
@@ -31,11 +31,11 @@ The library can then be loaded out of the deployed assets folder using a `script
 
 Accessing the `va-report-components` library from a CDN is easy. It does not require installation or
 hosting of the library code and assets. There are several public options for accessing NPM content through a CDN, such
-as <a target="_blank" href="https://unpkg.com/">UNPKG</a> and <a target="_blank" href="https://www.jsdelivr.com/">jsDelivr</a>. Here is an example of loading the 0.18.0 version of `va-report-components` from UNPKG
+as <a target="_blank" href="https://unpkg.com/">UNPKG</a> and <a target="_blank" href="https://www.jsdelivr.com/">jsDelivr</a>. Here is an example of loading the 0.19.0 version of `va-report-components` from UNPKG
 using an HTML `script` tag. When used in production, the version should be pinned to the full `major.minor.patch` semantic version.
 
 ```html
-<script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## SAS Viya setup

diff --git a/documentation/website/versioned_docs/version-0.19.0/api-reference.md b/documentation/website/versioned_docs/version-0.19.0/api-reference.md
@@ -0,0 +1,34 @@
+---
+id: version-0.19.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)
+
+## Loading with \<script\>
+
+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
+<script async src="https://unpkg.com/@sassoftware/[email protected]/dist/umd/va-report-components.js"></script>
+<script>
+  window.addEventListener('vaReportComponents.loaded', function() {
+    // The SAS Visual Analytics SDK is loaded and ready
+    const connectToServer = vaReportComponents.connectToServer;
+  });
+</script>
+```
diff --git a/documentation/website/versioned_docs/version-0.19.0/api/setLoadingTheme.md b/documentation/website/versioned_docs/version-0.19.0/api/setLoadingTheme.md
@@ -0,0 +1,51 @@
+---
+id: version-0.19.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
+
+```javascript
+  window.addEventListener('vaReportComponents.loaded', function() {
+    vaReportComponents.setLoadingTheme('dark');
+  });
+```
+
+```javascript
+  window.addEventListener('vaReportComponents.loaded', function() {
+    vaReportComponents.setLoadingTheme({
+      baseTheme: 'dark',
+      primary: '#FFA500',
+      fontFamily: 'Gothic',
+    });
+  });
+```
diff --git a/documentation/website/versioned_docs/version-0.19.0/getting-started.md b/documentation/website/versioned_docs/version-0.19.0/getting-started.md
@@ -0,0 +1,86 @@
+---
+id: version-0.19.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 `<sas-report>` custom HTML element, embed a single object with the
+`<sas-report-object>` element, or connect to your reports with our JavaScript API.
+
+## Installation
+
+### NPM
+
+The <a target="_blank" href="https://www.npmjs.com/package/@sassoftware/va-report-components">`@sassoftware/va-report-components`</a> library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` does not support ES6 imports. Therefore, the contents of the `va-report-components/dist` folder must be deployed with your page, and then loaded using a `script` tag.
+
+```bash
+# From the root directory of your project
+npm install @sassoftware/va-report-components
+
+# 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 using a `script` tag.
+
+```html
+<script async src="./sdk-assets/dist/umd/va-report-components.js"></script>
+```
+
+### CDN (Content Delivery Network)
+
+Accessing the `va-report-components` library from a CDN is easy. It does not require installation or
+hosting of the library code and assets. There are several public options for accessing NPM content through a CDN, such
+as <a target="_blank" href="https://unpkg.com/">UNPKG</a> and <a target="_blank" href="https://www.jsdelivr.com/">jsDelivr</a>. Here is an example of loading the 0.19.0 version of `va-report-components` from UNPKG
+using an HTML `script` tag. When used in production, the version should be pinned to the full `major.minor.patch` semantic version.
+
+```html
+<script async src="https://unpkg.com/@sassoftware/[email protected]/dist/umd/va-report-components.js"></script>
+```
+
+## SAS Viya setup
+
+The SAS Visual Analytics SDK requires connecting to SAS Viya server.  Server setup requirements are covered in the [SAS Viya Setup Guide](guides/viya-setup.md).
+
+## Include a custom elements polyfill
+
+A <a target="_blank" href="https://www.npmjs.com/package/@webcomponents/custom-elements">custom elements polyfill</a> is required for Microsoft Edge support. The following script tag should be added before the `va-report-components` script tag.
+
+```html
+<script src="https://unpkg.com/@webcomponents/custom-elements"></script>
+```
+
+## 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.
+
+<link rel="stylesheet" href="/sdk/va/css/copy-link-translator.css">
+<form>
+  <textarea id="vdk-slt-input"
+    rows="5"
+    style="resize: none; width: 100%;"
+    placeholder="Paste the link from SAS Visual Analytics here."
+    aria-label="Paste the link from SAS Visual Analytics here."
+  ></textarea>
+  <pre><code id="vdk-slt-output" class="hljs" data-hide="true"></code></pre>
+</form>
+<script type="module" src="/sdk/va/js/copy-link-translator.js"></script>
+
+For a complete list of options, see the documentation for [`SASReportElement`](api/SASReportElement.md) and
+[`SASReportObjectElement`](api/SASReportObjectElement.md)
+
+## See our examples
+
+<a target="_blank" href="https://github.com/sassoftware/visual-analytics-sdk/tree/master/examples">Our examples</a> demonstrate a few different
+ways to start using the SAS Visual Analytics SDK in your HTML application.
diff --git a/documentation/website/versioned_docs/version-0.19.0/guides/viya-setup.md b/documentation/website/versioned_docs/version-0.19.0/guides/viya-setup.md
@@ -0,0 +1,33 @@
+---
+id: version-0.19.0-viya-setup
+title: SAS Viya Setup
+original_id: viya-setup
+---
+
+This guide explains how to modify the SAS Viya security settings to connect to the SAS Visual Analytics SDK. You need administrator credentials to make these changes using SAS Environment Manager.
+
+Note: The configuration changes listed below should all be made to the global context, applying to all services. Restart all services after making the changes.
+
+## Enable Cross-Origin Resource Sharing
+
+By default, your SAS Viya deployment is not set up to allow access to REST API endpoints from different domains. This is
+needed in order to connect to SAS Viya from the domain that is hosting your HTML page. This domain needs to be added to the
+`allowOrigins` property in SAS Viya deployment's CORS configuration. This can be done by following the <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calauthmdl&docsetTarget=p1gq6q7zzt52win1jwhc2b5kuc1z.htm&locale=en#p04ifnaixhf85in1xo7zrr2fgimf">Configure Cross-Origin Resource Sharing</a> documentation. Note that the `allowedOrigins` property does not support using the value `*` to support all origins. You must explicitly add you domain or a list of domains.
+
+## Cross-Site Request Forgery
+
+SAS Viya protects against Cross-Site Request Forgery (CSRF) by blocking requests where the HTTP Referer Header does not match the URI of the requested resource or the `allowedUris` CSRF configuration property. The domain of the site using the SAS Visual Analytics SDK must be allowed in the CSRF configuration by setting `allowedUris` to a regular expression that matches the domain. For example, the regular expression `.*` will match all domains.  See <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calconfigref&docsetTarget=p1fejrlg8b007jn1krvvwzy5q7tn.htm#n0nf0wwa3p7mjhn11926x4k9gl72">SAS Help Center</a> for more information.
+
+## Cross-Site Cookies
+
+The SAS Visual Analytics SDK requires the use of cookies to handle authentication with the SAS Viya Logon service. Browsers require that the response setting the cookie explicitly enable cross-site cookies by setting `samesite=none` on the response header. This is not the default for SAS Viya, so you must configure it to support the SAS Visual Analytics SDK. The `sameSite` configuration option in the `sas.commons.web.security.cookies` definition should be set to `None`, and should be applied globally to all services. See <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calconfigref&docsetTarget=p1fejrlg8b007jn1krvvwzy5q7tn.htm#p0xav129qcxrytn14y2d8rnhdrlm">SAS Help Center</a> for more information.
+
+Note: If you have enabled settings that block cookies in your web browser, then the SAS Visual Analytics SDK cannot authenticate with SAS Viya. Check your settings to make sure your web browser allows third-party cookies.
+
+### HTTPS
+It is also a requirement that SAS Viya be accessed using the HTTPS protocol in order for web browsers to allow cross-site cookies to be set by SAS Viya. This requires that TLS (Transport Layer Security) be enabled on your SAS Viya deployment. See <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calencryptmotion&docsetTarget=n1bktkey9qb5z0n14fji0ss0b453.htm#p11136ylabo3k1n1rwctv2xrn8js">SAS Help Center</a> for more information.
+
+## Allow guest access
+
+The SAS Visual Analytics SDK has the option to connect to SAS Viya using guest authentication. This requires that SAS Viya be set up to enable guest access, and that the guest user has access to the appropriate report content and data. For more information, see 
+<a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calauthmdl&docsetTarget=n067qoyrgu1yohn19nq4ehy8o0b3.htm">SAS Help Center</a>.
diff --git a/documentation/website/versioned_sidebars/version-0.19.0-sidebars.json b/documentation/website/versioned_sidebars/version-0.19.0-sidebars.json
@@ -0,0 +1,29 @@
+{
+  "version-0.19.0-docs": {
+    "Introduction": [
+      "version-0.19.0-getting-started"
+    ],
+    "Guides": [
+      "version-0.19.0-guides/viya-setup",
+      "version-0.19.0-guides/data-driven-content"
+    ],
+    "API Reference": [
+      "version-0.19.0-api-reference",
+      "version-0.19.0-api/SASReportElement",
+      "version-0.19.0-api/SASReportPageElement",
+      "version-0.19.0-api/SASReportObjectElement",
+      "version-0.19.0-api/ReportHandle",
+      "version-0.19.0-api/ObjectHandle",
+      "version-0.19.0-api/ExportPDFOptions",
+      "version-0.19.0-api/MenuItemProvider",
+      "version-0.19.0-api/connectToServer",
+      "version-0.19.0-api/registerDataDrivenContent",
+      "version-0.19.0-api/DataDrivenContentHandle",
+      "version-0.19.0-api/setUseHighContrastReportTheme",
+      "version-0.19.0-api/setLoadingTheme"
+    ],
+    "Resources": [
+      "version-0.19.0-faq"
+    ]
+  }
+}
diff --git a/documentation/website/versions.json b/documentation/website/versions.json
@@ -1,4 +1,5 @@
 [
+  "0.19.0",
   "0.18.0",
   "0.17.0",
   "0.16.0",

diff --git a/examples/SASReportElement.html b/examples/SASReportElement.html
@@ -1,6 +1,6 @@
 <html>
   <head>
-    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
     <style>
       html {
         background-color: #f0f0f0;

diff --git a/examples/SASReportElementJS.html b/examples/SASReportElementJS.html
@@ -5,7 +5,7 @@
         background-color: #f0f0f0;
       }
     </style>
-    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
   </head>
   <body></body>
   <script> 

diff --git a/examples/SASReportObjectElement.html b/examples/SASReportObjectElement.html
@@ -1,6 +1,6 @@
 <html>
   <head>
-    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
     <style>
       html {
         background-color: #f0f0f0;

diff --git a/examples/connectToServer.html b/examples/connectToServer.html
@@ -5,7 +5,7 @@
         background-color: #f0f0f0;
       }
     </style>
-    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"></script>
   </head>
   <body></body>
   <script>

diff --git a/examples/registerDataDrivenContent.html b/examples/registerDataDrivenContent.html
@@ -4,7 +4,7 @@
     <title>SAS Visual Analytics Custom Data Table</title>
     <script
       async
-      src="https://unpkg.com/@sassoftware/va-report-components@0.18.0/dist/umd/va-report-components.js"
+      src="https://unpkg.com/@sassoftware/va-report-components@0.19.0/dist/umd/va-report-components.js"
     ></script>
     <style>
       body {