Template Data Object Specification¶
Intro¶
This page defines requirements for Template as a data object and then also outlines a possible solution to meet those.
This is a model-enchanced document. Changes to the documentation model docs/mdd-model have effect on the contents of this page.
Requirements¶
Here is a summary of stakeholder needs towards the Template data object that we identified so far:
ID/Version | Requirement | Rationale |
---|---|---|
R001/1 | The form in which a Template is stored or transfered shall be open, so that no proprietary tooling is required to create, read or modify a Template instance. |
So that other compatible templating tools could be made and no data gets locked. |
R002/1 | The Template provide means for unique identification of its constructs across baselines (unique object identifier and version). |
This improves user experience in an environment where templates are part of change controled assets. Ability to isolate a diffect in documentation to a specific template fragment / version |
R003/1 | The Template data structure shall enable fault isolation to one of the basic templating constructs - rendering block, condition, query (data transformation) or loop |
This will improve user experience related to template debugging and maintenance. With a monolythic template it frequently gets difficult to find a root cause of things going wrong. Having template broken down into basic isolated building blocks will enable more precise fault isolation as well as independent and maybe even asynchronous / real-time fragment validation and preview. |
R004/1 | The Template ontology shall provide means for re-use through instantiation of template fragments. |
In templating we frequently make use of visualization patterns and it should be possible for an end-user to define and re-use those. |
R005/1 | The Template ontology shall enable reverse mapping of generated objects to the template fragments. |
To debug content we need to know which template fragment resulted in what content. |
R006/1 | The Template shall provide means to specify how the generated elements should be uniquely identified and versioned. |
To enable formal change control of the derived documents. |
Conceptual ontology of a Template¶
The figure above provides an overview of the Template ontology (conceptual). The final technical implementation may differ.
Classes¶
RichText (Fragment)¶
This is a Fragment specialization with focus on text capture. The expected realization will allow for use of any jinja payload so this also may be used to deliver any HTML output.
Attributes of RichText¶
is_work_item: value of type Boolean
params: value of type Parameter
version_major: value of type Long
version_minor: value of type Long
Table (Fragment)¶
This fragment type specialization is table capture. Technically this should be another jinja block, however on the front-end side this may be realized by a more complex text editor.
Attributes of Table¶
params: value of type Parameter
version_major: value of type Long
version_minor: value of type Long
Figure (Fragment)¶
This fragment type is focused on delivering figures, be it model-derived, static asset or synthetic
Attributes of Figure¶
params: value of type Parameter
version_major: value of type Long
version_minor: value of type Long
FragmentInstance (Fragment)¶
This is an instance of a Fragment from library. It has some or all of its parameters pre-configured
Attributes of FragmentInstance¶
VersionedObject¶
No description availableAttributes of VersionedObject¶
version_major: value of type Long
version_minor: value of type Long
Loop (FragmentContainer)¶
No description availableAttributes of Loop¶
DataQuery (FragmentContainer)¶
No description availableAttributes of DataQuery¶
PythonModule¶
No description availableAttributes of PythonModule¶
Condition (FragmentContainer)¶
No description availableAttributes of Condition¶
Abstract FragmentContainer (Fragment)¶
No description availableAttributes of FragmentContainer¶
Template¶
No description availableAttributes of Template¶
contents: an ordered list of Fragment class
library_assets: one or many instances of Fragment class
required_modules: one or many instances of PythonModule class
data: one or many instances of DataSourceReference class
params: one or many instances of Parameter class
DataSourceReference¶
This class points to a data source that shall be available to all Fragments for queries from jinja.
Attributes of DataSourceReference¶
Heading (FragmentContainer)¶
No description availableAttributes of Heading¶
Parameter¶
Parameters allow for configuration of templates. For instance you may have a template that describes a component - in that case you may use parameter to define what component a template instance shall describe in particular (by passing its name or uuid).
Attributes of Parameter¶
Abstract Fragment (VersionedObject)¶
Fragment is the lowest building block of a Template. Any fragment can be independently compiled / validated given the context.
Attributes of Fragment¶
params: value of type Parameter
version_major: value of type Long
version_minor: value of type Long