advanced customization of certificate templates

[manitra]

Hello,

I came across the documentation about configuring a certificate and wanted something which is a bit more complicated.

Is it possible to somehow use Javascript in the macros (eg. {{eventDate}}) to do all kind of adjustments (like, put default value, use magic worlds like "yesterday" instead of the date of yesterday ...) ?
One of my goal is to show some dates in full literal in my own language (like thursday the fifth of october nineteen eigthy nine but not in english).

I already have the JS functions and/or endpoint to do it but I'm looking for a proper way to do it (without modifying opencrvs-core).

Thank you for your help

[rikukissa]

Hey Manitra! Unfortunately, currently, it is not possible to run completely arbitrary javascript on the certificate values. We have a few built-in Handlebars Helpers for internationalisation, if conditions, date formatting and fetching location details by id. However, these might not be sufficient for your use case. We acknowledge that custom formatting logic is a very common use case and are planning to support this in future releases.

Modifying core is never a good idea, but if you have no choice, I recommend you write your own Handlebars helper. We haven't yet designed how we could allow countries to add custom formatting to their certificates, but my hunch is that it would involve allowing countries to define their own helpers for Handlebars. Transitioning your custom helpers to this format in later versions shouldn't be too difficult.

I hope this helps!

[manitra]

Thank you @rikukissa, sounds crystal clear to me and is very helpful.

As it's a common use case, would you guys feel confortable if I submit a PR which would add a configuration UI where a system admin could add a list of Handlebars helpers (name, description, slug, end-point url).
The slug would be the prefix we put at the left of the field ref.
Eg. It would be loud in the expression {{loud lastname}}

All end-points would follow a defined signature like this (not sure about the data type yet, just a draft idea)
Request
POST /xxxx
{
... raw json data
}

Response
... raw text data

This way, at startup, open-crvs core would register a list of Handlebars helpers which would all have the same implementation which is :

• use the slug as the helper key
• call the end-point with the json data as input (synchronously or asynchronously if the Handlebars API allows it)
• get the raw text result and return it

Thanks to this feature, all country implementors would feel safe about the fact they could do everything they want every where there are handlebars:

• either, there are predefined helpers already implemented
• or, they spawn an endpoint somewhere which does what they want and register it using a simple UI

Ok, I'm always optimistic by nature, so not really sure I'll have the time to do it.
But just in case I manage to squiz this into our next sprint, what do you think about the overal implementation idea ?

[rikukissa]

Thank you so much for your suggestion and proactivity, @manitra. Much appreciated.

I've given some thought to your approach, and I believe there are two main obstacles that unfortunately prevent us from implementing it this way: offline-support and the future design direction we aim to pursue.

Since OpenCRVS needs to operate offline, we ideally want to cache everything to the user's device, including form definitions, certificate templates, and everything else needed for rendering the certificate, including the Handlebar helpers.
You can see this in action for custom form conditionals by looking at v1.3's /conditionals.js handler in Farajaland. The browser fetches that file, stores it for offline use, and from this point forward, all the methods are available for form configuration to use. You can see how core consumes this endpoint here.

Being able to write backend API endpoints for custom helpers would indeed be an incredibly powerful feature, but the user wouldn't be able to make network requests offline. This is why I believe the approach for handlebars helpers should be identical to how conditionals currently operate.

As per my current thinking, the js file exported by country config could look something like:

GET /certificate-helpers.js

export function loud(intl, applicationState) {
  return (nameString) => {
    return nameString.toUpperCase();
  }
}

which would then be available in the certificate as {{loud lastname}}. The outermost function wrapper provides the custom handlebars helpers with useful variables like the localisation function and current application state.

Another factor to consider is our aim to reduce the functionality an admin can perform through the UI and transfer much of that configuration to the country config. I could go on about the reasons, but in summary, we believe most of the configuration should be handled by developers as part of the development cycle. This way, all changes would be versioned, reviewed, tested, and can be redeployed without someone having to log in and add the configuration manually. I have personally configured OpenCRVS for three countries in the past year, and not once have we done it through the UI. And of course, there's a significant difference in complexity between building the UI and storing the values in the database and having a JSON / JS file in the country config repository.

If you still wish to help us by creating a PR for implementing the helpers in this manner, I'm more than happy to review it once you have it working :) We are planning to implement this pretty sure ourselves in any case.

[euanmillar]

@rikukissa @manitra I just submitted this PR which allows you to build configurable handlebar helpers.

[euanmillar]

I was then able to create a multiline handlebar like this in the countryconfig repo here, like this:

import * as Handlebars from 'handlebars'

function wordWrap(text: string, boundary: number) {
  return text
    .split('\n')
    .map(function (line) {
      let pos = 0
      return line
        .split(/\b/)
        .map(function (word) {
          pos += word.length
          if (pos > boundary) {
            pos = 0
            return '\n' + word.trimLeft()
          }
          return word
        })
        .join('')
    })
    .join('\n')
    .split('\n')
}

function insertTspansIntoText(textLines: string[]) {
  let svgString = ''
  let y = 451.418
  for (const line of textLines) {
    svgString += `<tspan x="292.123" y="${y}">${line}</tspan>`
    y += 14 // line height
  }
  return svgString
}

export const wrap: Handlebars.HelperDelegate = function (
  this: any,
  value: string
) {
  const lines = wordWrap(value, 30)
  return insertTspansIntoText(lines)
}

I can use it in the SVG like this:

{{{ wrap deathDescription }}}