Customizing your CoolCalc installation


Static HTML and CSS

The CoolCalc CDN contains CSS required for the proper rendering and functionality of the user interface. A much smaller local CSS file is used for local styles related only to visual appearance. You can edit the local CSS as required for visual appearance and branding.

From your web root, the typical location of the local CSS file is:

  • Bootstrap version:
    • /coolcalc/local-assets/css/mj8/v-bootstrap/current/coolcalc.css
  • Unkuna version:
    • /coolcalc/local-assets/css/mj8/v-unkuna/current/coolcalc.css

The HTML page where you render the CoolCalc user interface can be designed any way you like as long as the DOM element where the user interface renders is present. HTML outside the DOM element where the CoolCalc UI renders does not affect functionality.

From your web root, the typical location CoolCalc user interface is:

  • Bootstrap version:
    • /coolcalc/ui/mj8/v-bootstrap/current/restui.html
  • Unkuna version:
    • /coolcalc/ui/mj8/v-unkuna/current/restui.html

Static HTML for the CoolCalc REST resources (screens inside the CoolCalc UI) is hosted on the CoolCalc CDN. Clients who wish to do an extensive degree of customization may host the static HTML for the CoolCalc REST resources locally. If you prefer to host the static HTML locally please contact our development team.

Implementation required on your side:
  • Edit local CSS for visual appearance.
Note: Beauty is in the eye of the beholder :)

MJ8 Reports

Static HTML for the downloadable MJ8 report is hosted on your local server so you can customize the look and feel of the report. You can add OEM, distributor or contractor logos and branding as is appropriate for your installation.

From your web root, the typical URL to the static HTML for the downloadable MJ8 report is:

  • Bootstrap version, staging and current:
    • /ui/mj8/v-bootstrap/staging/mj8-report.html
    • /ui/mj8/v-bootstrap/current/mj8-report.html
  • Unkuna version, staging and current:
    • /ui/mj8/v-unkuna/staging/mj8-report.html
    • /ui/mj8/v-unkuna/current/mj8-report.html

In most cases customizing this HTML will require nothing more than adding a branded header and/or footer. If you want to do more extensive customization keep in mind that certain attributes like HTML ids, data-khipu-role and data-coolcalc-role attributes are required for the correct rendering of the JSON data. If you have any doubts as to specific changes in the HTML please contact our development team.

Implementation required on your side:
  • Add your brand or logo to the static HTML for the downloadable MJ8 report

The README files in the Github repository indicate the location of the MJ8 report static HTML for each specific client.


PDF conversion

Static HTML for the downloadable MJ8 report is hosted by the client to allow for custom branding of the MJ8 reports. HTML to PDF conversion for MJ8 reports must be implemented on the client side but the boilerplate CoolCalc libraries includes sample code that can be easily adapted to most installations.

Overview of MJ8 report to PDF implementation:

  1. The CoolCalc JavaScript library automatically assigns a click handler to the "Download PDF" button in the user interface. This click handler invokes the function returned by myFunFactory.PDFHandler in the local JavaScript library.
  2. In it's default implementation, the anonymous function returned by myFunFactory.PDFHandler makes an HTTP POST request to an endpoint on your server identified in attribute myFunFactory.PDFURL.
  3. The payload of the POST request contains a JSON string with the HTML URL of the MJ8 report. Your local endpoint only needs to convert the HTML to PDF.
  4. In its default implementation the anonymous function returned by myFunFactory.PDFHandler expects the response from your local endpoint to be a JSON payload with a first level attribute "FileUrl" which indicates the URL of the created PDF. The anonymous handler then opens the PDF at the given URL.
Implementation required on your side:
  • Implement a local endpoint that converts a given HTML URL to PDF (step 3 above).
  • Verify attribute myFunFactory.PDFURL correctly identifies the URL of your local HTML to PDF endpoint.

You can use any library or API of your choice for email send functionality.


Unauthenticated users

If you want to make the CoolCalc applications available to unauthenticated users there are a few additional considerations.

In CoolCalc all projects must be assigned to an account nr (customer identification) which is unique in the scope of your application and cannot be empty. To the CoolCalc API it does not matter if this customer is known to you or not. If the user is not authenticated (you do not know who they are) you must generate a unique “John or Jane Doe” id for the duration of the session. Your application provides the “John or Jane Doe” id to the CoolCalc API the same way as you provide a known user's identification.

If the unauthenticated user at some point becomes known (logs in or creates an account) your application can make a special PUT request to the CoolCalc API to update the work that was done by the user while unauthenticated to the known users account nr.


CSRF protection

If your web server implements CSRF protection it's typically necessary to inject a CSRF hander function to the CoolCalc JavaScript library. The CoolCalc JavaScript library accepts an anonymous function with input param "xhr" as CSRF handler. You can implement the internal details as appropriate for the CSRF protection implemented on your server. The CoolCalc JavaScript library will automatically invoke the injected handler prior to any XHR (ajax) request.

Implementation required on your side:
  • Implement myFunFactory.CSRFHandler in the local JavaScript library as appropriate for the CSRF protection implemented on your local server.

Custom REST resources

If required, your local server-side library can inject custom REST resources in the application flow above and beyond the REST resources provided by the CoolCalc API. In order to inject custom REST resources the following steps are required:

  • Implement a local endpoint on your server that provides the static HTML for your custom resources. The static HTML is provided as a JSON object with the key => value pairs representing the custom resource name and the corresponding static HTML.
  • Implement the JSON output for the custom resource in your local server-side library.
  • Optionally implement a custom "render" handler in the local JavaScript library if rendering the custom resource requires any specifics on the script side.

The JSON output of your custom resource should follow the following format:

{ "myResourceName": {  // Some interesting data here  },
    "navTrail": [],
    "links": [
        { "rel": "self", "href": "" }
    ]
}
Note: The Java example in our Github repository includes a custom "MJ8 preview" resource which is used during the unauthenticated to authenticated user flow. For help designing or implementing custom REST resources please contact our development team.

Previous topic
Rest API Resources
Next topic
FAQ's