Difference between revisions of "FHIR IG publisher templates"
| Line 25: | Line 25: | ||
A template contains 3 kinds of artifacts: | A template contains 3 kinds of artifacts: | ||
| − | * | + | * configuration files that describes 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 | ||
| Line 31: | Line 31: | ||
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 some documentation that describes how an author adds pages and narrative content to the Implementation guide. | ||
| − | == Template | + | == Template Resolution == |
| − | When accessing a template by it's URL | + | When accessing a template by it's 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 == | == Configuration file == | ||
| + | ...to document... | ||
what goes in here: | what goes in here: | ||
* default templates and resources locations | * default templates and resources locations | ||
| Line 42: | Line 48: | ||
== Active Scripts == | == 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 - the is provided so that the template can generate template-config.xml/json (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 | + | 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 == | == Jekyll template files == | ||
| − | Any files in | + | Any files in "content" will be passed through untouched to the Jekyll build directory |
Revision as of 07:12, 7 May 2018
A FHIR IG template 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 laid into 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.
Contents
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.
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
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.
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 describes 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 some documentation that describes how an author adds pages and narrative content to the Implementation guide.
Template Resolution
When accessing a template by it's 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 - the is provided so that the template can generate template-config.xml/json (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
