admin/raven
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Browse Source
This commit is contained in:
John Cardinal
2020-09-08 00:07:17 +00:00
parent 0f3ae9102e
commit e3089a2b2c
1 changed files with 94 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
docs/8.0/ayanova/docs/form-ay-report-edit.md
View File

@@ -7,6 +7,15 @@ HTML and Javascript along with Handlebars templates are used to customize the ex
AyaNova comes with a built in report template editor and reports can be created or customized directly within AyaNova.
## Render process
When a report is rendered the following steps take place behind the scenes:
* A request is made to the server providing a report template ID, selected business object id's or a DataList name and filter / sort options.
* The server retrieves the report template from the database, "re-hydrates" the business objects in memory and feeds the data to the report template to be processed by the Handlebars templating engine
* The resulting HTML document is rendered and converted to a .PDF format document and a download URL is sent back to the user's browser to download and open the .pdf document.
## Report designer template sections
A report template contains several sections:
@@ -15,10 +24,10 @@ A report template contains several sections:
These are the properties of the report outside of the actual report template itself:
* `Name` the name of the report as it is displayed to users for selection
* `Active` status controls report availability. Set to inactive to keep a report but not make it available to users.
* `Roles` controls which User Roles are allowed to access the report. (Note: no matter what is set here, the server will still not provide data to a report if that data is outside of the Roles of the current user)
* `Notes` about the template only displayed in the designer UI
* `Name` the name of the report as it is displayed to users for selection. As with all named objects in AyaNova it must be unique, no two reports can have the same name.
* `Active` this controls report availability to users. Set to inactive to keep a report template in the databse but not make it available to users.
* `Roles` this sets which User Roles are allowed to access the report. (*Security note*: no matter what is set here, the server will still not provide data to a report if that data is outside of the Roles of the current user so reporting is not a way to get access to information that is not permitted for a User)
* `Notes` about the template, only displayed in the designer UI, usually reference notes for the people involved in designing the reports.
### Template
@@ -26,6 +35,7 @@ The main HTML / Handlebars template. This is where the report is defined and is
In order to get up to speed quickly with report design we recommend looking over the stock reports provided as well as referring to the [Handlebars documentation](https://handlebarsjs.com/guide/#what-is-handlebars)
### CSS
This section is provided to define the HTML Cascading Style Sheet for the report document. This section is optional.
@@ -33,7 +43,7 @@ This section is provided to define the HTML Cascading Style Sheet for the report
### JSPreRender
This section is provided as a way to change the data provided to the report *before* it is rendered. You can use this section to alter data that is fed to the report template. Use of the reportPreRender function is optional but it *must* be present in it's default format even if not used.
This section is provided as a way to change the data provided to the report *before* it is rendered. You can use this section to alter data that is fed to the report template. Use of the reportPreRender function is optional but it *must* be present in it's default format even if not used as it is *always* called by the rendering process and will result in an error if missing.
This is the minimum required default definition:
@@ -43,9 +53,9 @@ function reportPreRender(reportData) {
}
```
Note that the SAMPLE DATA section of the user interface in the report designer shows the raw data *before* it is passed to this function, not how it would look *after* this function is run.
Note that the SAMPLE DATA section of the user interface in the report designer shows the raw data *before* it is passed to this function, not how it would look *after* this function is run. If you need to see how the data is shaped after a reportPreRender you can make use of the `ayJSON` helper documented below to view the raw data on the rendered report itself.
A common use for this section would be to insert or change data based on calculations or data fetched from external API's or the AyaNova API itself (see the section regarding API usage below for details).
A common use for the reportPreRender function would be to insert or re-shape data based on calculations or data fetched from external API's or the AyaNova API itself (see the section regarding API usage below for details).
### Helpers
@@ -58,14 +68,80 @@ This is displayed in the report designer user interface when the report designer
If you do not see this section it means the report designer was opened directly without passing through a business object first so there is no current data to display but you can still edit the report as normal. This can happen if you open a report from a History form or use the browser back button to go back to a report that was previously edited or open a report URL directly.
## Render process
## Report data objects
When a report is rendered the following steps take place behind the scenes:
When a report template is processed, business object data is provided to the template along with other data. Some of this data is used internally by the provided helpers and you have full access to these data values in your templates and helper / pre-render scripts.
* A request is made to the server providing a report template ID, selected business object id's or a DataList name and filter / sort options.
* The server retrieves the report template from the database, "re-hydrates" the business objects in memory and feeds the data to the report template to be processed by the Handlebars templating engine
* The resulting HTML document is rendered and converted to a .PDF format document and a download URL is sent back to the user's browser to download and open the .pdf document.
The object provided has the following format:
```{
ayReportData:[...array of business object data...],
ayClientMetaData:{...Client / User data object...},
ayServerMetaData:{...Server data object... }
}
```
### ayReportData
This is the main business object data provided to the template. It will be identical to the object you see in the `SAMPLE DATA` area of the report designer user interface and is fetched from the server using the same method that populates the report when rendered ensuring consistency between design and rendered report.
It is *always* provided as an Array. In the case of a single object it will be an array of one, in the case of multiple objects it will be the same object definition but repeated for each object.
This means that any report should be designed with one or multiple objects in mind so that the same report can be used for both a single object or a collection.
For example if you are reporting off a Customer you would design a report that can handle one or multiple Customer objects so that the same report can be used when viewing a single Customer or a whole list of Customers.
The data provided to the report consists of the same fields visible in the user interface when editing that record and in addition, where appropriate, extra fields to bring in commonly required data from other objects that are linked.
#### Localization
Localization is a *Client* responsibility in AyaNova.
The server is Locale agnostic and doesn't normally process data into localized format but rather leaves that to the Client AyaNova software running on the web browser.
However, because reports are processed *at* the server, the server uses the locale information provided by the Client when requesting the report in the ayClientMetaData property in conjunction with the Helpers provided to localize the data to display according to the Client that requested the report.
Some reports are also generated outside of a Client session, for example when sending a report as an attachment in an email notification, in that case report defaults will be used.
Date and time values: raw Date and time values are provided in the ayReportData object in UTC / GMT time and [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) universal time format. Helpers are used to display this data in the Client default format.
Currency / decimal: currency and decimal number values are provided in simple decimal notation and formatted for display using a Handlebars helper and the Client default format.
Translations: translated text is displayed in the current logged in Client User's default Translation setting using a Handlebars helper.
### ayClientMetaData
When a report is rendered some settings from the Client browser are sent along with the report and are used as required to localize date, time and currency display formats as well as the current logged in User's API credential Bearer token and some other Client dependent settings.
You can see what data is provided by using the ayJson helper as in the example above on the report. As of the time of this writing the current values provided are:
```
ayClientMetaData:
{
"UserName": "AyaNova username",
"Authorization": "Bearer eJhbGciO...token...data...hb9JyjcWl3Tib",
"TimeZoneName": "America/Los_Angeles",
"LanguageName": "en-US",
"Hour12": true,
"CurrencyName": "USD",
"DefaultLocale": "en"
}
```
### ayServerMetaData
When a report is rendered some settings from the local AyaNova Server are injected into the report data and are used as required to access local server relative settings. For example the URL path to the local AyaNova server's API so that API methods can be called directly in the report template relative to the server's local path.
You can see what data is provided by using the ayJson helper as in the example above on the report. As of the time of this writing the current values provided are:
```
ayServerMetaData:
{
"ayApiUrl": "http://127.0.0.1:7575/api/v8/"
}
```
(Note: The value is an example only, your server may report a different value for the api url)
## Built in helpers
@@ -161,70 +237,18 @@ Formats a raw DateTime stamp into a short time only (no date) in the locale form
```{{ ayTime startDate }}```
## Report data objects
When a report template is processed, business object data is provided to the template along with other data. The exact object provided is as follows:
## API Usage
```{
ayReportData:[...array business object data...],
ayClientMetaData:{...object Client / User data...},
ayServerMetaData:{...object server data... }
}
```
Note that you can use the full power of the [AyaNova developer's API](api-intro.md) with your reports to bring in any data from anywhere in AyaNova as required.
### ayReportData
The currently logged in User's API Bearer access token is provided for accessing API routes via the `ayClientMetaData.Authorization` value (see above).
This is the main business object data provided to the template.
You should not store a static copy of an API Bearer access token or hard code it into your templates because it changes regularly and will expire the moment the User logs in to AyaNova.
It is *always* provided as an Array. In the case of a single object it will be an array of one, in the case of multiple objects it will be the same object definition but repeated for each object.
While it is possible to login via a script using alternate credentials and access the API with alternative access to the current logged in user, this opens a security hole as you would need to hard code credentials into the report script and is **absolutely NOT recommended**.
For example if you are reporting off a Customer you would design a report that can handle one or multiple Customer objects so that the same report can be used when viewing a single Customer or a whole list of Customers.
The following is a simple example of access the API via a Helper to retrieve a value:
The data provided to the report consists of the same fields visible in the user interface when editing that record and in addition, where appropriate, extra fields to bring in commonly required data from other objects that are linked.
#### Localization
Localization is a *Client* responsibility in AyaNova.
The server is Locale agnostic and doesn't normally process data into localized format but rather leaves that to the Client AyaNova software running on the web browser.
However, because reports are processed *at* the server, the server uses the locale information provided by the Client when requesting the report in the ayClientMetaData property in conjunction with the Helpers provided to localize the data to display according to the Client that requested the report.
Some reports are also generated outside of a Client session, for example when sending a report as an attachment in an email notification, in that case report defaults will be used.
Date and time values: raw Date and time values are provided in the ayReportData object in UTC / GMT time and [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) universal time format. Helpers are used to display this data in the Client default format.
Currency / decimal: currency and decimal number values are provided in simple decimal notation and formatted for display using a Handlebars helper and the Client default format.
Translations: translated text is displayed in the current logged in Client User's default Translation setting using a Handlebars helper.
## ayClientMetaData
When a report is rendered some settings from the Client browser are sent along with the report and are used as required to localize date, time and currency display formats as well as the current logged in User's API credential Bearer token and some other Client dependent settings.
You can see what data is provided by using the ayJson helper as in the example above on the report. As of the time of this writing the current values provided are:
```
ayClientMetaData:
{
"UserName": "AyaNova username",
"Authorization": "Bearer eJhbGciO...token...data...hb9JyjcWl3Tib",
"TimeZoneName": "America/Los_Angeles",
"LanguageName": "en-US",
"Hour12": true,
"CurrencyName": "USD",
"DefaultLocale": "en"
}
```
## ayServerMetaData
When a report is rendered some settings from the local AyaNova Server are injected into the report data and are used as required to access local server relative settings. For example the URL path to the local AyaNova server's API so that API methods can be called directly in the report template relative to the server's local path.
You can see what data is provided by using the ayJson helper as in the example above on the report. As of the time of this writing the current values provided are:
```
ayServerMetaData: { "ayApiUrl": "http://127.0.0.1:7575/api/v8/" }
```
(Note: The value is an example only, your server may report a different value for the api url)