docs/8.0/ayanova/docs/ay-report-edit.md

@@ -10,9 +10,9 @@ AyaNova report templates are based upon commonly used web technology and are HTM
 
 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, spins up a temporary "headless" web browser to do the rendering and feeds the data, report template and related objects to the browser to be processed by the Handlebars templating engine
-- The resulting HTML document is rendered and converted to a .PDF format document, saved to a temporary location at the server and a download URL is sent back to the user's browser to download and open the .PDF document.
+-   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, spins up a temporary "headless" web browser to do the rendering and feeds the data, report template and related objects to the browser to be processed by the Handlebars templating engine
+-   The resulting HTML document is rendered and converted to a .PDF format document, saved to a temporary location at the server and a download URL is sent back to the user's browser to download and open the .PDF document.
 
 ## Mobile devices
 
@@ -24,36 +24,40 @@ Note that _viewing_ reports is supported on all devices, only editing is unavail
 
 ### Properties
 
+![report edit form properties tab](img/report-edit-form-properties-tab.png)
+
 These are the general properties of the report:
 
-- `Name` the name of the report as it is displayed to users for selection; no two reports **for the same object type** can have the same name, however you can re-use a name for reports for different AyaNova Types
-- `Who can select` 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)
-- `Type` this controls the Type of AyaNova object for which this report will be offered as an option. This is useful for duplicating a report for use with a different type of object. For example if you have a report made for a Customer type object you can save a copy and change the Type to HeadOffice for use with a Head Office type object as the fields are almost identical so it will work for either object with only slight changes
-- `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
-- `Notes` about the template, only displayed in the designer UI, usually reference notes for the people involved in designing the reports
+-   `Name` the name of the report as it is displayed to users for selection; no two reports **for the same object type** can have the same name, however you can re-use a name for reports for different AyaNova Types
+-   `Who can select` 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)
+-   `Type` this controls the Type of AyaNova object for which this report will be offered as an option. This is useful for duplicating a report for use with a different type of object. For example if you have a report made for a Customer type object you can save a copy and change the Type to HeadOffice for use with a Head Office type object as the fields are almost identical so it will work for either object with only slight changes
+-   `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
+-   `Notes` about the template, only displayed in the designer UI, usually reference notes for the people involved in designing the reports
 
 ### PDF Options
 
+![report edit form pdf tab](img/report-edit-form-pdf-tab.png)
+
 #### overview
 
 Report generation consists of two distinct and separate processes: Processing the the report html template to generate an HTML web page and secondly rendering the generated HTML page to a PDF document for the final report. The PDF Options tab of the report designer controls settings related to the rendering and appearance of the output PDF document which contains the report.
 
 #### PDF settings
 
-- `Display header & footer` if checkmarked then the header and footer templates will be inserted into the output PDF document
-- `Header template` HTML template for the PDF header. Use HTML markup with following classes used to inject special values into them
-  - `date` formatted print date
-  - `title` document title
-  - `url` document location
-  - `pageNumber` current page number
-  - `totalPages` total pages in the document
-- `Footer template` HTML footer template, uses same properties as header template
-- `Paper format` Standard paper size format, choose from list of supported formats
-- `Landscape` Output in Landscape vs Portrait format
-- `Botttom / Left / Top / Right Margin` Margin values formatted as a number and unit. Valid units are `px` - pixel, `cm` - centimeter, `in` - inch, `mm` - millimeters e.g. "11 mm"
-- `Prefer CSS page size` Prioritizes any CSS @page size declared in the page over what is declared in width and height or format options. Defaults is false, which will scale the content to fit the paper size
-- `Print background` print background graphics, default is false. _Must_ be checkmarked for CSS attributes such as alternating table rows to work.
-- `Scale` scales the report rendering, must be a value between 0.1 and 2, the default is 1
+-   `Display header & footer` if checkmarked then the header and footer templates will be inserted into the output PDF document
+-   `Header template` HTML template for the PDF header. Use HTML markup with following classes used to inject special values into them
+    -   `date` formatted print date
+    -   `title` document title
+    -   `url` document location
+    -   `pageNumber` current page number
+    -   `totalPages` total pages in the document
+-   `Footer template` HTML footer template, uses same properties as header template
+-   `Paper format` Standard paper size format, choose from list of supported formats
+-   `Landscape` Output in Landscape vs Portrait format
+-   `Botttom / Left / Top / Right Margin` Margin values formatted as a number and unit. Valid units are `px` - pixel, `cm` - centimeter, `in` - inch, `mm` - millimeters e.g. "11 mm"
+-   `Prefer CSS page size` Prioritizes any CSS @page size declared in the page over what is declared in width and height or format options. Defaults is false, which will scale the content to fit the paper size
+-   `Print background` print background graphics, default is false. _Must_ be checkmarked for CSS attributes such as alternating table rows to work.
+-   `Scale` scales the report rendering, must be a value between 0.1 and 2, the default is 1
 
 #### PDF header / footer template details
 
