From e2f70723c836803ca4773611afd8a12199e024af Mon Sep 17 00:00:00 2001 From: Brad Morris Date: Thu, 15 Feb 2024 09:03:11 -0500 Subject: [PATCH] update va-report-components v2.7.0 doc and changelog (#63) --- sdk/va-report-components/CHANGELOG.md | 9 + .../version-2.7.0/api/ReportHandle.md | 177 ++++++++++++++++++ .../documentation/website/versions.json | 1 + 3 files changed, 187 insertions(+) create mode 100644 sdk/va-report-components/documentation/website/versioned_docs/version-2.7.0/api/ReportHandle.md diff --git a/sdk/va-report-components/CHANGELOG.md b/sdk/va-report-components/CHANGELOG.md index 3ce3d2f..c7ba713 100644 --- a/sdk/va-report-components/CHANGELOG.md +++ b/sdk/va-report-components/CHANGELOG.md @@ -1,3 +1,12 @@ +## 2.7.0 (February 15, 2024) + +### Added +- SAS Viya 2024.02 support (Report Package version 43) +- `addEventListener` method on `ReportHandle` +- `removeEventListener` method on `ReportHandle` +- `readyState` property on `ReportHandle` +- `readyStateChanged` event type on `ReportHandle` + ## 2.6.0 (January 18, 2024) ### Added diff --git a/sdk/va-report-components/documentation/website/versioned_docs/version-2.7.0/api/ReportHandle.md b/sdk/va-report-components/documentation/website/versioned_docs/version-2.7.0/api/ReportHandle.md new file mode 100644 index 0000000..ba7a4f8 --- /dev/null +++ b/sdk/va-report-components/documentation/website/versioned_docs/version-2.7.0/api/ReportHandle.md @@ -0,0 +1,177 @@ +--- +id: version-2.7.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. + +## Properties + +### readyState: string +The ready state of the report. When this value changes, a `readyStateChanged` event is fired on the ReportHandle. + +This value can be one of the following: + - `"loading"` when the report is still initializing. + - `"contentLoading"` when the report is still loading its content. + - `"complete"` when the report has finished loading. + - `"error"` when the report encountered an error and could not load. + +## 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 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. + +### addEventListener(eventType: string, listener: (event: Object) => void) + +Adds an event listener to the `ReportHandle` to call the supplied listener when the specified event occurs. + +#### Arguments + +`eventType` is a string that represents the event type to listen for. These event types are supported: +- `"readyStateChanged"` for listening to changes on the `readyState` property. + +`listener` is an event listener callback function. When the event occurs, `listener` is called and passed an event object containing the following properties: +- `type` is a string that matches the event type. +- `target` refers to the ReportHandle that the event occurred on. + +### removeEventListener(eventType: string, listener: (event: Object) => void) + +Removes the previously registered event listener from the `ReportHandle`. diff --git a/sdk/va-report-components/documentation/website/versions.json b/sdk/va-report-components/documentation/website/versions.json index d692420..eef4295 100644 --- a/sdk/va-report-components/documentation/website/versions.json +++ b/sdk/va-report-components/documentation/website/versions.json @@ -1,4 +1,5 @@ [ + "2.7.0", "2.6.0", "2.5.0", "2.4.0",