From 56644412b8cf246aa98aeba393c8c31337bc06a4 Mon Sep 17 00:00:00 2001 From: John Cardinal Date: Wed, 13 Oct 2021 19:57:18 +0000 Subject: [PATCH] --- docs/8.0/ayanova/docs/ay-report-edit.md | 130 ++++++++++++++---------- 1 file changed, 75 insertions(+), 55 deletions(-) diff --git a/docs/8.0/ayanova/docs/ay-report-edit.md b/docs/8.0/ayanova/docs/ay-report-edit.md index 3d8785d4..70bc753e 100644 --- a/docs/8.0/ayanova/docs/ay-report-edit.md +++ b/docs/8.0/ayanova/docs/ay-report-edit.md @@ -20,8 +20,6 @@ When a report is rendered the following steps take place behind the scenes: ## Report designer template sections -The report editor has several sections: - ### Properties These are the general properties of the report: @@ -76,22 +74,22 @@ Footer The main HTML / Handlebars template. This is where the report is defined and is required to render a report. A template is a mixture of both source HTML and Handlebars templates combined with data to generate the final report HTML. -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) +In order to get up to speed quickly with report design we recommend experimenting with copies of the stock report templates provided as well as referring to the [Handlebars documentation](https://handlebarsjs.com/guide/#what-is-handlebars) ### CSS -This section is provided to optionally define your own HTML Cascading Style Sheet for the report document. +This section is provided to optionally define your own HTML Cascading Style Sheet for the report document. Define your styles here and they will be available to the report template. ### Prepare -This section is provided as a way to change the data provided to the report *before* it is rendered. +This section is provided as a way to change the data *before* it is sent to the report template and rendered. -Typically this function is used to retrieve and / or alter data that is fed to the report template. For example changing the data from a list of Customer Units to Group By Customer. +Typically this function is used to retrieve outside data and / or alter data that is fed to the report template. For example changing the data from a list of Customer Units to Group By Customer or adding running totals. -Use of the `ayPrepareData` function is optional but the function *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. +Use of the `ayPrepareData` function is optional and most reports will not require it to be used. -This is the minimum required default definition: +This is the default ayPrepareData method: ``` async function ayPrepareData(ayData) { @@ -99,15 +97,15 @@ async function ayPrepareData(ayData) { } ``` -`ayData` parameter is an object containing all data required to render the report and is detailed below in the [Report Data Objects](#report-data-objects) section. +`ayData` parameter is an object containing three keys with data required to render the report and it's format is detailed below in the [Report Data Objects](#report-data-objects) section. 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 ayPrepareData you can make use of the `ayJSON` helper documented below to view the raw data on the rendered report itself. -A common use for the ayPrepareData 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). +A common use for the ayPrepareData 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). It is defined as an asynchronous function so that the User can all AyaNova or other external API's if necessary to fetch data to insert into the report. For example getting part images from a manufacturers API site to insert into a report document. ### Helpers -This section is for custom [Handlebars helper functions](https://handlebarsjs.com/guide/#custom-helpers) defined by the user. AyaNova comes with many pre-defined helpers documented below, but this section is where you can add your own. Any helper compatible with Handlebars can be defined here. You can even use AyaNova API methods in your helpers if required (see the section regarding API usage below for details). +This section is for custom [Handlebars helper functions](https://handlebarsjs.com/guide/#custom-helpers) defined by the user. AyaNova comes with several [built in Handlebars helpers](#built-in-handlebars-helpers) however, this section is where you can add your own. Any helper compatible with Handlebars can be defined here. You can even use AyaNova API methods in your helpers if required to pull in data from other areas of AyaNova not directly provided in the report data. ### Sample Data @@ -136,7 +134,9 @@ In the report template section you must access these three variables by their na This is the main business object data provided to the template. It will be identical in format 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. Note that the Report Designer Sample Data section shows only a limited subset of the entire data that will be provided to the report as it is intended to be a quick sample to show the structure of that particular data, not all the records. -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. +The data provided is in [JSON](https://www.json.org/) format and can be used directly with Javascript. + +The report data object 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. @@ -144,6 +144,33 @@ For example if you are reporting off a Customer you would design a report that c 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. +#### Numbers, dates, times and translations in report data + +The report data provided comes directly from the Server and is not translated or localized into the current User's format as that is the responsiblity of the "Client" end, see the [Localization and Translation](#localization-and-translation) section for details. + +#### Custom fields in report data + +In AyaNova an object can have up to 16 customizable fields of extra data. In the `SAMPLE DATA` area of the reported editor interface you can see the custom field data, for example: + +``` +"CustomFields": { + "c1": "2019-11-02T00:28:03.3193287Z", + "c2": "Aperiam sequi dolores consequatur temporibus ducimus rerum.", + "c3": 81510873, + "c4": false, + "c5": 0.119726536851249 + }, +``` + +In the above example you can see that there are four custom fields containing data. To access this data in your report template use dot notation to drill down to the custom field desired, for example {{ CustomFields.c1 }} in the template would return the date and time stamp in the above example. + +To format that data into local time zone and display format you would use a date time helper exactly as with non custom fields: {{ ayDT CustomFields.c1 }} would format the time stamp correctly for the user's browser settings. + +Empty or non existent custom fields reference will simply result in nothing being returned for that value, so if your template had {{ CustomFields.c6 }} using the above record would simply return nothing / empty string. + +If the custom field definitions are changed for an object then the reports must also be changed to match. For example if the c1 value was turned into a text field instead of a datetime field then the reports would need to be changed to match (for example removing the ayDT helper as it would now be a text field). + + ### ayClientMetaData When a report is rendered some settings from AyaNova running at the User's browser are sent along with the report and are used as required to provide Translations and localized date, time and currency display formats as per the User's preferences as well as the current logged in User's API credential Bearer token and some other Client dependent settings. @@ -187,49 +214,25 @@ ayServerMetaData: * HasXXLogo - these keys are set to true if a Logo has been uploaded for each size to AyaNova and are useful for controlling whether or not to show a logo on a report template as can be seen in many of our sample reports - -#### Custom fields - -In AyaNova an object can have up to 16 customizable fields of extra data. In the `SAMPLE DATA` area of the reported editor interface you can see the custom field data, for example: - -``` -"CustomFields": { - "c1": "2019-11-02T00:28:03.3193287Z", - "c2": "Aperiam sequi dolores consequatur temporibus ducimus rerum.", - "c3": 81510873, - "c4": false, - "c5": 0.119726536851249 - }, -``` - -In the above example you can see that there are four custom fields containing data. To access this data in your report template use dot notation to drill down to the custom field desired, for example {{ CustomFields.c1 }} in the template would return the date and time stamp in the above example. - -To format that data into local time zone and display format you would use a date time helper exactly as with non custom fields: {{ ayDT CustomFields.c1 }} would format the time stamp correctly for the user's browser settings. - -Empty or non existent custom fields reference will simply result in nothing being returned for that value, so if your template had {{ CustomFields.c6 }} using the above record would simply return nothing / empty string. - -The if the custom field definitions are changed for an object then the reports would need to also be changed to match, so for example if the c1 value was turned into a text field instead of a datetime field then the reports would need to be changed to match (for example removing the ayDT helper as it would now be a text field). - - -#### Localization +## Localization and Translation Localization, the display of Dates, Times, Numbers and AyaNova translated text 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. +The server is Locale and language agnostic and doesn't normally process data into localized format but rather leaves that to the Client AyaNova software running on the web browser and the User's preferences. 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. -Localizable values should display the same in a report as they do in the AyaNova user interface in the browser. +Localizable values will display the same in a report as they do in the AyaNova user interface in the browser when the [built in Handlebars helpers](#built-in-handlebars-helpers) are used. -##### Date and time values +### Date and time values Date and time values are always stored at the server and provided in the ayReportData object in UTC / GMT time and [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) universal time format. The values are converted to the user's local time zone and display format in the AyaNova client software and reports. The `ayDateTime`, `ayDate` and `ayTime` Helpers are used to display this data in the Client default format and time zone. -##### Currency / decimal +### Currency / decimal Currency and decimal number values are provided in simple decimal notation and formatted for display using the `ayCurrency` / `ayDecimal` Handlebars helpers and the Client default language and currency settings. -##### Translations +### Translations Translated text is displayed in the current logged in User's default Translation setting using the `ayT` Handlebars helper. @@ -327,7 +330,7 @@ This helper takes a parameter indicating which size of logo is desired and must For example: -```{{ ayLogo "small" }}``` +```{{ ayLogo 'small' }}``` Will render the small sized logo as an image tag set to the correct API Url. Note that if you do not upload a logo then this will display a broken image icon instead. @@ -360,19 +363,33 @@ AyaNova comes with some utility functions that you can call from your own helper ### Group by -ayGroupByKey +The `ayGroupByKey` function is provided to group the report data by a key name in it. All records in the array are grouped into groups based on the key selected. +The following shows using the ayGroupBy function in the ayPrepareData to reformat a Customer Unit List into groups by Customer name which is provided in the CustomerViz property: +```javascript +async function ayPrepareData(ayData) { + //send the raw report data to the groupByKey function which will return a new array grouped by the key name provided + ayData.ayReportData = ayGroupByKey(ayData.ayReportData, 'CustomerViz') + + //return the data into the pipeline to send to the report template + return ayData; +} +``` + +The data returned is an array of objects with a `group` property containing the value in the group key name and an `items` array containing the matching items for that group. + +The `ayGroupByKey` function does no sorting so the data will be returned in the same order it was originally selected in the data list filter and sort options in AyaNova. So, for example, if you wanted a Customer Unit report grouped by Customer you would likely want to sort the list by Customer first and then by Serial number second so that the resulting report would contain the data ordered sequentially. It is also possible to sort the data in the ayPrepareData method using Javascript if desired however the server is much faster at sorting data tables so for large reports it makes more sense to let the server sort it first by making data table sorting selections before reporting. ## API Usage -Note that you can use the full power of the [AyaNova developer's API](api-intro.md) with your reports to incorporate data from anywhere in AyaNova as required. +The full power of the [AyaNova developer's API](api-intro.md) is available to reports to incorporate data from anywhere in AyaNova as required. The currently logged in User's API Bearer access token is provided for accessing API routes via the `ayClientMetaData.Authorization` value (see above). 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. -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**. +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 for this reason is **absolutely NOT recommended**. ### API convenience functions @@ -398,18 +415,18 @@ The `route` parameter will be automatically prepended with the server local api *Parameters* The `route` parameter is required and will automatically include the current API server URL prepended if not provided (it looks for "http" at the start). For example you can specifiy the `route` parameter as simply the end portion of the route without the slash: "server-info" or the full route to the server from the server URL meta property. For example the full route to fetch data from the `server-info` API route can be constructed as follows: -```let route=`${reportData.ayServerMetaData.ayApiUrl}server-info`;``` +```let route=`${ayData.ayServerMetaData.ayApiUrl}server-info`;``` The `token` parameter is optional and if not provided will be set by default to the current User's access token or you can specify it by using the authorization token provided in the Client data as follows: -```let token=reportData.ayClientMetaData.Authorization;``` +```let token=ayData.ayClientMetaData.Authorization;``` The `data` parameter of a POST route differs for each route and is documented in the developer's API documentation. The following is an example of accessing the API with both a GET and POST action: -``` -async function ayPrepareData(reportData) { +```javascript +async function ayPrepareData(ayData) { //Example API GET method //to fetch data from API server @@ -418,7 +435,7 @@ async function ayPrepareData(reportData) { //Add the data to the main report data object //so it's available to the template - reportData.myData= + ayData.myData= { ServerInfo:await ayGetFromAPI( "server-info" @@ -429,13 +446,13 @@ async function ayPrepareData(reportData) { //using the "search" route //construct the POST object - let searchPostData={phrase: "Fish"}; + let searchPostData={phrase: "fish"}; - reportData.myData.SearchResults = await ayPostToAPI( + ayData.myData.SearchResults = await ayPostToAPI( "search", searchPostData ); - return reportData; + return ayData; } ``` @@ -444,7 +461,10 @@ async function ayPrepareData(reportData) { ## How to link directly to a report The AyaNova client supports directly linking to a report in an URL, primarily for Customer notification purposes. Only single objects can be linked to for reporting, not lists of objects. +Reports can only be viewed by Users who can log in to AyaNova and have rights to view that particular report. -The AyaNova client application expects report urls format as follows: `[PATH_TO_AYANOVA_APP_URL]/viewreport?oid=[objectid]&rid=[reportid]` +(If you need to send a report to someone without them having a login to AyaNova then you would generate the report and send it as a PDF instead.) + +The AyaNova client application requires the report URL format to be as follows: `[PATH_TO_AYANOVA_APP_URL]/viewreport?oid=[objectid]&rid=[reportid]` If the user is not already logged in, they will be prompted to login first before the report is rendered. \ No newline at end of file