@@ -98,8 +102,8 @@ Header
 
 ```html
 <span style="font-size:6pt;width: 94%; text-align:left; "
-  >&nbsp;&nbsp;&nbsp;&nbsp;Report rendered
-  on:&nbsp;<span>PDFDate</span>&nbsp;at:&nbsp;<span>PDFTime</span></span
+    >&nbsp;&nbsp;&nbsp;&nbsp;Report rendered
+    on:&nbsp;<span>PDFDate</span>&nbsp;at:&nbsp;<span>PDFTime</span></span
 >
 ```
 
@@ -107,10 +111,10 @@ Footer
 
 ```html
 <span style="font-size:6pt;width: 94%; text-align: right; "
-  >Page&nbsp;<span class="pageNumber"></span>&nbsp;of&nbsp;<span
-    class="totalPages"
-  ></span
-  >&nbsp;&nbsp;&nbsp;&nbsp;</span
+    >Page&nbsp;<span class="pageNumber"></span>&nbsp;of&nbsp;<span
+        class="totalPages"
+    ></span
+    >&nbsp;&nbsp;&nbsp;&nbsp;</span
 >
 ```
 
@@ -120,17 +124,23 @@ If you specify a header or footer without setting a top or bottom margin you wil
 
 ### Report Template
 
+![report edit form template tab](img/report-edit-form-template-tab.png)
+
 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 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. Define your styles here and they will be available to the report template.
+![report edit form css tab](img/report-edit-form-css-tab.png)
+
+This optional 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 _before_ it is sent to the report template and rendered.
+![report edit form prepare tab](img/report-edit-form-prepare-tab.png)
+
+This optional section is provided as a way to prepare / change the data _before_ it is sent to the report template and rendered.
 
 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.
 
@@ -140,7 +150,7 @@ This is the default ayPrepareData method:
 
 ```javascript
 async function ayPrepareData(ayData) {
-  return ayData;
+    return ayData;
 }
 ```
 
@@ -152,11 +162,23 @@ A common use for the ayPrepareData function would be to insert or re-shape data
 
 ### Helpers
 
-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.
+![report edit form helpers tab](img/report-edit-form-helpers-tab.png)
+
+This optional 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
 
-This is displayed in the report designer user interface when the report designer is opened via a business object. The sample data is temporary and displayed for the purpose of assisting during report design as a reference to the field names available to the report.
+![report edit form sample data tab](img/report-edit-form-sample-data-tab.png)
+
+This read only section is for viewing sample data from real objects as a referece to the names of fields and "shape" of the collections available to use in your report template.
+
+Data here is displayed in the report designer user interface when the report designer is opened via a business object. 
 
 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.
 
