Template Extension
The template extension provides the basic capability for creating template MooseDocs markdown files. This extension is used by the Software Quality Assurance Extension to help minimize the burden of creating SQA documentation. The available configuration options for the extension are given in Table 1.
Table 1: Configuration options for the template extension.
| Key | Default | Description |
|---|---|---|
| active | False | Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime. |
| args | {} | Key value pair template arguments to be applied. The key should exist within the template file as {{key}}, which is replaced by value when loaded. |
The "args" configuration option can be used to set default template arguments. For example, a template argument "company" exists the configuration for MOOSE for use in the following examples.
MooseDocs.extensions.template:
args:
company: FordUsing a Template
To use a template it must be loaded and then the required fields defined. Assuming that the example in Example 2 was named "example.md.template", it can be loaded and modified as shown in Example 1.
Example 1: Example of loading and modifying template markdown file.
Notice that the command includes a key/value input "model=Mustang". All key/value supplied that are not in settings for the command are passed in as template arguments. These arguments are used to update the default arguments supplied by the extension configuration. Thus, in this example it would be possible to override the default for "company" by also supplying it to the load command.
The complete list of settings for the "template item" command are provided in Table 2.
Table 2: Available settings for the 'template item' command.
| Key | Default | Description |
|---|---|---|
| style | None | The style settings that are passed to rendered HTML tag. |
| class | None | The class settings to be passed to rendered HTML tag. |
| id | None | The class settings to be passed to the rendered tag. |
| key | None | The name of the template item which the content is to replace. |
Creating a Template
A template is a MooseDocs file with special sections that are designed to be replaced by another file that loads the template. Begin by creating a file and associated content that is constant, such as the headings or introduction. Then within this content begin by adding required or optional fields that are intended to be customized in the file that loads the template. The complete list of settings for the "template field" command are provided in Table 3.
Example 2: Example template markdown file.
# {{model}} Information
## Introduction
The {{model}} is a car manufactured by {{company}}.
## Details
!template field key=details
Provide detailed information regarding the specific {{company}} model.
{{model}} Information
Introduction
The {{model}} is a car manufactured by {{company}}.
Details
Provide detailed information regarding the specific {{company}} model.
The document must include the "details" template item, this can be included by add adding the following to the markdown file (python/MooseDocs/extensions/template.md):
!template! item key=details
Include text (in MooseDocs format) regarding the "details" template item here.
!template-end!Within MOOSE documentation the '.md.template' file extension is used for template files. This will avoid the template itself from getting rendered and copied to output destination.
Table 3: Available settings for the 'template field' command.
| Key | Default | Description |
|---|---|---|
| style | None | The style settings that are passed to rendered HTML tag. |
| class | None | The class settings to be passed to rendered HTML tag. |
| id | None | The class settings to be passed to the rendered tag. |
| key | None | The name of the template item which the content is to replace. |
| required | True | The section is required. |