From c3bad9a8d30aa176de854c6efc03558c36d29e6e Mon Sep 17 00:00:00 2001 From: Brad Morris Date: Mon, 17 Aug 2020 13:38:42 -0400 Subject: [PATCH 1/2] update doc version to 0.8.0 --- README.md | 4 +- documentation/docs/api-reference.md | 2 +- documentation/docs/getting-started.md | 4 +- .../version-0.8.0/api-reference.md | 32 ++++++ .../version-0.8.0/getting-started.md | 106 ++++++++++++++++++ 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 +- 11 files changed, 149 insertions(+), 10 deletions(-) create mode 100644 documentation/website/versioned_docs/version-0.8.0/api-reference.md create mode 100644 documentation/website/versioned_docs/version-0.8.0/getting-started.md diff --git a/README.md b/README.md index d7941fa..7f521e8 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.7.* version of `va-report-components` from UNPKG +as UNPKG and jsDelivr. Here is an example of loading the 0.8.* 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 d4b908c..0c84b24 100644 --- a/documentation/docs/api-reference.md +++ b/documentation/docs/api-reference.md @@ -21,7 +21,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.8.0/api-reference.md b/documentation/website/versioned_docs/version-0.8.0/api-reference.md new file mode 100644 index 0000000..27b77e8 --- /dev/null +++ b/documentation/website/versioned_docs/version-0.8.0/api-reference.md @@ -0,0 +1,32 @@ +--- +id: version-0.8.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) + +## 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.8.0/getting-started.md b/documentation/website/versioned_docs/version-0.8.0/getting-started.md new file mode 100644 index 0000000..8210f39 --- /dev/null +++ b/documentation/website/versioned_docs/version-0.8.0/getting-started.md @@ -0,0 +1,106 @@ +--- +id: version-0.8.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.8.* 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. CSRF checks are only made on authenticated sessions, so this is not applicable if using `authenticationType="guest"`. If using `authenticationType="credentials"`, 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 `authenticationType="credentials"` in 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. + +### 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 Visual Analytics SDK in your HTML application. diff --git a/documentation/website/versions.json b/documentation/website/versions.json index 3bb1b00..623728d 100644 --- a/documentation/website/versions.json +++ b/documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "0.8.0", "0.7.0", "0.6.0", "0.5.0", diff --git a/examples/SASReportElement.html b/examples/SASReportElement.html index 0a4d147..9f77c65 100644 --- a/examples/SASReportElement.html +++ b/examples/SASReportElement.html @@ -1,6 +1,6 @@ - + - + + - +