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 1: Line 1:
A FHIR IG template are used by the [[FHIR IG Publishing tool]] when publishing [[FHIR Implementation Guides]]. The templates control:
+
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 look and feel of the published IG
* the way the resources are laid into pages  
+
* the way the resources are expressed as pages  
 
* 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 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 =
 
= 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, which 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 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:
 
List of known IGs:
Line 15: Line 15:
 
* "hl7" (http://gitub.com/hl7/fhir-ig-template - the standard template for HL7 published implementation guides  
 
* "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  
 
* "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" (todo): the standard template for IHE-published implementation guides
  
note to template authors: you can add you template to this list, as a url + documentation, but only the FHIR product director can assign standard codes.  
+
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 =
 
= Authoring IG templates =
  
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 3 kinds of artifacts:
  
* configuration files that describes how resources are rendered into HTML
+
* configuration files that describe how resources are rendered into HTML
 
* 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
 
* jekyll templates / include files / html files
  
In addition to these artifacts which are for the IG publisher, the template must contain some documentation that describes how an author adds pages and narrative content to the Implementation guide.
+
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 ==
 
== Template Resolution ==
  
When accessing a template by it's URL:
+
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 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
 
* if the URL is a file location, then the IG publisher will assume that template is local, and copy all the files
Line 49: Line 49:
  
 
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:
 
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 - the is provided so that the template can generate template-config.xml/json (see below)
+
* 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
 
* 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 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)
+
* 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  
 
* 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.  
 
* The IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.  

Revision as of 10:23, 7 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 "content" in the template, which will be copied into the \temp directory - e.g. provided to Jekyll as published content directly

Configuration file

...to document... what goes in here:

  • default templates and resources locations

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

Jekyll template files

Any files in "content" will be passed through untouched to the Jekyll build directory