Node-modules like bootprint-swagger
and bootprint-json-schema
are called template-modules.
They provide Handlebars-templates and Less-definitions for convert a specific JSON format
to readable HTML.
Writing a template module is not much different from writing a config-file for Bootprint. The main difference is, that a module can be published on npm and that it can itself be reused and adapted.
In order to make it easy for other people to understand and contribute to a template-module, this document proposes a number of conventions. Eventually, there will be a documentation generator for modules that are based on these conventions.
The following structure is a proposal for the structure of a template. It is not required that a template-module have this structure, but I think a unified structure helps other people (such as yourself in the future) find their way easier. So if you are writing a template module, you should structure it like this:
├── index.js
├── package.json
├── LICENSE
├── handlebars
│ ├── preprocessor.js
│ ├── helpers.js
│ ├── partials
│ │ ├── my-module-name
│ │ │ ├── my-partial.hbs
│ │ │ └── my-other-partial.hbs
│ │ └── inherited-module-name
│ │ ├── overridden-partial.hbs
│ │ └── other-overriden-partial.hbs
│ └── templates
│ └── index.html.hbs
└── less
├── include
│ └── included-less-file.less
└── main.less
All parts except index.js
and package.json
are optional. All paths must be configured.
index.js contains a bootprint-configuration for these folders.
In addition to the configuration, the contents of the package.json
-file is
included in the export:
var path = require('path')
// Export function to create new config (builder is passed in from outside)
module.exports = function (builder) {
return builder
.load(require('bootprint-inherited-module-name'))
.merge({
'handlebars': {
'partials': path.join(__dirname, 'handlebars/partials'),
'templates': require.resolve('./handlebars/templates'),
'preprocessor': require('./handlebars/preprocessor.js'),
'helpers': require.resolve('./handlebars/helpers.js')
},
'less': {
'main': [
require.resolve('./less/main.less')
],
'paths': [
path.join(__dirname, 'less/include')
]
}
})
}
// Add "package" metadata. This can be evaluated by documentation generators
module.exports.package = require('./package')
For examples, have a look at the existing template-modules (e.g. bootprint-swagger) and its dependencies.
The file watcher and the live-reload server can be started using the "-d" option of the command-line utility. Open a browser on http://localhost:8181 and your current bootprint-result will be displayed. Change any template-file, partial, less-file, js-file containing helpers and the browser will automatically reload the page once the bootprint-generaion is complete.
In order to avoid naming clashes with other modules, you should prefix all
entities of your module with the module name (without the mandatory bootprint-
-prefix. If you module is named bootprint-cats
, you should
- prefix all {less}-definitions with
cats--
- put all partials into a
cats
-subdirectory of thepartials
-directory, so they are registered ascats/partial-name
. - prefix all handlebars-helpers with
cats--
.
If you want your module to be reusable and you want to use Semantic Versioning when maintaining your module, you should define an explicit api.
Here is a convention on how to do that. Eventually, there will be support to generate an API-documentation automatically based on this convention.
-
Document your less-files with jsdoc-like tags.
-
Use the
@public
-tag to mark definitions that should be visible to other modules -
Use the
@readonly
-tag to mark definitions that should not be modified or overridden by another module. -
Use the
@override
-tag to mark definitions that override settings from other modules.
Example:
/** * Label of the `description`-section within a json-schema box. * @public */ @json-schema--msg-section-description: "Description";
-
-
Document your handlebars-partials by inserting a comment at the very beginning of the file.
-
Add a jsdoc-like
{{!--
-comment to the beginning of the partial. Describe expected parameters and outputs. -
Add a
@api public
to the comment partial that should be visible to other modules. -
Add a
@readonly
-tag to the comment, if the partials should not be modified or overridden by another module. Bootprint does not enforce this, but it is a good hint for other developers about what you are considering part of the API. -
Use the
@override
-tag to mark definitions that override partials or templates from other modules.
Example:
definitions.hbs
frombootprint-swagger
: -
See bootprint-json-schema for an example, although it does not follow of the above rules yet. For a module extending another bootprint-module, see bootprint-swagger.