adapters.md

Adapters

UIengine supports adapters for rendering to support multiple templating engines and to offer a template agnostic way for rendering.

Adapters are registered for a particular file extension. UIengine will require an adapter when it needs to process a file with the given extension.

You configure the adapters for your project in the project configuration file, using the file extension as the adapter key.

Adapter Modules

A templating adapter module has to export an async render function:

• render(opts, filePath, data) gets the adapter options, the path to the file that should get rendered and the data to render it with. This function is called asynchronously and has to return a Promise! The incoming data depends on the file that gets rendered: For variants this is the context that is provided via the variant metadata.
• render should either return the rendered HTML, or a structured object containing the rendered HTML and an optional array of parts:
  • String -> <div>rendered html</div>
  • Object -> { rendered: "<div>rendered html</div>", parts: [{ title: 'HTML', content: "<div>rendered html</div>", lang: 'html' }, { title: 'CSS', content: "div { background: yellow; }", lang: 'css' }] }
    • The rendered HTML is required and is used to display the preview
    • The parts are optional and get displayed in the code view:
      • title: The title of the code block
      • content: The content of the code block
      • lang: The language of the code block, used for syntax highlighting

In addition to that there is an optional hooks for registerComponentFile. You can use this hook to i.e. register partials when working with Handlebars:

• registerComponentFile() gets called before the project gets generated. When generating incremental changes during development you can use this to update the registered cpomponent files as this hook gets called with changed files too.

In case you provided this hook, make sure to return a Promise!

See the list of available adapters – either to find an existing one or for a starting point to create a custom one:

• NPM
• GitHub: Core
• GitHub: Third-Party

Scaffolding

Adapters can also provide async functions to be used when scaffolding components and variants:

• filesForComponent(componentName)
• filesForVariant(componentName, variantName)

Both functions should resolve with an array containing information about the files that need to be created. For each file the array should contain an object providing a basename and data.

Here is an example from the Pug adapter:

const filesForComponent = (componentName) =>
  [
    {
      basename: `${componentName}.pug`,
      data: `mixin ${componentName}()\n  .${componentName}\n    //- TODO: implement\n`
    }
  ]

const filesForVariant = (componentName, variantName) =>
  [
    {
      basename: `${variantName}.pug`,
      data: `+${componentName}()\n`
    }
  ]