@@ -273,9 +295,9 @@ ayServerMetaData:
 }
 ```
 
-- ayApiUrl - this is the URL of the server relative to the report generator and is useful for calling AyaNova API methods in your prepare data function to bring in sources of information from other areas of AyaNova that might not be directly available to your report
-- 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
-- Company XXX fields - these fields represent your company information as entered in Global settings to provide a centralized source of information for all reports requiring company contact or address data
+-   ayApiUrl - this is the URL of the server relative to the report generator and is useful for calling AyaNova API methods in your prepare data function to bring in sources of information from other areas of AyaNova that might not be directly available to your report
+-   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
+-   Company XXX fields - these fields represent your company information as entered in Global settings to provide a centralized source of information for all reports requiring company contact or address data
 
 ### Accessing top level meta data from inside nested objects
 
@@ -321,15 +343,15 @@ In AyaNova the `text` option of the `options` property is automatically set to t
 
 #### Gotchas
 
-- Quotes: Be careful how you specify quotation marks around the options property, use full quotes for the inner field and property values and single quotes to enclose the whole string of JSON as in this example:
+-   Quotes: Be careful how you specify quotation marks around the options property, use full quotes for the inner field and property values and single quotes to enclose the whole string of JSON as in this example:
 
 `{{ ayBC ReportFieldName '{ "bcid": "code128"}' }}`
 
-- Validity: certain bar codes (such as UPC) have a built in checksum validity check and will not render if the value is not valid. So, for example, you cannot use any random number as a UPC code, it _must_ contain valid checksum characters. Or for example an EAN-13 code _must_ contain 13 characters or it will not be valid either.
+-   Validity: certain bar codes (such as UPC) have a built in checksum validity check and will not render if the value is not valid. So, for example, you cannot use any random number as a UPC code, it _must_ contain valid checksum characters. Or for example an EAN-13 code _must_ contain 13 characters or it will not be valid either.
 
 If you are using bar codes only for internal purposes there are many forgiving options available such as Code39 barcodes (or Code 3 of 9) which do not require a check digit and can store up to 39 digits or QR Code or PDF417 '2d' bar codes which can store alphanumeric and ad-hoc data suitable for scanning with camera devices.
 
-- Size: Some experimentation scaling and size options maybe be required to ensure bar codes are scannable depending on the rendering medium / equipment and scanner.
+-   Size: Some experimentation scaling and size options maybe be required to ensure bar codes are scannable depending on the rendering medium / equipment and scanner.
 
 #### Advanced usage
 
@@ -428,8 +450,8 @@ For example, let's say you wanted to display the translation for Customer and Wo
 
 ```javascript
 async function ayPrepareData(ayData) {
-  await ayGetTranslations(["Customer", "WorkOrder"]);
-  return ayData;
+    await ayGetTranslations(["Customer", "WorkOrder"]);
+    return ayData;
 }
 ```
 
@@ -462,11 +484,11 @@ The following shows using the ayGroupBy function in the ayPrepareData to reforma
 
 ```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");
+    //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;
+    //return the data into the pipeline to send to the report template
+    return ayData;
 }
 ```
 
@@ -517,24 +539,24 @@ The following is an example of accessing the API with both a GET and POST action
 
 ```javascript
 async function ayPrepareData(ayData) {
-  //Example API GET method
-  //to fetch data from API server
-  //using the "server-info" route
+    //Example API GET method
+    //to fetch data from API server
+    //using the "server-info" route
 
-  //Add the data to the main report data object
-  //so it's available to the template
-  ayData.myData = {
-    ServerInfo: await ayGetFromAPI("server-info")
-  };
+    //Add the data to the main report data object
+    //so it's available to the template
+    ayData.myData = {
+        ServerInfo: await ayGetFromAPI("server-info")
+    };
 
-  //Example API POST method to fetch data from api server
-  //using the "search" route
+    //Example API POST method to fetch data from api server
+    //using the "search" route
 
-  //construct the POST object
-  let searchPostData = { phrase: "fish" };
+    //construct the POST object
+    let searchPostData = { phrase: "fish" };
 
-  ayData.myData.SearchResults = await ayPostToAPI("search", searchPostData);
-  return ayData;
+    ayData.myData.SearchResults = await ayPostToAPI("search", searchPostData);
+    return ayData;
 }
 ```