update version 1.1.0 doc (#61)

sassoftware · Oct 20, 2021 · 92104e4 · 92104e4
1 parent 2f22f5c
commit 92104e4
Show file tree

Hide file tree

Showing 16 changed files with 283 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -113,7 +113,13 @@
 ## 1.0.0 (September 15, 2021)
 
 - SAS Viya 2021.1.5 support
-- SAS Viya 2021.2 LTS support
 - Add enablePdfAccessibleTags to ExportPDFOptions
 - Add packageUri API and support exported SAS Report Packages
 - Bug fixes
+
+## 1.1.0 (October 20, 2021)
+
+- SAS Viya 2021.1.6 support
+- SAS Viya 2021.2 LTS support
+- Add exportData API (ObjectHandle)
+- 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 1.0.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.1.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.0.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## Getting Started

diff --git 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
-<script async src="https://unpkg.com/@sassoftware/va-report-components@1.0.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.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 1.0.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.1.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.0.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## SAS Viya setup

diff --git a/documentation/website/versioned_docs/version-1.1.0/api-reference.md b/documentation/website/versioned_docs/version-1.1.0/api-reference.md
@@ -0,0 +1,34 @@
+---
+id: version-1.1.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>
+```
diff --git a/documentation/website/versioned_docs/version-1.1.0/api/ExportDataOptions.md b/documentation/website/versioned_docs/version-1.1.0/api/ExportDataOptions.md
@@ -0,0 +1,32 @@
+---
+id: version-1.1.0-ExportDataOptions
+title: ExportDataOptions
+original_id: ExportDataOptions
+---
+
+ExportDataOptions provides options for customizing the properties of the report data that you want to export. If no option is specified, then the default value is used.
+
+## Options
+
+### `columns: string[]`
+Determines which data columns should be exported by specifying their labels.
+
+### `startRow: number` 
+Determines which row the data should begin with.
+
+default value: `0`
+
+### `endRow: number` 
+Determines which row the data should end with.
+
+default value: `<index of last row of data>`
+
+### `formattedData: boolean` 
+Controls whether formatted or unformatted data is exported. For example, if a data item has a dollar format applied, then exporting the formatted data includes the dollar sign. If this option is set to false, then the data for that item is exported as a raw number.
+
+default value: `true`
+
+### `detailedData: boolean` 
+Specifies whether the data is aggregated (which has fewer columns, rows, or both depending on filters that have been applied) or detailed (which has all available columns and rows).
+
+default value: `false`
diff --git a/documentation/website/versioned_docs/version-1.1.0/api/ObjectHandle.md b/documentation/website/versioned_docs/version-1.1.0/api/ObjectHandle.md
@@ -0,0 +1,33 @@
+---
+id: version-1.1.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. 
+
+### refreshData(): void
+
+Refreshes the data for the report object that is controlled by the
+`ObjectHandle`.
diff --git a/documentation/website/versioned_docs/version-1.1.0/getting-started.md b/documentation/website/versioned_docs/version-1.1.0/getting-started.md
@@ -0,0 +1,78 @@
+---
+id: version-1.1.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.1.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.
diff --git a/documentation/website/versioned_docs/version-1.1.0/guides/export-report-package.md b/documentation/website/versioned_docs/version-1.1.0/guides/export-report-package.md
@@ -0,0 +1,57 @@
+---
+id: version-1.1.0-export-report-package
+title: Export SAS Report Packages
+original_id: export-report-package
+---
+
+The SAS Visual Analytics SDK can be used in two fundamentally different ways. In the most basic setup you are connecting directly to a SAS Viya deployment, delivering reports and data to your web page.  But it can also be used to display report content that has been exported from SAS Visual Analytics and hosted on your own web server. Exporting a report package enables you to use the SAS Visual Analytics SDK while completely disconnected from SAS Viya. The benefit is that your webpage traffic can scale independently from your SAS Viya deployment. This also enables you to skip any [SAS Viya configuration setup](guides/viya-setup.md) necessary for enabling cross-site access from the SAS Visual Analytics SDK.
+
+## How do I export a SAS Report Package?
+
+There are two methods for exporting entire reports or subsets of reports (which enable you to embed individual objects or pages) as a SAS report package. The first method is to use the export feature in SAS Visual Analytics. which enables you to export a report package as a ZIP file. For more information, see <a target="_blank" href="https://documentation.sas.com/?cdcId=vacdc&cdcVersion=default&docsetId=vareports&docsetTarget=p0log1ce8qcj4cn15k0oby258pdb.htm">Exporting SAS Report Packages</a>. This method works well for one-time use and for learning about the supported export features. However, if your data changes regularly, then you might want to use the second method of automating the creation of the report package. You can do this using the reports plug-in to the SAS Viya CLI. For more information, see <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calcli&docsetTarget=n09r8rzfe0xt6gn1krnt75beevgk.htm">CLI Examples: Reports</a>.
+
+## What do I do with the SAS Report Package?
+
+The exported report package includes a sample HTML page (`index.html`) that demonstrates the mechanics of how to use the SAS Visul Analytics SDK to render the report content. In order to see the sample page, deploy all of the report package contents to a web server. Then, navigate a web browser to the URL of the `index.html` file.
+
+When you create a new web page or embed report content into an existing web page, it is common to co-locate the report package content with other assets for the web page. You might want to have a `reportAsests` folder that is deployed along with your HTML file. However, it is possible to put the report package content anywhere that is accessible through a URL.
+
+Once you extract the report package contents and you know where they are deployed, you can reference the content using the `packageUri` property on [`SASReportElement`](api/SASReportElement.md#packageuri-string), [`SASReportPageElement`](api/SASReportPageElement.md#packageuri-string), or [`SASReportObjectElement`](api/SASReportObjectElement.md#packageuri-string). `packageUri` should point to the base location of the package contents, either with an absolute or relative URL. 
+
+```html
+<sas-report-object
+  packageUri="./reportAssets"
+  objectName="ve27"
+></sas-report-object>
+```
+As noted in the `packageUri` API documentation, this property takes the place of `url`, `reportUri`, and `authenticationType` that are used when connecting directly to SAS Viya.
+
+## Why do my report fonts look different from SAS Visual Analytics?
+
+When you use the SAS Visual Analytics SDK to connect directly to SAS Viya, the fonts are loaded from that SAS Viya deployment. This allows the report content to render using the same font that was specified when the report was designed in SAS Visual Analytics. For licensing reasons, SAS cannot redistribute these fonts when a report package is exported. When you use a report package, extra steps are required to ensure that the report content uses the fonts that you intended. These steps are outlined below.
+
+### Define the font face in CSS
+
+Use the [@font-face](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) in your CSS to define the font (or fonts) that are used by the report content. This means you must know the `font-family` name and have access to the font files.
+
+```html
+<style>
+  @font-face {
+    font-family: 'MyFont';
+    src: url('/fonts/MyFont.woff2') format('woff2'),
+         url('/fonts/MyFont.woff') format('woff');
+  }
+</style>
+```
+
+It might be necessary for you to use a font that is not a standard font available in SAS Visual Analytics. To do this, you must first load the font onto SAS Viya by utilizing the SAS Viya CLI fonts plug-in, as shown in <a target="_blank" href="https://documentation.sas.com/?cdcId=sasadmincdc&cdcVersion=default&docsetId=calfonts&docsetTarget=p0z64ee1ufe5vpn1pibg7pzhsgrb.htm">Fonts: CLI Examples</a>. You can then create the report content using that font.
+
+## Are all features and APIs supported?
+
+As mentioned above, `url`, `reportUri`, and `authenticationType` are ignored when you set `packageUri`. The following APIs and features are not supported for report packages:
+* [`exportPDF`](api/ReportHandle.md#exportpdfoptions-exportpdfoptions-promise-string)
+* [`exportData`](api/ObjectHandle.md#exportdataformat-string-options-exportdataoptions-promise-string)
+* [`setUseHighContrastReportTheme`](api/setUseHighContrastReportTheme.md)
+* Custom report themes
+
+Some objects and advanced object functionality are not supported for report packages. Those details are outlined in <a target="_blank" href="https://documentation.sas.com/?cdcId=vacdc&cdcVersion=default&docsetId=varef&docsetTarget=n1tbiwkzea35nin1wbvjdcregjcs.htm#p0bfdy2hrkw4lzn1glyhtfu02t2h">SAS Report Package Reference</a> and further clarifications can be found at <a target="_blank" href="https://documentation.sas.com/?cdcId=vacdc&cdcVersion=default&docsetId=varef&docsetTarget=n1tbiwkzea35nin1wbvjdcregjcs.htm#p080fwv713hlzfn1cjvls3mfg6u0">SAS Report Packages: Frequently Asked Questions</a>.
diff --git a/documentation/website/versioned_sidebars/version-1.1.0-sidebars.json b/documentation/website/versioned_sidebars/version-1.1.0-sidebars.json
@@ -0,0 +1,31 @@
+{
+  "version-1.1.0-docs": {
+    "Introduction": [
+      "version-1.1.0-getting-started"
+    ],
+    "Guides": [
+      "version-1.1.0-guides/viya-setup",
+      "version-1.1.0-guides/export-report-package",
+      "version-1.1.0-guides/data-driven-content"
+    ],
+    "API Reference": [
+      "version-1.1.0-api-reference",
+      "version-1.1.0-api/SASReportElement",
+      "version-1.1.0-api/SASReportPageElement",
+      "version-1.1.0-api/SASReportObjectElement",
+      "version-1.1.0-api/ReportHandle",
+      "version-1.1.0-api/ObjectHandle",
+      "version-1.1.0-api/ExportPDFOptions",
+      "version-1.1.0-api/ExportDataOptions",
+      "version-1.1.0-api/MenuItemProvider",
+      "version-1.1.0-api/connectToServer",
+      "version-1.1.0-api/registerDataDrivenContent",
+      "version-1.1.0-api/DataDrivenContentHandle",
+      "version-1.1.0-api/setUseHighContrastReportTheme",
+      "version-1.1.0-api/setLoadingTheme"
+    ],
+    "Resources": [
+      "version-1.1.0-faq"
+    ]
+  }
+}
diff --git a/documentation/website/versions.json b/documentation/website/versions.json
@@ -1,4 +1,5 @@
 [
+  "1.1.0",
   "1.0.0",
   "0.20.0",
   "0.19.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@1.0.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.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@1.0.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.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@1.0.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.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@1.0.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.1.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@1.0.0/dist/umd/va-report-components.js"
+      src="https://unpkg.com/@sassoftware/va-report-components@1.1.0/dist/umd/va-report-components.js"
     ></script>
     <style>
       body {