Skip to content

Commit e2f7072

Browse files
brmorrbrmorr
authored
update va-report-components v2.7.0 doc and changelog (#63)
1 parent 7162104 commit e2f7072

File tree

3 files changed

+187
-0
lines changed

3 files changed

+187
-0
lines changed

‎sdk/va-report-components/CHANGELOG.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
## 2.7.0 (February 15, 2024)
2+
3+
### Added
4+
- SAS Viya 2024.02 support (Report Package version 43)
5+
- `addEventListener` method on `ReportHandle`
6+
- `removeEventListener` method on `ReportHandle`
7+
- `readyState` property on `ReportHandle`
8+
- `readyStateChanged` event type on `ReportHandle`
9+
110
## 2.6.0 (January 18, 2024)
211

312
### Added

‎sdk/va-report-components/documentation/website/versioned_docs/version-2.7.0/api/ReportHandle.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
id: version-2.7.0-ReportHandle
3+
title: ReportHandle
4+
original_id: ReportHandle
5+
---
6+
7+
A `ReportHandle` is used to control the state of an open report. A report's
8+
handle can be obtained by calling the `getReportHandle` method on a
9+
[`SASReportElement`](SASReportElement.md),
10+
[`SASReportPageElement`](SASReportPageElement.md), or
11+
[`SASReportObjectElement`](SASReportObjectElement.md).
12+
13+
When a report element is assigned new attribute values or removed from the DOM,
14+
any `ReportHandles` obtained from that element are invalidated and should be
15+
discarded.
16+
17+
## Properties
18+
19+
### readyState: string
20+
The ready state of the report. When this value changes, a `readyStateChanged` event is fired on the ReportHandle.
21+
22+
This value can be one of the following:
23+
- `"loading"` when the report is still initializing.
24+
- `"contentLoading"` when the report is still loading its content.
25+
- `"complete"` when the report has finished loading.
26+
- `"error"` when the report encountered an error and could not load.
27+
28+
## Methods
29+
30+
### getObjectHandle(objectName: string): Promise\<ObjectHandle>
31+
32+
Get an [ObjectHandle](ObjectHandle.md) for performing actions on a single object
33+
in the report.
34+
35+
Possible values for `objectName` are the same as the `objectName` attribute on
36+
[`SASReportObjectElement`](SASReportObjectElement.md). The promise is rejected
37+
if the name does not exist in the report.
38+
39+
[`ObjectHandles`](ObjectHandle.md) are invalidated under the same conditions as
40+
`ReportHandles`. To obtain another one, get a new `ReportHandle` and call
41+
`getObjectHandle` again.
42+
43+
### setReportParameters(parameters: Object | undefined): void
44+
45+
Set the state of all the parameters in a report. For information on how
46+
parameters can be added to reports, see the
47+
<a target="_blank" href="https://documentation.sas.com/?cdcId=vacdc&cdcVersion=default&docsetId=vareportdata&docsetTarget=n1wv50n60ccq86n1nzp6zat1wj64.htm">SAS Help Center</a>.
48+
49+
If `parameters` is an object, each key in the object should correspond to the
50+
name of a parameter used in the report. Keys are case-sensitive and must
51+
match the name of the parameter exactly. If a key does not match any
52+
parameters in the report, its value is ignored.
53+
54+
For single value parameters, the value may be a number, string, `Date`
55+
object, `null`, or `undefined`. For parameters that support multiple values,
56+
the value may be also be an array of numbers, strings, or `Date` objects. If
57+
the value given for a parameter is `null`, `undefined`, or the empty string
58+
`''`, that parameter's value will be unset.
59+
60+
All report parameters missing from the `parameters` argument are reset to
61+
their default values. Calling `setReportParameters` with either an empty
62+
object or `undefined` resets all parameters to their default values. A
63+
parameter's default value is the value it had when the report was first
64+
opened.
65+
66+
If a parameter is given an invalid value, the value is ignored and the
67+
parameter is neither updated nor reset. Numeric and date values that are out
68+
of range for their parameters are invalid, as are arrays passed to single
69+
value parameters. Strings are valid values for numeric parameters only if
70+
they can be parsed into numbers. Strings are not valid for date and datetime
71+
parameters.
72+
73+
If a page contains more than one
74+
[`SASReportObjectElement`](SASReportObjectElement.md) using the same report,
75+
parameters set on a `ReportHandle` from one will affect all the others on the
76+
page. Each [`SASReportElement`](SASReportElement.md) and
77+
[`SASReportPageElement`](SASReportPageElement.md) maintains its own report
78+
state, so setting parameters on those elements does not affect other elements
79+
on the page.
80+
81+
#### Example
82+
83+
In this example, the parameters `Date`, `Character`, `Multiple Character`,
84+
and `Numeric` get valid values, `OtherNumeric` has its value unset, and
85+
`InvalidNumeric` is left unchanged. If the report contained other parameters
86+
not present in the object, they would be reset to their initial state.
87+
88+
```javascript
89+
const sasReport = document.getElementById("my-report");
90+
sasReport.getReportHandle().then((reportHandle) => {
91+
reportHandle.setReportParameters({
92+
Date: new Date(2020, 0, 1),
93+
Character: "String",
94+
"Multiple Character": ["String 1", "String 2"],
95+
Numeric: 12,
96+
OtherNumeric: null,
97+
InvalidNumeric: "number",
98+
});
99+
});
100+
```
101+
102+
### updateReportParameters(parameters: Object): void
103+
104+
Update a subset of the parameters in the report.
105+
106+
Usage of `updateReportParameters` is the same as `setReportParameters`,
107+
except report parameters missing from the `parameters` argument do not get
108+
reset to their default values. Calling `updateReportParameters` with an empty
109+
object has no effect on the report.
110+
111+
#### Example
112+
113+
In this example, the parameters `Character` and `Numeric` get new values,
114+
while all other parameters are left unchanged.
115+
116+
```javascript
117+
const sasReport = document.getElementById("my-report");
118+
sasReport.getReportHandle().then((reportHandle) => {
119+
reportHandle.updateReportParameters({
120+
Character: "String",
121+
Numeric: 12,
122+
});
123+
});
124+
```
125+
126+
### exportPDF(options?: ExportPDFOptions): Promise\<string>
127+
128+
Exports a PDF of the report and returns a URL to the PDF document.
129+
130+
`options` is an [`ExportPDFOptions`](ExportPDFOptions.md) that controls the format of the exported PDF document.
131+
If no `options` parameter is supplied, the report is exported using the default options values.
132+
133+
#### Example
134+
135+
In this example, custom options are passed in to the export function, and the exported PDF is opened in a new window.
136+
137+
```javascript
138+
const sasReport = document.getElementById("my-report");
139+
sasReport.getReportHandle().then((reportHandle) => {
140+
const options = {
141+
orientation: "portrait",
142+
margin: { top: 0.2, bottom: 0.2, units: "inches" },
143+
includeDetailsTables: true,
144+
includedReportObjects: ["ve38", "ve56"],
145+
};
146+
147+
reportHandle.exportPDF(options).then((pdfUrl) => {
148+
// Open the PDF in a new window
149+
window.open(pdfUrl, "_blank");
150+
});
151+
});
152+
```
153+
154+
### refreshData(): void
155+
156+
Refreshes the data for all of the objects in the report.
157+
158+
### reloadReport(): void
159+
160+
Reloads the report. This updates all report content and data, which resets all filters and parameters to their default values.
161+
162+
### addEventListener(eventType: string, listener: (event: Object) => void)
163+
164+
Adds an event listener to the `ReportHandle` to call the supplied listener when the specified event occurs.
165+
166+
#### Arguments
167+
168+
`eventType` is a string that represents the event type to listen for. These event types are supported:
169+
- `"readyStateChanged"` for listening to changes on the `readyState` property.
170+
171+
`listener` is an event listener callback function. When the event occurs, `listener` is called and passed an event object containing the following properties:
172+
- `type` is a string that matches the event type.
173+
- `target` refers to the ReportHandle that the event occurred on.
174+
175+
### removeEventListener(eventType: string, listener: (event: Object) => void)
176+
177+
Removes the previously registered event listener from the `ReportHandle`.

‎sdk/va-report-components/documentation/website/versions.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[
2+
"2.7.0",
23
"2.6.0",
34
"2.5.0",
45
"2.4.0",

0 commit comments

Comments
 (0)