informatics-isi-edu / ermrestjs

ERMrest client library in JavaScript
Apache License 2.0
4 stars 3 forks source link

Ability to define global templating configuration #908

Open RFSH opened 3 years ago

RFSH commented 3 years ago

Consider these two use cases:

  1. When we introduced handlebars, since we didn't want to break backwards compatibility, we decided to leave the default template_engine as mustache. But we never discussed about the plan to change this default. So we should introduce a way that data-modelers can globally change this default.
  2. In some cases we might want to write a markdown_pattern that is using a static value that is shared throughout the whole catalog. For example, let's say that we want to prepend all the Titles with the project name. Or in case of google-dataset annotation, we have to define creator, license, and usageInfo in all the tables. In these cases, it would be useful if data-modelers could define a global object that they can use everywhere. With this, if they ever need to change any of these static values, they don't have to change multiple places and they would just need to change the global object.

Therefore, we decided to introduce a new chaise-config properly called templating, which has the following format:

{
  "templating": {
    "engine": "mustache|handlebars", // the default engine
    "environment": {
      "static": {
        // define the static global object here
      },
      "dynamic": {
        // we're not going to implement this now but we might want something like this in the future
      }
    }
  }
}

ERMrestJS will use the defined "static" object as the starting object and will add other variables to it. We're not going to enforce any rules for the names chosen in this object and data-modelers should just make sure these names don't clash with the ones that chaise ERMrestJS generates. So the convention is to begin each attribute key with $ under the static object. An example of this chaise-config property would be

{
  "templating": {
    "engine": "mustache|handlebars", // the default engine
    "environment": {
      "static": {
        "$gudmap_static": {
          "consortium": "gudmap"
        },
        "$language": "en-US"
      }
    }
  }
}

Which can be used like this

www.{{{$gudmap_static}}}.org

or

"tag:isrd.isi.edu,2021:google-dataset": {
  "detailed": {
    "dataset": {
       "inLanguage": "{{{$language}}}",
       ...
    }
  }
}
RFSH commented 2 years ago

The engine property has been implemented. So only the environment is left that requires further discussion.