From a9b9062ae00e89e62840b7ecb851257736e41694 Mon Sep 17 00:00:00 2001 From: Brad Morris Date: Wed, 19 May 2021 12:22:44 -0400 Subject: [PATCH] update version 0.17.0 doc (#44) --- CHANGELOG.md | 5 + README.md | 4 +- documentation/docs/api-reference.md | 2 +- documentation/docs/getting-started.md | 4 +- .../version-0.17.0/api-reference.md | 33 ++++++ .../version-0.17.0/getting-started.md | 109 ++++++++++++++++++ documentation/website/versions.json | 1 + examples/SASReportElement.html | 2 +- examples/SASReportElementJS.html | 2 +- examples/SASReportObjectElement.html | 2 +- examples/connectToServer.html | 2 +- examples/registerDataDrivenContent.html | 2 +- 12 files changed, 158 insertions(+), 10 deletions(-) create mode 100644 documentation/website/versioned_docs/version-0.17.0/api-reference.md create mode 100644 documentation/website/versioned_docs/version-0.17.0/getting-started.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 96b5178..e63ff41 100644 --- 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 index afd7536..67cccb7 100644 --- 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 UNPKG and jsDelivr. Here is an example of loading the 0.16.0 version of `va-report-components` from UNPKG +as UNPKG and jsDelivr. 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 - + ``` ## Getting Started diff --git a/documentation/docs/api-reference.md b/documentation/docs/api-reference.md index 501fa34..a46721a 100644 --- 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 - + + ``` ## 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 new file mode 100644 index 0000000..417f05f --- /dev/null +++ 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 \ + +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 + + +``` 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 new file mode 100644 index 0000000..86f1f1b --- /dev/null +++ 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 `` 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` 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 + +``` + +### 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 UNPKG and jsDelivr. 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 + +``` + +## 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 +developer.sas.com and +SAS Help Center 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 SAS Help Center 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 SAS Help Center 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 SAS Help Center 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 +SAS Help Center. + +## Include a custom elements polyfill + +A custom elements polyfill is required for Microsoft Edge support. The following script tag should be added before the `va-report-components` script tag. + +```html + +``` + +## 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/documentation/website/versions.json b/documentation/website/versions.json index 601a128..47a7c55 100644 --- 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 index 2658514..177a56a 100644 --- a/examples/SASReportElement.html +++ b/examples/SASReportElement.html @@ -1,6 +1,6 @@ - + - + + - +