User Interface


The CoolCalc user interface is implemented as a static HTML element in any page on your site, for example:

<!-- <div "coolcalc-ui" renders the CoolCalc single page REST UI. -->
<div id="coolcalc-ui" class="coolcalc-restui"></div>

The inner HTML of this element can be empty or you can place a nice branded "spinner" animation inside. When the initial resource (landing page) renders any existing HTML inside the element will be replaced with the landing page resource.

The HTML page where you render the CoolCalc UI requires a few CSS and JavaScript links to CDN hosted libraries, including the CoolCalc JavaScript library, Google maps and Leaflet libraries. Additionally, a few local JavaScript and CSS files are linked.

The static HTML for each of the resources (screens) rendered by the CoolCalc application is hosted on the CoolCalc CDN and imported by the JavaScript library at run-time when the user interface is initialized.

Implementation required on your side:
  • Implement static HTML page on your site for the CoolCalc UI, or add the HTML element and JavaScript/CSS links to any existing page on your site.
  • Add a valid Google maps API key in the link to the Google maps library loader.

Check the sample clients in our Github repository for the current HTML and JavaScript/CSS links.

Note: For native or hybrid mobile apps we recommend rendering the CoolCalc user interface as a web view.
Note: The CoolCalc static HTML is implemented in HTML5. The underlying technology you use to render your web pages is not important to the CoolCalc installation but the page where you render the CoolCalc UI must be rendered with an HTML5 doctype, other doctypes (eg. XHTML or older HTML4 types) may cause unexpected behavior.

HTML skins

The architecture of the CoolCalc applications permits the use of multiple variations of static HTML. Essentially, any static HTML that contains the required DOM elements for a given REST resource can be used to render that resource.

For example, if you had a REST resource with the following structure:

{ "dog" : {
        "breed": "Mutt",
        "favoriteActivity": "Sleep"

Then the CoolCalc user interface libraries can render this resource in any static HTML that contains at minimum the following elements. Labels, wrapper divs, styles or other HTML details will not affect functionality:

<form name="dog">
    <input type="text" name="breed">    
    <input type="text" name="favoriteActivity">

Even replacing the INPUT elements with SELECT elements will still work:

<form name="dog">
    <select name="breed">
        <option>Not a mutt</option>
    <input type="text" name="favoriteActivity">

Given this flexibility the CoolCalc MJ8 application may be configured "out of the box" to use one of two user interface variants available on the CoolCalc CDN:

  • A user interface implemented using the Unkuna front end framework. This user interface is designed as a fixed layout.
  • An alternate user interface implemented using the popular Bootstrap front end framework. This user interface is designed as a fluid layout.

Your choice of user interface variant (skin or flavor if you wish) is entirely aesthetical. The fluid Bootstrap layout is generally considered a more appropriate solution if you have larger branded headers and footers whereas the fixed Unkuna layout was designed for optimum use of visible space with little or no headers and footers.

Implementation required on your side:
  • Switching between the Bootstrap or Unkuna user interfaces is simply a matter of replacing the "skin" URL segment in routes to static HTML, CSS or JavaScript.
  • For the Bootstrap version:
    • /coolcalc/ui/mj8/v-bootstrap/current/restui.html
  • For the Unkuna version:
    • /coolcalc/ui/mj8/v-unkuna/current/restui.html

Local JavaScript

A local JavaScript library contains configurations for your specific installation as well as code to initialize the CoolCalc user interface on page load. In most cases the configuration on the script side is relatively trivial, requiring only a few configuration attributes related to domain names and URLs of the CoolCalc installation.

Implementation required on your side:
  • Verify or edit JavaScript configs in file libmj8.js
    • /coolcalc/javascript/mj8/{skin}/{version}/libmj8.js
  • Verify or edit JavaScript configs in file fun-factory.js
    • /coolcalc/javascript/mj8/{skin}/{version}/fun-factory.js

The local JavaScript library also implements the script side of a few utility features that must be implemented by the client, specifically HTML to PDF conversion and MJ8 report email/share functionality. See the section on customizing CoolCalc for details.

Initializing the UI

On page load, the CoolCalc UI normally opens on the end user's project list. If any of your applications are integrating directly with the CoolCalc API it may be desirable to open the UI on a specific REST resource. This can be accomplished by providing the HATEOAS "self" link of that resource as a "hateoasLink" URL query param.

For example, the "self" link of an MJ8 project with id 2029 may be:

{ "href":"",
    "description":"95 Shorrey Place",

To open the user interface on that resource, open the HTML page where the UI renders with a URL query param "hateoasLink" which contains a JSON stringified representation of the link:

  • { JSON string here }

When your own applications create projects directly in the CoolCalc API by making a POST request to the project list URL, the output of the API will be the updated project list, not the newly created project. The URL of the newly created project will be specified in the HTTP "Location" header in the response to the POST request. Since the HTTP "Location" header is only a URL, opening the user interface on the newly created project requires building the HATEOAS link JSON string manually. You do not need to build all of the attributes, for the purposes of the hateoasLink URL query param the "href" attribute is the only required attribute.

For example, if the HTTP "Location" header in response to a POST request is:

  • ""

You can build the HATEOAS link object as:

  • { "href":"" }

Then you can open the CoolCalc user interface with a stringified representation of the HATEOAS link object:

  • { JSON string here }

Keep in mind that opening the UI on any resource requires that the current session user is the owner of that resource. In the example above, the account nr. of the currently logged in user should be "1626443386"

Previous topic
Server Side Library
Next topic
Rest API