The template system
The template system enable building components with richer client-side libraries other than the currently supported engines (handlebars and jade). One of the goal of this API is to make react a first class citizen of OC without having to lock the platform around it but allowing other technologies to be easily swapped in the future if wanted/needed.
Ideally component creators should only care of handling data in order to provide a viewModel within the dataProvider and build the viewLayer using a specific library/fw (i.e. react). The template should hide all the complexity away in order to compile/optimize the client bundle, perform server-side-rendering, and all the related wiring. In order to do so, templates have full access over the whole compilation/packaging phase and provide the information needed for clients to consume and handle such components.
Within the component's package.json a template type need to be specified together with its related compiler declared within devDependencies.
By convention the compiler need to follow the naming structure:
<template-type>-compiler.
For example a component of type: oc-template-handlebars will need a compiler named oc-template-handlebars-compiler in order to be correctly packaged and published:
...
"oc": {
"files": {
"template": {
"src": "template.hbs",
"type": "oc-template-handlebars"
}
}
},
"devDependencies": {
"oc-template-handlebars-compiler": "6.0.8"
},
...The CLI allow to bootstrap a new component with the init command. By default if no templateType is passed to the command a component of type oc-template-handlebars is created. Optionally you can pass any valid template as long as it follow the conventions mentioned above.
Usage:
$ oc init myComponent oc-template-jade
Check the CLI documentation for more details.
The registry need to be configured with the templates you want to allow:
const configuration = {
...
templates: [require('oc-template-extra'), require('oc-template-plus')]
...
}Check the registry configuration guide for more details.
Client-side rendering is done via the oc-client.js library. The library can now be dynamically updated to support client-side rendering of different templates:
via configuration API:
<script> var oc = {
conf: {
templates: [
{
"type": "oc-template-jade","externals": [
{"global": "jade","url": "https://unpkg.com/[email protected]/runtime.js"}
]
}
]
}
};
<script src="//registry.components.com/oc-client/client.js"></script>via registerTemplates() API:
cons templates = oc.registerTemplates([{
"type": "custom-react-template",
"externals": [{
"global": "React",
"url": "https://cdnjs.cloudflare.com/ajax/libs/react/15.6.1/react.min.js"
}]
}]);Check the browser client documentation for more details.
As a note, supported templates on the registry are now exposed via context.templates on the dataProvider, this allow for example, for components to be able to dynamically configure the browser client. See the oc-client code as an example.
At the moment oc-template-handlebars, oc-template-jade and oc-template-react support server-side rendering (SSR) as you would expect for the legacy handlebars and jade components.
At the moment OC come with oc-template-jade and oc-template-handlebars as default. But you can fork any of those template, or the oc-template-react, or simply build your own from scratch in case you need a custom template. Please check the following templates as a reference:
