docs/8.0/ayanova/docs/form-adm-global-logo.md

@@ -1,4 +1,4 @@
-# ADM-GLOBAL-LOGO Documentation under construction
+# ADM-GLOBAL-LOGO (documentation under construction)
 
 Upload business logo's here.
 Used for login form and reporting.

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

@@ -0,0 +1,127 @@
+# REPORT TEMPLATE EDITOR
+
+AyaNova report templates are html based template documents that are used with the [Handlebars](https://handlebarsjs.com/) templating language to generate html documents that are rendered to .PDF [Portable document format](https://en.wikipedia.org/wiki/PDF) files.
+
+HTML and Javascript along with Handlebars templates are used to customize the existing reports in AyaNova and make new ones.
+
+AyaNova comes with a built in report template editor and reports can be created or customized directly within AyaNova.
+
+
+## Report designer template sections
+
+A report template contains several sections: 
+
+### Properties 
+
+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
+
+### Template 
+
+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)
+
+### CSS 
+
+This section is provided to define the HTML Cascading Style Sheet for the report document.  This section is optional.
+
+
+### 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 is the minimum required default definition:
+
+```
+function reportPreRender(reportData) {    
+    return reportData;
+}
+```
+
+Note that the SAMPLE DATA section of the user interface in the report designer shows the raw data as it is passed to this function, *not* how it would look after this function is run.
+
+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).
+
+### 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).
+
+### 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.  
+
+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
+
+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.
+
+
+
+## Built in helpers
+
+Several helpers are pre-defined for use with reports:
+
+### ayCaps
+
+Format value as all capitals: 
+
+```{ ayCaps ReportFieldName }}```
+
+
+### ayMarkdown
+
+Format a Markdown formatted field such as a Wiki field on an object into HTML in a similar manner to how they are displayed in the AyaNova user interface WIKI fields:
+
+```{ ayMarkdown wiki }}```
+
+
+### ayJSON
+
+Outputs a block of javascript in JSON format.  Used primarily for diagnosing issues when using the designer to view script or data objects as text data right in the report, for example:
+
+```{{ ayJSON ayClientMetaData }}```
+
+Will output the Client meta data sent along with the report request from the Client as text viewable on the report.
+
+
+### ayLink
+
+Format an URL properly in the displayed document:
+
+```{ ayLink text_displayed url_link }}```
+
+e.g. 
+
+```{ ayLink 'AyaNova website' 'https://www.ayanova.com' }}```
+
+Will display as text and url: [AyaNova website](https://www.ayanova.com)
+
+
+### ayLogo
+
+Used to display your business logo that was previusly uploaded via the [Global settings logo page](form-adm-global-logo.md)
+This helper takes a parameter indicating which size of logo is desired and must be one of the following values: `small`, `medium`, `large`
+
+For example:
+
+```{{ 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.
+
+
+## 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:

server/AyaNova/biz/ReportBiz.cs

@@ -409,7 +409,7 @@ namespace AyaNova.Biz
 #endif
                     //compile and run handlebars template              
 
-                    var compileScript = $"Handlebars.compile(`{report.Template}`)({{ ayReportData:ayPreRender({ReportData}), ayClientMetaData:{clientMeta}, ayApiUrl:{apiUrl} }});";
+                    var compileScript = $"Handlebars.compile(`{report.Template}`)({{ ayReportData:ayPreRender({ReportData}), ayClientMetaData:{clientMeta}, ayApiUrl:`{apiUrl}` }});";
                     var resultHTML = await page.EvaluateExpressionAsync<string>(compileScript);
 
                     //render report as HTML              

server/AyaNova/resource/rpt/ay-report.js

@@ -1,9 +1,9 @@
 function ayRegisterHelpers() {
-  Handlebars.registerHelper("aycaps", function (aString) {
+  Handlebars.registerHelper("ayCaps", function (aString) {
     return aString.toUpperCase();
   });
 
-  Handlebars.registerHelper("aymarkdown", function (astring) {
+  Handlebars.registerHelper("ayMarkdown", function (astring) {
     return marked(astring, { breaks: true });
   });
 
@@ -11,13 +11,19 @@ function ayRegisterHelpers() {
     return JSON.stringify(obj, null, 3);
   });
 
-  Handlebars.registerHelper("link", function(text, url) {
+  Handlebars.registerHelper("ayLink", function (text, url) {
     var url = Handlebars.escapeExpression(url),
-        text = Handlebars.escapeExpression(text)
-        
-   return new Handlebars.SafeString("<a href='" + url + "'>" + text +"</a>");
-});
-}
+      text = Handlebars.escapeExpression(text);
+
+    return new Handlebars.SafeString("<a href='" + url + "'>" + text + "</a>");
+  });
+
+  Handlebars.registerHelper("ayLogo", function (size) {
+    var url = `${Handlebars.escapeExpression(this.ayApiUrl)}logo/${size}`;
+    return new Handlebars.SafeString("<img src='" + url + "'/>");
+  });
+
+}//eof
 
 function ayPreRender(theReportData) {
   if (typeof reportPreRender === "function") {