Tweaking the FHIR IG Spreadsheets

Sometimes boundaries are good, and other times, they are limits meant to be broken.  I'm usually breaking boundaries.  One of the boundaries imposed by the FHIR IG Builder is it's use of templates.

And, unless you know what you are doing, breaking away from that is challenging, or even just making minor adjustments to make your life easier is a PITA.  But after you have the secret sauce, it's very simple.

The IG Builder runs off a configuration file called ig.ini.

Your's probably looks something like this:
[IG]
ig = input/ImplementationGuide-hl7.fhir.uv.mhealth-framework.json
template = hl7.fhir.template
usage-stats-opt-out = false
copyrightyear = 2020+
license = CC0-1.0
version = 0.1.0
ballotstatus = CI Build
fhirspec = http://build.fhir.org/

Mine looks like this:
[IG]
ig = input/ImplementationGuide-hl7.fhir.uv.mhealth-framework.json
template = #ig-template
usage-stats-opt-out = false
copyrightyear = 2020+
license = CC0-1.0
version = 0.1.0
ballotstatus = CI Build
fhirspec = http://build.fhir.org/

The hash-mark (#) means in this local folder (and yes, you can nest it away in another folder).

I have a folder in my build called ig-template, living right alongside my ig-data folder (yeah, I use SUSHI, you should too).  It is organized this way:

/ig-template
  /content
    /assets
      /css
         assess.css
  /includes
     _append.fragment-css.html
  /package
     package.json

The CSS file contains some CSS classes I wanted to make my IG development easier to work with, because I can say in one class what takes about 10 lines of HTML to do otherwise.  You'll get a view of that in the appendix of the Mobile Health IG I'm working on.

The /includes/_append.fragment-css.html file works with the existing template infrastructure.
<link href="{{site.data.info.assets}}assets/css/bootstrap-glyphicons.css" rel="stylesheet"/>
<link href="{{site.data.info.assets}}assets/css/assess.css" rel="stylesheet"/>

It's an included fragment that the existing templates incorporate into the part of your html page where additional stylesheets can be added.  The {{ and }} stuff is Jekyll related gunge* that basically inserts the value of a specified variable passed to it during the IG Building process.  You don't need to worry about it for the most part, and if you do, you'll figure it out (or perhaps not).


Finally, you need to tell the IG Builder what this package is, what else it needs.  That's what package/package.json does.  Mine looks like this:
{
  "name": "hl7.mhealth.template",
  "version": "0.0.1",
  "type": "fhir.template",
  "license": "CC0-1.0",
  "description": "HL7 Mobile Template - for use with Mobile Health Framework",
  "author": "http://hl7.org/fhir",
  "canonical": "http://github.com/HL7/ig-template-hl7",
  "base": "hl7.fhir.template",
  "dependencies": {
    "hl7.fhir.template": "current"
  }
}

The critical pieces are the values you set for "base", and "dependencies", which tells the IG Builder that your local template is BASED on the hl7.fhir.template.  You could also base it on the IHE FHIR template, or the HL7 base template, or the CDA template.

Essentially, by doing this, you are inheriting ALL of the behavior of the previously existing templates, and the world (headers, footers, all the rest of the gunge), is essentially your oyster (to eat raw or cooked as you desire).

So, now you have in a page a description of how to tweak your FHIR IG Builder templates.

For what it's worth, I'm going to be working on another tweak which will enable readers to comment on the page by creating a JIRA ticket (I already have DISCUS working in prototype form for the V2 to FHIR project).

     Keith

* Gunge is a technical term meaning stuff one developer thinks deeply about that another really just is going to ignore.