update version 0.17.0 doc (#44)

sassoftware · May 19, 2021 · a9b9062 · a9b9062
1 parent 7f73150
commit a9b9062
Show file tree

Hide file tree

Showing 12 changed files with 158 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -84,3 +84,8 @@
 - Support for select all option on list control
 - SAS Viya 2020.1.5 support
 - Bug fixes
+
+## 0.17.0 (May 19, 2021)
+
+- SAS Viya 2021.1.1 support
+- 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.16.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.17.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.16.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## Getting Started

diff --git a/documentation/docs/api-reference.md b/documentation/docs/api-reference.md
@@ -22,7 +22,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.16.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.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.16.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.17.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.16.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## SAS Viya setup

diff --git a/documentation/website/versioned_docs/version-0.17.0/api-reference.md b/documentation/website/versioned_docs/version-0.17.0/api-reference.md
@@ -0,0 +1,33 @@
+---
+id: version-0.17.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)
+
+## 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.17.0/getting-started.md b/documentation/website/versioned_docs/version-0.17.0/getting-started.md
@@ -0,0 +1,109 @@
+---
+id: version-0.17.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.17.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
+
+### 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. See
+<a target="_blank" href="https://developer.sas.com/reference/cors/">developer.sas.com</a> and
+<a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calauthmdl&docsetTarget=p1gq6q7zzt52win1jwhc2b5kuc1z.htm&locale=en#p04ifnaixhf85in1xo7zrr2fgimf">SAS Help Center</a> for more information.
+
+### Cross-Site Request Forgery
+
+SAS Viya servers protect against Cross-Site Request Forgery (CSRF) by blocking requests where the HTTP Referer Header does not match the URI of the requested resource or a URI whitelist. The domain of the site using the SAS Visual Analytics SDK must be whitelisted in the CSRF configuration.  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 and must be configured in order to support the 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.
+
+#### 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 the SAS Viya server using guest authentication. This requires that the SAS Viya system 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>.
+
+## 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/versions.json b/documentation/website/versions.json
@@ -1,4 +1,5 @@
 [
+  "0.17.0",
   "0.16.0",
   "0.15.0",
   "0.14.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.16.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.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.16.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.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.16.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.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.16.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@0.17.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.16.0/dist/umd/va-report-components.js"
+      src="https://unpkg.com/@sassoftware/va-report-components@0.17.0/dist/umd/va-report-components.js"
     ></script>
     <style>
       body {