Custom Implementation Guide templates

As you’ll likely be aware, FHIR uses Implementation Guides (IG) to describe how to use FHIR for specific scenarios or use cases. In the past it has been technically challenging to create these guides, but this is changing – in large part due to new tooling/approaches like shorthand and sushi, but also because the FHIR community (and especially Lloyd) have been working on a template based publisher.

The idea behind the template based publisher is that there are a number of standard templates for specific purposes such as an ‘official’ HL7 FHIR IG or a plain template, and these can then be adapted for specific purposes – such as a National IG or a vendor specific one describing a FHIR based implementation. The project is still relatively new, but becoming stable enough that people are able to use it. However, the newness means that the documentation is still catching up, so when my colleague Jose Costa Teixeira offered to write a ‘beginners guide to creating your very own template’ I said great!

He’s published it on his blog, but kindly allowed me to reproduce it here.

Without further ado, take it away Jose…

The Implementation Guide publishing system is one of my favourite things about the FHIR ecosystem. It allows encourages us to have continuously-delivered, self-validating specifications for a project, a realm or a system.

The publishing system takes the content – resources, text, images, etc – and creates a set of web pages that can be published on your own website. It uses a template which defines the behaviour and look-and-feel of the web pages.

While HL7 does provide a set of working templates, chances are you want to change the look and feel of your Implementation Guide, whether you’re working on a project or designing a system.

The Implementation Guide publishing systems allows you to create custom templates.
Note that such templates currently only work for local builds – you can use them locally, but you cannot use a custom template in the CI (Continuous Integration) Build (which is only an issue for ‘official’ HL7 IGs).

Choosing the base template

Choose which of the existing templates contain what you need, and does not contain (a lot of) things that you don’t need, or can’t use – it’s simpler to maintain additions to a template than overrides.

In this example we want to make an implementation guide for a national project. This is not an HL7 project so it does not contain the HL7 logo on the left – so we use the FHIR Base Template.

The IG Base template can be found at https://github.com/HL7/ig-template-base but you don’t have to fetch it – you just have to point to the package name which is fhir.base.template (see image below for some of the existing templates). (see below how this is done)

Understanding custom templates

While this is called a “custom template” you may also think of it as a template extension – because we are actually taking a template and extending it.
Some customizations that are possible:

• Adding or changing images in the template
• Adding html content
• Changing colors
• And more…

Customizing a template means altering the template, so it does require a bit of understanding of how the template works. We’ll see that later. For now, let’s start by using a custom template to change the look and feel of the template: images, color scheme, header and footer.

Creating a custom template for your IG

Follow these steps:

• Make sure that the IG is currently building. The last thing you want to be tracing down errors that aren’t related to your customizations!
• Create a folder for the new template (at the same level as the “input” folder). You can’t call it ‘template’, as that’s the one that the IG publisher creates as it runs (this is quite handy as a source of files to customize later on).
• Add a “package” folder in that template
• Add a file “package.json” in the package folder, with at least:
  • The name of this template
  • The base and dependency that this template builds upon

Example of a package.json file:

{
"name": "ihe.fhir.template",
"version": "0.1.0",
"type": "fhir.template",
"license": "CC0-1.0",
"description": "IHE FHIR Template",
"author": "http://ihe.net",
"canonical": "http://fhir.org/templates/ihe.fhir.template",
"base": "fhir.base.template",
"dependencies": {
    "fhir.base.template": "current"
    }
}

Then tell the IG Publisher that the template to use is your local template – simply give it the folder name.
In your implementation guide’s ig.ini file:

[IG]
ig = input/myig.xml
#template = hl7.fhir.template
template = ihe-ig-template-local
usage-stats-opt-out = false
...

That’s it! This tells the ImplementationGuide publisher to:

• download the base template to the “template” folder
• then overwrite/append the base template with any local files you add in your local template

You can now run your IG publisher, and you will see this in the build log:

The result will still look the same as the base template, because you haven’t added any customizations. But you should try to run it to ensure everything still works.

Adding customizations

You can add customizations by:

• Replacing the template’s files with your own (by putting files with the same name in your custom template)
• Adding new files (by putting files with a different name in your custom template)
• Appending content to some files(by putting files with the same name but prefixed with “_append.” e.g. “_append.fragment-css.html” )

The example below shows the files to add a few changes:

• Add two images to the header. ihe-international.png and ihe.logo.png in package\content\assets\images
  • Adding the reference to these images to fragment-header – by adding a file _append.fragment-header.html
• Add some changes to the footer segment – by adding a file _append.fragment-footer.html
  Add a new stylesheet – it’s better to add and load your own css than to change the FHIR css.
  • Adding the reference to it at the end of the fragment-css.html by adding a file _append.fragment-css.html

This is what the folder structure looks like. Note that the custom template is in the folder ihe-ig-template-local:

When you run the IG Publisher these files will be appended into a final template (you can see the result of this in the ig’s ‘template’ folder).

If you want to see an example, check this template:
https://github.com/IHE/ihe-ig-template
(the folder structure you will see here is somewhat different, but that is just because of the way that files are packaged. We’ll see that later – Publishing a new IG template)