update version 1.6.0 doc (#75)

CHANGELOG.md

@@ -145,3 +145,9 @@
 
 - SAS Viya 2021.2.4 support
 - Bug fixes
+
+## 1.6.0 (March 17, 2022)
+
+- SAS Viya 2021.2.5 support (Report Package version 23)
+- Support SAS Viya fonts with exported SAS Report Packages
+- Bug fixes

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 1.5.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 1.6.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@1.5.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.6.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## Getting Started

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@1.5.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.6.0/dist/umd/va-report-components.js"></script>
 <script>
   window.addEventListener('vaReportComponents.loaded', function() {
     // The SAS Visual Analytics SDK is loaded and ready

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 1.5.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 1.6.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@1.5.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.6.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## SAS Viya setup

documentation/website/versioned_docs/version-1.6.0/api-reference.md

@@ -0,0 +1,34 @@
+---
+id: version-1.6.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>
+```

documentation/website/versioned_docs/version-1.6.0/api/ObjectHandle.md

@@ -0,0 +1,41 @@
+---
+id: version-1.6.0-ObjectHandle
+title: ObjectHandle
+original_id: ObjectHandle
+---
+
+An `ObjectHandle` is used to perform actions on a single object in an open
+report. An object's handle can be obtained using the `getObjectHandle` method
+on a [`ReportHandle`](ReportHandle.md).
+
+When a report element is assigned new attribute values or removed from the DOM,
+any `ObjectHandles` obtained from that element are invalidated and should be
+discarded.
+
+## Methods
+
+### exportData(format: string, options?: ExportDataOptions): Promise\<string>
+Exports a file that contains the object's data, and returns a URL to the file. 
+
+`format` defines the format of the data output file.
+Supported formats: 
+  - `"XLSX"`
+  - `"CSV"`
+  - `"TSV"`
+
+`options` is an [`ExportDataOptions`](ExportDataOptions.md) bundle that modifies properties of the exported data file. 
+
+If no `options` parameter is supplied, the data will be exported using the default option values. 
+
+### exportPDF(options?: ExportPDFOptions): Promise\<string>
+
+Exports a PDF of the report object and returns a URL to the PDF document. 
+
+`options` is an [`ExportPDFOptions`](ExportPDFOptions.md) that controls the format of the exported PDF document. The option `includedReportObjects` does not apply when exporting a report object.
+
+If no `options` parameter is supplied, the report is exported using the default options values.
+
+### refreshData(): void
+
+Refreshes the data for the report object that is controlled by the
+`ObjectHandle`.

documentation/website/versioned_docs/version-1.6.0/api/ReportHandle.md

@@ -0,0 +1,149 @@
+---
+id: version-1.6.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\<ObjectHandle>
+
+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
+<a target="_blank" href="https://documentation.sas.com/?cdcId=vacdc&cdcVersion=default&docsetId=vareportdata&docsetTarget=n1wv50n60ccq86n1nzp6zat1wj64.htm">SAS Help Center</a>.
+
+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\<string>
+
+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 is 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.

documentation/website/versioned_docs/version-1.6.0/getting-started.md

@@ -0,0 +1,78 @@
+---
+id: version-1.6.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 1.6.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 either connecting directly to SAS Viya or exporting a SAS Report Package.  Server setup requirements for connecting to SAS Viya are covered in the [SAS Viya Setup Guide](guides/viya-setup.md).
+
+## 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.