Summary

Some projects may want to publish their IGs with a different look and feel or changed features. This can be done by creating a custom template (which is a template extension) and pointing the IG Publisher to use that custom template.

We can customize the template by:

• Adding or changing images to the template

• Adding html content

• Changing colors

• etc.

The custom template consists of a local folder under the IG root folder with a "package" folder, which in turn contains:

1. a package.json defining the new template and the base template

2. the files for the extended template

(See below for details)

When publishing the IG, these files are combined (added, replaced, or appended) to the base template, resulting in a custom template.

Changing the custom template

Changing the template means:

• creating the template’s “package” folder and a package.json in it

• adding content files to the custom template folder

• telling the IG publisher to use the local template

To create the package.json, you might find it easiest to copy the one from the HL7 official template. See here more about the contents of package.json.

Next, we add files that add/replace to the base template.

The logic how it works is:

• When the custom template has a file that does not exist in the base, this file from the custom template gets added to the template

• When the custom template has a file that exists in the base, the base file gets replaced by the file from the custom template

• When the custom template has a file named _append.xyz , the content of this file is added to the file named xyz in the base

• (A custom template with no files simply does not change the base templates)

Example

For an example of how a template is customized, the HL7 official template (used exclusively for Implementation Guides published by HL7 International) extends the FHIR base template and can be checked here: https://github.com/HL7/ig-template-fhir

Customize a template

Here is an example customization:

Setting up the local custom template

The first step is to define the custom template's package.json. It must have a unique name, and declare a base (and dependency on) the base template. For example, if we want a template called "myTemplate", the package.json could look like:

{
 "name": "myTemplate",
 "version": "0.1",
 "type": "fhir.template",
 "license": "CC0-1.0",
 "description": "My FHIR Template",
 "base": "hl7.fhir.template",
 "dependencies": {
 "hl7.fhir.template": "0.0.5"
 }
}

Adding an icon to the template

1. Within your local template folder (e.g. myTemplate), create a path "content/assets/images"

2. Inside the images folder put some sort of icon that you"d like in header to your implementation guides (call it for example "myIcon.png") - make sure you have a license to use the image

3. Supplement the header for the template to point to your icon:

   1. Within your local template folder (e.g. myTemplate), create a path "includes"

   2. Create a text file called "_append.fragment-header.html"

   3. In that file put an XHTML fragment that looks like this:

     <div id="hl7-nav"> 
     <a id="hl7-logo" no-external="true" href="yourprojectwebsite.html">
     <img height="50" alt="Visit MyProject" src="assets/images/myIcon.png.png"/>
     </a>

Append a CSS to change the background color

1. Within your local template folder (e.g. myTemplate), create a path "content/assets/css"

2. Create a file called "myproject.css"

3. In that file, set the following styles:

      #segment-footer > .container {background-color: #888888;}
      .navbar-inverse {background-color: #88888;}

4. Supplement the header for the template to point to your css

5. In the "includes" folder created in step 5, create a new file called "_append.fragment-css.html"

6. In that file add the following XHTML fragment:

     <link href="assets/css/myproject.css" rel="stylesheet"/>

Running the publisher

To see the results of the customization - and you should do it often to make sure that the changes do not break the publisher – just run the IG Publisher.

Shared content

Sometimes there is boiler-plate content that needs to be included in multiple implementation guides that leverage a particular template. This might be legal terms, disclaimers, shared use-case information, contact information, etc. Such content can be placed in the 'includes' folder of the template as a .md or .xml file. It can then be referenced using a liquid 'include' from the different IGs that need to use it. For example, {% include burdenReduction.md %}

Liquid templates for narrative

The IG publisher supports a liquid-based approach to defining the narrative content for different types of resources.

TODO - flesh this out