The template system

Warning

The template system still in development. While base templates (oc-template-jade and oc-template-handlebars) fully support legacy template types (handlebars and jade), and can be safely used in production. The use of custom templates in production is discourage at this moment.

Intro

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.

Using templates

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 for packaging and publishing:

...
"oc": {
  "files": {
    "template": {
      "src": "template.hbs",
      "type": "oc-template-handlebars"
    }
  }
},
"devDependencies": {
  "oc-template-handlebars-compiler": "6.0.8"
},
...

With the CLI

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.

On the Registry

The registry need to be configured with the templates you want to allow:

const configuration = {
...
templates: ['oc-template-extra', 'oc-template-plus']
...
}

Check the registry configuration guide for more details.

Client-side rendering

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.

templates exposed in context

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.

Server-side rendering (WIP)

At the moment oc-template-handlebars and oc-template-jade support server-side rendering (SSR) as you would expect for the legacy handlebars and jade components. We are currently work to extend the template system to allow for to support SSR for any type of template.

Building templates

Please check oc-template-jade and oc-template-handlebars as a reference.