This wiki has undergone a migration to Confluence found Here

Difference between revisions of "FHIR IG publisher templates"

From HL7Wiki
Jump to navigation Jump to search
 
(13 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
* how users navigate around the pages
 
* how users navigate around the pages
  
From the point of view of an IG Author, the IG template consists of a list of files and documentation that describes how the author writes their own narrative and fits that into the pages described by the template.  
+
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 =
 
= Known IG templates =
  
To use a template, you specify the 'template' parameter in the IG. You can nominate either the official code for a template (where it has one defined that is controlled by the FHIR product director), or the URL of the location of the template.
+
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:
 
List of known IGs:
* "test" (http://gitub.com/fhir/test-template) - a test template the generates all the kinds of things that can be published
 
* "hl7" (http://gitub.com/hl7/fhir-ig-template - the standard template for HL7 published implementation guides
 
* "hl7-au" (http://gitub.com/hl7-au/fhir-ig-template - the standard template for HL7 Australia published implementation guides
 
* "ihe" (todo): the standard template for IHE-published implementation guides
 
  
note to template authors: you can add your template to this list, as a url + documentation, but only the FHIR product director can assign standard codes.  
+
{|
 +
|+
 +
| package id
 +
| description
 +
| documentation
 +
| source
 +
|-
 +
||fhir.test.template
 +
| a test template the generates all the kinds of things that can be published
 +
| Todo
 +
| http://github.com/fhir/test-template
 +
|-
 +
| hl7.fhir.template
 +
| the standard template for HL7 published implementation guides
 +
| ?
 +
| http://github.com/hl7/fhir-ig-template
 +
|-
 +
| hl7.fhir.au.template
 +
| the standard template for HL7 Australia published implementation guides
 +
| ?
 +
| http://github.com/hl7-au/fhir-ig-template
 +
|-
 +
| ihe.fhir.template
 +
| 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 =
 
= Authoring IG templates =
Line 23: Line 47:
 
The information below is for authors of templates and is highly technical. It should only be used by template authors.  
 
The information below is for authors of templates and is highly technical. It should only be used by template authors.  
  
A template contains 3 kinds of artifacts:
+
A template contains 5 kinds of artifacts:
  
* configuration files that describe how resources are rendered into HTML
+
* NPM Package file that describes the template (in package/package.json, use https://github.com/FHIR/test-template/blob/master/package/package.json for a template)
 +
* a configuration file that describes how resources are rendered into HTML (config.json, see https://github.com/FHIR/test-template/blob/master/config.json for an example)
 +
* jekyll templates / _layouts / include files / html files / assets (fonts, images, js, css, ico)
 
* active scripts that generate content as part of the build process
 
* active scripts that generate content as part of the build process
* jekyll templates / include files / html files
+
* 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) (readme.md)
  
In addition to these artifacts which are for the IG publisher, the template must contain documentation that describes how an author adds pages and narrative content to the Implementation guide.
+
== Publishing Templates ==
  
== Template Resolution ==
+
Any template should be authored in a Github repository, and registered with the IG Auto-publisher  - see [[https://github.com/hl7-fhir/auto-ig-builder/blob/master/README.md Auto-IG-Publisher Documentation]]. Whenever commits are pushed to GitHub, a new 'current' version of the template will be published.
  
When accessing a template by its URL:
+
To do a milestone release - that is, one that authors can refer to by version, create a branch in github with the correct version stated in the package/package.json file, and send the tag id as a request to the FHIR product Director
* if the URL specifies a github.com location, then the IG publisher will assume that the template is a github repository and download it directly
 
* if the URL is a file location, then the IG publisher will assume that template is local, and copy all the files
 
* else it will look for [url]\package.tgz, or [url]\package.zip
 
  
When copying the files, all the files will be placed into a \template directory alongside the \temp directory, except for any files in a folder named "jekyll" in the template, which will be copied into the \temp directory - e.g. provided to Jekyll as published content directly
+
== File layout of a Template ==
  
== File layout of a Template ==
+
The template lives in a github location somewhere. There are 3 important folders in the template package:
  
The template lives in a github location somewhere. There are 2 important folders in the template layout:
 
 
* package - must contain a file package.json, with contents as below.  
 
* package - must contain a file package.json, with contents as below.  
* template - contains the actual contents of the template that are distributed
+
* content - contains the content that will go straight into the IG build folder
 +
* scripts - contains the template content - scripts, etc. Must have a template.ini file (see below)
  
Any other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.  
+
Note: other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.  
  
The contents of the \template folder will be copied into \template in the IG that uses the template while it is built. The
+
When an IG template is used:
template folder must contain:  
 
  
* a config.json file (see below)
+
* the files in the template folder will be extracted into a \template directory in the root folder that the IG Publisher is running in
* a jekyll folder (copied into temp for jekyll to process)
+
* 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)
  
The template folder can contain whatever else is needed for processing the template of the scripts
+
== package\package.json ==
 
 
== package.json ==
 
  
 
Use this as a template:
 
Use this as a template:
  
  {
+
{
 
   "name": "[package-id]",
 
   "name": "[package-id]",
 
   "version": "[ver]",
 
   "version": "[ver]",
Line 66: Line 86:
 
   "license": "[license]",
 
   "license": "[license]",
 
   "description": "[description]",
 
   "description": "[description]",
   "author": "[url]"
+
   "author": "[url]",
 +
  "canonical" : "[canonical]"
 
  }
 
  }
  
 
Notes:
 
Notes:
  
* [package-id] must be chosen in association with the FHIR product director
+
* [package-id] must be chosen in accordance with the FHIR package naming convention
* [ver] is under manual control of the author. Use semver
+
* [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
 
* [license] - license of author's choice. Use CC0-1.0 for HL7 published templates
 
* [description] - whatever
 
* [description] - whatever
* [url] - your org/personal website. use http://hl7.org/fhir for HL7 authored templates
+
* [url] - project website (e.g. contact details)
 +
* [canonical] - For IGs authored in GitHub, the GitHub repository URL.
  
 
== config.json ==
 
== config.json ==
  
** note: when the config.json section is replaced by the new Implementation Guide resource, this section will change**
+
This file controls the functionality of the template. It has the following entries (all of which are optional):
 +
 
 +
{
 +
  "defaults" : { .. todo.. },
 +
  "scripts" : {
 +
    "onLoad" : "[filename]",
 +
    "onGenerate" : "[filename]",
 +
    "onJekyll" : "[filename]",
 +
    "onCheck" : "[filename]"
 +
  }
 +
  }
 +
 
 +
=== scripts ===
 +
 
 +
Entry should only be present if the script is in use. file name is relative to the root of the template
 +
 
 +
* onLoad: ant script that runs after the IG resource has been loaded - it can edit the IG resource
 +
* onGenerate: an ant script that runs before any html is generated
 +
* onJekyll: an ant script that runs before running Jekyll
 +
* onCheck: 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 to be 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
 +
 
 +
The following Ant properties are set for all events:
 +
 
 +
* ig.root - the root directory of the IG being processed
 +
* ig.temp - the temp directory where the jekyll source is being assembled
 +
* ig.template - the source folder for the template contnet
 +
* ig.scripts - the source folder for the scripts (the template scripts folder)
 +
* ig.source - the path to "ig-working." - append either xml or json to get the appropriate file
 +
 
 +
=== onLoad ===
 +
 
 +
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 resource has been written to ig-working.xml and ig-working.json in \template
 +
* the ant script must produce the file ig-updated.xml or ig-updated.json 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
 +
 
 +
Notes:
 +
* the Implementation Guide is always in R5 format.
 +
* the xml dest is checked first and then the json dest - if both are produced, the xml one will be used
 +
 
 +
The following additional Ant properties are set for this event:
 +
 
 +
* ig.dest - the path to the "ig-updated." - append either xml or json to get the appropriate file
 +
 
 +
=== onGenerate ===
 +
 
 +
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.
  
This is a json file, which has the same format as the config file documented in the [[IG Publisher Documentation]]. The contents of this file
+
The working ImplementationGuide resource is available at \template\ig-working.xml|json. This can be modified by the template by producing ig-updated.xml or ig-updated.json in \template. If the IG is updated, the following rules apply:
are merged with the json file for the IG. Entries in the template json file overwrite the entries in the IG json file.
 
The principal use of this file is to specify all the templates for the different content.
 
  
In addition, the template json file has the following new entries
+
* the list of resources cannot be changed (though it can be re-ordered, and information about the resources can be changed)
 +
* other than this, the definition can be changed, and the manifest.page, manifest.image, and manifest.other lists can be changed.
 +
* all other changes to the IG will be ignored
  
* still to be documented
+
Note that to help the the template process the script, additional information about the resource is provided in the extension http://tools.fhir.org/StructureDefinition/resource-information. This extension will be removed by the IG publisher after the onGenerate event is called.
  
 +
The following additional Ant properties are set for this event:
  
== Active Scripts ==
+
(none)
  
A template can contain 2 ant build scripts that allow the template to inspect the content of the IG and generate additional content. These will be run at selected points in the build process:
+
=== onJekyll ===
* before-generate.xml - run as soon as all the content is loaded and the resource outputs are generated, but before any html fragments are generated - this is provided so that the template can generate template-config.xml/json and/or to perform pre-processing on resource content (see below)
 
* after-generate.xml - run after all the generation is complete, before Jekyll is run: this the primary template active point to generate whatever additional content the template wants the output files/fragments to contain
 
  
The ant scripts can do whatever is desired, with the following limitations:
+
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 build file should be able to run offline (e.g. only depend on content in the template and from the IG publisher)
+
 
* whatever the script does should run ok on windows, linux, and OSX
+
The ant script may generate it's own HTML fragments, or alter the jekyll template data files etc. The working ImplementationGuide resource is available at \template\ig-working.xml|json (can no longer be modified)
* The IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.
+
 
 +
=== onCheck ===
 +
 
 +
This event is called once Jekyll has finished running, and the output folder is populated, but before the broken ink & security checks are run
  
Note: if you run the IGPublisher jar with the parameter -debug, it will stop and wait for a prompt at the script execution point to allow template authors to inspect the content of the temp folder
+
The ant script may modify the content in \output. The working ImplementationGuide resource is available at \template\ig-working.xml|json (can no longer be modified)

Latest revision as of 01:31, 6 September 2019

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 description documentation source
fhir.test.template a test template the generates all the kinds of things that can be published Todo http://github.com/fhir/test-template
hl7.fhir.template the standard template for HL7 published implementation guides ? http://github.com/hl7/fhir-ig-template
hl7.fhir.au.template the standard template for HL7 Australia published implementation guides ? http://github.com/hl7-au/fhir-ig-template
ihe.fhir.template 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 (in package/package.json, use https://github.com/FHIR/test-template/blob/master/package/package.json for a template)
  • a configuration file that describes how resources are rendered into HTML (config.json, see https://github.com/FHIR/test-template/blob/master/config.json for an example)
  • jekyll templates / _layouts / include files / html files / assets (fonts, images, js, css, ico)
  • 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) (readme.md)

Publishing Templates

Any template should be authored in a Github repository, and registered with the IG Auto-publisher - see [Auto-IG-Publisher Documentation]. Whenever commits are pushed to GitHub, a new 'current' version of the template will be published.

To do a milestone release - that is, one that authors can refer to by version, create a branch in github with the correct version stated in the package/package.json file, and send the tag id as a request to the FHIR product Director

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
  • scripts - 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]",
  "canonical" : "[canonical]"
}

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] - project website (e.g. contact details)
  • [canonical] - For IGs authored in GitHub, the GitHub repository URL.

config.json

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

{ 
  "defaults" : { .. todo.. },
  "scripts" : {
    "onLoad" : "[filename]",
    "onGenerate" : "[filename]",
    "onJekyll" : "[filename]",
    "onCheck" : "[filename]"
  }
 }

scripts

Entry should only be present if the script is in use. file name is relative to the root of the template

  • onLoad: ant script that runs after the IG resource has been loaded - it can edit the IG resource
  • onGenerate: an ant script that runs before any html is generated
  • onJekyll: an ant script that runs before running Jekyll
  • onCheck: 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 to be 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

The following Ant properties are set for all events:

  • ig.root - the root directory of the IG being processed
  • ig.temp - the temp directory where the jekyll source is being assembled
  • ig.template - the source folder for the template contnet
  • ig.scripts - the source folder for the scripts (the template scripts folder)
  • ig.source - the path to "ig-working." - append either xml or json to get the appropriate file

onLoad

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 resource has been written to ig-working.xml and ig-working.json in \template
  • the ant script must produce the file ig-updated.xml or ig-updated.json 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

Notes:

  • the Implementation Guide is always in R5 format.
  • the xml dest is checked first and then the json dest - if both are produced, the xml one will be used

The following additional Ant properties are set for this event:

  • ig.dest - the path to the "ig-updated." - append either xml or json to get the appropriate file

onGenerate

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.

The working ImplementationGuide resource is available at \template\ig-working.xml|json. This can be modified by the template by producing ig-updated.xml or ig-updated.json in \template. If the IG is updated, the following rules apply:

  • the list of resources cannot be changed (though it can be re-ordered, and information about the resources can be changed)
  • other than this, the definition can be changed, and the manifest.page, manifest.image, and manifest.other lists can be changed.
  • all other changes to the IG will be ignored

Note that to help the the template process the script, additional information about the resource is provided in the extension http://tools.fhir.org/StructureDefinition/resource-information. This extension will be removed by the IG publisher after the onGenerate event is called.

The following additional Ant properties are set for this event:

(none)

onJekyll

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. The working ImplementationGuide resource is available at \template\ig-working.xml|json (can no longer be modified)

onCheck

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. The working ImplementationGuide resource is available at \template\ig-working.xml|json (can no longer be modified)