From 0a1a15fbd59871ccbe17401bcdbebe011ecc3819 Mon Sep 17 00:00:00 2001 From: Brad Morris Date: Wed, 18 Aug 2021 12:37:23 -0400 Subject: [PATCH] update version 0.20.0 doc (#52) --- CHANGELOG.md | 7 + README.md | 4 +- documentation/docs/api-reference.md | 2 +- documentation/docs/getting-started.md | 4 +- .../version-0.20.0/api-reference.md | 34 ++++ .../version-0.20.0/api/ReportHandle.md | 149 ++++++++++++++++++ .../version-0.20.0/getting-started.md | 86 ++++++++++ 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 +- 13 files changed, 287 insertions(+), 10 deletions(-) create mode 100644 documentation/website/versioned_docs/version-0.20.0/api-reference.md create mode 100644 documentation/website/versioned_docs/version-0.20.0/api/ReportHandle.md create mode 100644 documentation/website/versioned_docs/version-0.20.0/getting-started.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b20a88d..709dcda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -102,3 +102,10 @@ - SAS Viya 2021.1.3 support - Add setLoadingTheme API - Bug fixes + +## 0.20.0 (Aug 18, 2021) + +- SAS Viya 2021.1.4 support +- Add reloadReport API (ReportHandle) +- Add support for object maximize and detailed data +- Bug fixes diff --git a/README.md b/README.md index 5c5495a..7d9cbde 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.19.0 version of `va-report-components` from UNPKG +as UNPKG and jsDelivr. Here is an example of loading the 0.20.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 3e953ab..2365a76 100644 --- 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 - + + ``` ## SAS Viya setup diff --git a/documentation/website/versioned_docs/version-0.20.0/api-reference.md b/documentation/website/versioned_docs/version-0.20.0/api-reference.md new file mode 100644 index 0000000..d243027 --- /dev/null +++ b/documentation/website/versioned_docs/version-0.20.0/api-reference.md @@ -0,0 +1,34 @@ +--- +id: version-0.20.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 \ + +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.20.0/api/ReportHandle.md b/documentation/website/versioned_docs/version-0.20.0/api/ReportHandle.md new file mode 100644 index 0000000..e407c8f --- /dev/null +++ b/documentation/website/versioned_docs/version-0.20.0/api/ReportHandle.md @@ -0,0 +1,149 @@ +--- +id: version-0.20.0-ReportHandle +title: ReportHandle +original_id: ReportHandle +--- + +A `ReportHandle` is used to control the state of an open report. A report's +handle can be obtained by calling the `getReportHandle` method on a +[`SASReportElement`](SASReportElement.md), +[`SASReportPageElement`](SASReportPageElement.md), or +[`SASReportObjectElement`](SASReportObjectElement.md). + +When a report element is assigned new attribute values or removed from the DOM, +any `ReportHandles` obtained from that element are invalidated and should be +discarded. + +## Methods + +### getObjectHandle(objectName: string): Promise\ + +Get an [ObjectHandle](ObjectHandle.md) for performing actions on a single object +in the report. + +Possible values for `objectName` are the same as the `objectName` attribute on +[`SASReportObjectElement`](SASReportObjectElement.md). The promise is rejected +if the name does not exist in the report. + +[`ObjectHandles`](ObjectHandle.md) are invalidated under the same conditions as +`ReportHandles`. To obtain another one, get a new `ReportHandle` and call +`getObjectHandle` again. + +### setReportParameters(parameters: Object | undefined): void + +Set the state of all the parameters in a report. For information on how +parameters can be added to reports, see the +SAS Help Center. + +If `parameters` is an object, each key in the object should correspond to the +name of a parameter used in the report. Keys are case-sensitive and must +match the name of the parameter exactly. If a key does not match any +parameters in the report, its value is ignored. + +For single value parameters, the value may be a number, string, `Date` +object, `null`, or `undefined`. For parameters that support multiple values, +the value may be also be an array of numbers, strings, or `Date` objects. If +the value given for a parameter is `null`, `undefined`, or the empty string +`''`, that parameter's value will be unset. + +All report parameters missing from the `parameters` argument are reset to +their default values. Calling `setReportParameters` with either an empty +object or `undefined` resets all parameters to their default values. A +parameter's default value is the value it had when the report was first +opened. + +If a parameter is given an invalid value, the value is ignored and the +parameter is neither updated nor reset. Numeric and date values that are out +of range for their parameters are invalid, as are arrays passed to single +value parameters. Strings are valid values for numeric parameters only if +they can be parsed into numbers. Strings are not valid for date and datetime +parameters. + +If a page contains more than one +[`SASReportObjectElement`](SASReportObjectElement.md) using the same report, +parameters set on a `ReportHandle` from one will affect all the others on the +page. Each [`SASReportElement`](SASReportElement.md) and +[`SASReportPageElement`](SASReportPageElement.md) maintains its own report +state, so setting parameters on those elements does not affect other elements +on the page. + +#### Example + +In this example, the parameters `Date`, `Character`, `Multiple Character`, +and `Numeric` get valid values, `OtherNumeric` has its value unset, and +`InvalidNumeric` is left unchanged. If the report contained other parameters +not present in the object, they would be reset to their initial state. + +```javascript +const sasReport = document.getElementById("my-report"); +sasReport.getReportHandle().then((reportHandle) => { + reportHandle.setReportParameters({ + Date: new Date(2020, 0, 1), + Character: "String", + "Multiple Character": ["String 1", "String 2"], + Numeric: 12, + OtherNumeric: null, + InvalidNumeric: "number", + }); +}); +``` + +### updateReportParameters(parameters: Object): void + +Update a subset of the parameters in the report. + +Usage of `updateReportParameters` is the same as `setReportParameters`, +except report parameters missing from the `parameters` argument do not get +reset to their default values. Calling `updateReportParameters` with an empty +object has no effect on the report. + +#### Example + +In this example, the parameters `Character` and `Numeric` get new values, +while all other parameters are left unchanged. + +```javascript +const sasReport = document.getElementById("my-report"); +sasReport.getReportHandle().then((reportHandle) => { + reportHandle.updateReportParameters({ + Character: "String", + Numeric: 12, + }); +}); +``` + +### exportPDF(options?: ExportPDFOptions): Promise\ + +Exports a PDF of the report and returns a URL to the PDF document. + +`options` is an [`ExportPDFOptions`](ExportPDFOptions.md) that controls the format of the exported PDF document. +If no `options` parameter is supplied, the report will be exported using the default options values. + +#### Example + +In this example, custom options are passed in to the export function, and the exported PDF is opened in a new window. + +```javascript +const sasReport = document.getElementById("my-report"); +sasReport.getReportHandle().then((reportHandle) => { + const options = { + orientation: "portrait", + margin: { top: 0.2, bottom: 0.2, units: "inches" }, + includeDetailsTables: true, + includedReportObjects: ["ve38", "ve56"], + }; + + reportHandle.exportPDF(options).then((pdfUrl) => { + // Open the PDF in a new window + window.open(pdfUrl, "_blank"); + }); +}); +``` + +### refreshData(): void + +Refreshes the data for all of the objects in the report. + +### reloadReport(): void + +Reloads the report. This updates all report content and data, which resets all filters and parameters to their default values. diff --git a/documentation/website/versioned_docs/version-0.20.0/getting-started.md b/documentation/website/versioned_docs/version-0.20.0/getting-started.md new file mode 100644 index 0000000..94819f1 --- /dev/null +++ b/documentation/website/versioned_docs/version-0.20.0/getting-started.md @@ -0,0 +1,86 @@ +--- +id: version-0.20.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.20.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 + +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 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 485a14a..53ec0cd 100644 --- a/documentation/website/versions.json +++ b/documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "0.20.0", "0.19.0", "0.18.0", "0.17.0", diff --git a/examples/SASReportElement.html b/examples/SASReportElement.html index 5d33698..2c06816 100644 --- a/examples/SASReportElement.html +++ b/examples/SASReportElement.html @@ -1,6 +1,6 @@ - + - + + - +