FHIR IG publisher templates

FHIR IG templates are used by the FHIR IG Publishing tool when publishing FHIR Implementation Guides. The templates control:

• the look and feel of the published IG
• the way the resources are expressed as pages
• how users navigate around the pages

From the point of view of an IG Author, the IG template consists of a package they reference, and documentation that describes how the author writes their own narrative and fits that into the pages described by the template.

Known IG templates

To use a template, you specify the 'template' parameter in the IG. You can nominate the official packageId for a template (package ids in the HL7 namespace are assigned by the FHIR product director, and other wise you can make up your own)

List of known IGs:

package id	desdription	documentation	source
fhir.template.test	a test template the generates all the kinds of things that can be published	Todo	http://github.com/fhir/test-template
fhir.template.hl7	the standard template for HL7 published implementation guides	?	http://github.com/hl7/fhir-ig-template
fhir.template.hl7-au	the standard template for HL7 Australia published implementation guides	?	http://github.com/hl7-au/fhir-ig-template
ihe.template.fhir	the standard template for IHE-published implementation guides	?	?

Note to template authors: you can add your template to this table, as a url + documentation, but only the FHIR product director can make a particular template trusted (see below).

Authoring IG templates

The information below is for authors of templates and is highly technical. It should only be used by template authors.

A template contains 5 kinds of artifacts:

• NPM Package file that describes the template
• configuration files that describe how resources are rendered into HTML
• jekyll templates / include files / html files
• active scripts that generate content as part of the build process
• documentation that explains to IG Authors how to use the template (e.g. how an author adds pages and narrative content to the Implementation guide, and what control the author has over the output)

Template Resolution

Templates are resolved as a standard FHIR package (see NPM packages...). Authors must publish their template by [todo... how to publish an IG template package]

File layout of a Template

The template lives in a github location somewhere. There are 3 important folders in the template package:

• package - must contain a file package.json, with contents as below.
• content - contains the content that will go straight into the IG build folder
• template - contains the template content - scripts, etc. Must have a template.ini file (see below)

Note: other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.

When an IG template is used:

• the files in the template folder will be extracted into a \template directory in the root folder that the IG Publisher is running in
• the files in content folder will be extracted into the \temp directory in the root folder that the IG publisher is running in (Jekyll runs in this folder so they are provided to Jekyll as published content directly)

package\package.json

Use this as a template:

{
  "name": "[package-id]",
  "version": "[ver]",
  "type": "fhir.template",
  "license": "[license]",
  "description": "[description]",
  "author": "[url]"
}

Notes:

• [package-id] must be chosen in accordance with the FHIR package naming convention
• [ver] is under manual control of the author. Use semver. You will have to update the version to get IG publisher to pick up new versions
• [license] - license of author's choice. Use CC0-1.0 for HL7 published templates
• [description] - whatever
• [url] - your org/personal website. For IGs authored in GitHub, yse the GitHub repository URL

template\template.ini

This file controls the functionality of the template. It has the following entries (all of which are optional):

 [template]
 ig=[filename] 
 exp-params=[filename]
 on-load=[filename]
 on-generate=[filename] 
 on-jekyll=[filename] 
 on-check=[filename] 

Documentation:

• ig: an implementation guide resource (in R4 format).
• exp-params: a Parameters resource (R4 format) that has basic parameters for any expansions performed during the build

Any content in either of these two resoruce is merged into the IG provided resources (e.g. the IG specific IG over writes the template IG resource)

• on-load: ant script that runs after the template has been loaded
• on-generate: an ant script that runs before any html is generated
• on-jekyll: an ant script that runs before running Jekyll
• on-check: an ant script that runs before checking Jekyll output

Script Events

Notes:

• The Ci-Build (IG auto-publisher) will only accept templates from trusted templates. To get a template trusted, talk to the FHIR Product Director
• if you run the IGPublisher jar with the parameter -debug, it will stop and wait for a prompt at the script execution points (before and after running the ant script) to allow template authors to inspect the content of the folders
• the working diretory when the ant script runs is the base folder for the IG Publisher, not the folder containing the ant scripts
• the special IG resource (for on-load) will always be in R4 version; all the other resources will be in whatever version is specified in the IG
• The build file should be able to run offline (e.g. only depend on content in the template and from the IG publisher)
• the ant scripts can run whatever is supported on windows, linux, and osx. Known supported languages:

 * javascript
 * xslt

on-load

This event exists for a very specific purpose: to allow the template to alter the IG resource itself. At the point that this ant script executes, the following actions have been done:

• the hase specification package has been loaded
• the IG resource has been read
• the template has been located and extracted as described above
• the IG specified in IG in template.ini (if present) has been merged into the IG resource
• the IG resource has been written to ig-working.xml in \template
• the ant script must produce the file ig-updated.xml in \template
• this file will be re-loaded and used as the working IG resource for the rest of the build

The expectation is that the template will update the pages / resources (an maybe the parameters) from after examining the other folders. Changing other files is not supported for this event

on-generate

This event is called once all the resources have been loaded, processed/validated etc, and then all the resources that are going to be produced have been written into the \temp folder (in whatever formats specified by the reloaded IG resource), and the IG publisher is about to produce html fragments.

The ant script may generate it's own HTML content, or alter the jekyll template data files etc

on-jekyll

This event is called once all the html fragments have been produced, and the IG publisher is about to call Jekyll. The \temp folder is ready to go.

The ant script may generate it's own HTML fragments, or alter the jekyll template data files etc

on-check

This event is called once Jekyll has finished running, and the output folder is populated, but before the broken ink & security checks are run

The ant script may modify the content in \output.