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
Line 38: Line 38:
 
* else it will look for [url]\package.tgz, or [url]\package.zip  
 
* 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 "content" in the template, which will be copied into the \temp directory - e.g. provided to Jekyll as published content directly
+
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 ==
Line 48: Line 48:
 
Any other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.  
 
Any other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.  
  
The template folder has the following rules for it's content:  
+
The contents of the \template folder will be copied into \template in the IG that uses the template while it is built. The
 +
template folder must contain:  
  
* it must contain a conf.json file - content see below
+
* a config.json file (see below)
* anything in a "jekyll" folder gets passed straight through to Jekyll for generation - this is the core html / layout part of the template
+
* a jekyll folder (copied into temp for jekyll to process)
* it can contain any other folders - these are available to the script events (see below) but not published
+
 
 +
The template folder can contain whatever else is needed for processing the template of the scripts
  
 
== package.json ==
 
== package.json ==
Line 75: Line 77:
 
* [url] - your org/personal website. use http://hl7.org/fhir for HL7 authored templates
 
* [url] - your org/personal website. use http://hl7.org/fhir for HL7 authored templates
  
== Configuration file ==
+
== config.json ==
 +
 
 +
** note: when the config.json section is replaced by the new Implementation Guide resource, this section will change**
 +
 
 +
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
 +
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
 +
 
 +
* still to be documented
  
...to document...
 
what goes in here:
 
* default templates and resources locations
 
  
 
== Active Scripts ==
 
== Active Scripts ==
Line 92: Line 101:
 
* The IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.  
 
* The IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.  
  
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  
+
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
 
 
== Jekyll template files ==
 
 
 
Any files in "content" will be passed through untouched to the Jekyll build directory
 

Revision as of 07:29, 22 May 2018

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 list of files 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 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.

List of known IGs:

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.

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 3 kinds of artifacts:

  • configuration files that describe how resources are rendered into HTML
  • active scripts that generate content as part of the build process
  • jekyll templates / include files / html files

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.

Template Resolution

When accessing a template by its URL:

  • 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

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.
  • template - contains the actual contents of the template that are distributed

Any 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 template folder must contain:

  • a config.json file (see below)
  • a jekyll folder (copied into temp for jekyll to process)

The template folder can contain whatever else is needed for processing the template of the scripts

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 association with the FHIR product director
  • [ver] is under manual control of the author. Use semver
  • [license] - license of author's choice. Use CC0-1.0 for HL7 published templates
  • [description] - whatever
  • [url] - your org/personal website. use http://hl7.org/fhir for HL7 authored templates

config.json

    • note: when the config.json section is replaced by the new Implementation Guide resource, this section will change**

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 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

  • still to be documented


Active Scripts

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:

  • 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:

  • 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 IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.

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