Formatters
Templater was designed to be extensible. This means that it was
designed to include parts of the system in runtime.
Formatters are one of the extensible parts of the system. They are
designed to add additional formatting functionality and expose it
though metadata written in templates.
Metadata based plugins can be simple ones like bool(YES/NO/MAYBE) where
boolean value will be replaced with YES, NO
or MAYBE pattern, or more complicated ones like
join(SEPARATOR) where array elements would be joined with
SEPARATOR.
They are useful for converting domain model to presentation without
doing all the conversions in the domain model.
More complex use case would be to convert input into an image.
For example if the value in the tag represents an id of an image,
then plugin could load up the image from the appropriate location and provide it
instead of the original image id value
Where there is some pattern in conversion, like format(PATTERN)
or bool(YES/NO), it's useful to create required formatter
and use it.
The downside of this approach is that your formatters are leaking into
your templates, which can sometime look confusing. But this is also a
strong point, since you don't need Word/Excel/PowerPoint add-ons.
Since plugins can be registered during initialization (and depend on external state) there are various use cases for formatter plugins:
- picking a letter from the value - letter(X) - so that each letter can be placed in separate cell
- resizing an image - height(X,Y) - to adjust image size in the document
- converting ID into an image - load-image - to avoid providing such properties in the model
- verbalizing numbers into text - verbalize
- quoting CSV values - quote - since quoting can be configuration dependent
- formatting dates - date - show date in localized format
- various imports - html - convert HTML into docx format for import
