update version 1.3.0 doc (#68)

sassoftware · Dec 15, 2021 · 3ca402a · 3ca402a
1 parent c7eb921
commit 3ca402a
Show file tree

Hide file tree

Showing 13 changed files with 184 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -129,3 +129,9 @@
 - SAS Viya 2021.2.1 support
 - Support setUseHighContrastReportTheme API with exported SAS Report Packages
 - Bug fixes
+
+## 1.3.0 (December 15, 2021)
+
+- SAS Viya 2021.2.2 support
+- Support custom report themes with exported SAS Report Packages
+- 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.2.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.3.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.2.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.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.3.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.2.0/dist/umd/va-report-components.js"></script>
+<script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.0/dist/umd/va-report-components.js"></script>
 ```
 
 ## SAS Viya setup

diff --git a/documentation/website/versioned_docs/version-1.3.0/api-reference.md b/documentation/website/versioned_docs/version-1.3.0/api-reference.md
@@ -0,0 +1,34 @@
+---
+id: version-1.3.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.3.0/getting-started.md b/documentation/website/versioned_docs/version-1.3.0/getting-started.md
@@ -0,0 +1,78 @@
+---
+id: version-1.3.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.3.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.3.0/guides/export-report-package.md b/documentation/website/versioned_docs/version-1.3.0/guides/export-report-package.md
@@ -0,0 +1,55 @@
+---
+id: version-1.3.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 Visual Analytics SDK to render the report content. A second HTML page (`packageIndex.html`) is included to give you detailed information about all of the exported report objects and code snippets and to help you incorporate them into your own page. In order to see these HTML pages, deploy all of the report package contents to a web server. Then, navigate a web browser to the URL of the `index.html` or `packageIndex.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)
+
+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/versions.json b/documentation/website/versions.json
@@ -1,4 +1,5 @@
 [
+  "1.3.0",
   "1.2.0",
   "1.1.0",
   "1.0.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.2.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.0/dist/umd/va-report-components.js"></script>
+    <script async src="https://unpkg.com/@sassoftware/va-report-components@1.3.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.2.0/dist/umd/va-report-components.js"
+      src="https://unpkg.com/@sassoftware/va-report-components@1.3.0/dist/umd/va-report-components.js"
     ></script>
     <style>
       body {