Wizzi plugins

Wizzi is a generation framework implemented by plugins.

Kernel modules themself have a pluggable architecture. The wizzi-mtree package is a plugin that implements an api for building tree structures from ITTF documents . The wizzi-repo package is a plugin that implements an api for locating and retrieving ITTF documents.

A Wizzi plugin exposes to the Wizzi factory the methods for retrieving its:

Wizzi schema definitions
Wizzi models and their factories
Wizzi model transformers
Artifact generators

A plugin package must export the createFactoryPlugin method in its index.js file. The FactoryPlugin class instance returned to the caller must implement the wizzi-plugin.factoryPlugin API (see below).

ITTF pseudo-code implementation of the createFactoryPlugin method


                       1 set module.exports
   2   {
   3     ...
   4     @ createFactoryPlugin
   5       function
   6         { wizziPackage
   7         { options
   8           [ items
   9             string pluginNameOrFile
  10           string pluginsBaseFolder
  11             default process.cwd()
  12         callback
  13         ...
  14         return
  15           _ callback
  16             @ null
  17             { factoryPlugin
  18               api-ref wizzi-plugin.factoryPlugin

A Wizzi plugin should have a standard folder structure so that modules can be located given the short public name of the required item.

Wizzi plugin standard folder structure


                       1 ...
   2   {package-name}
   3     package.json
   4     ...
   5     lib
   6       artifacts
   7         {schema-name}
   8           {artifact-name}
   9             gen
  10               main.js
  11           ...
  12           {transformer-name}
  13             trans
  14               main.js
  15           ...
  16         ...
  17       utils
  18         ...
  19       wizzi
  20         models
  21           {schema-name}-model.g.js
  22           {schema-name}-factory.g.js
  23           {schema-name}-schema.g.json
  24           ...
  25     index.js

Plugin management

Wizzi uses a class that implements the wizzi.PluginsManager Api to resolve and load plugins.

Wizzi plugins can be nodejs packages installed locally or globally or can be folders in packages that make a private use of them.

Plugins used by the wizzi.WizziFactory class must be requested at initialization time and cannot be changed. To use a different plugin set a new instance of the Wizzi factory class must be created.

ITTF pseudo-code of the wizzi.WizziFactory.initialize method


                       1 ...
   2   m initialize
   3     { options
   4       { repo
   5         ...
   6       { plugins
   7         [ items
   8           string pluginNameOrFile
   9         string pluginsBaseFolder
  10           default process.cwd()
  11       { test
  12         ...

The items property of the options.plugins object is an array of:

Package names, when plugins are contained in npm installed nodejs packages
Relative paths to plugins index module, when plugins are contained in private folders.

In the case of relative paths the property


                            pluginsBaseFolder

of the


                            options.plugins

object must contains the base folder of the plugin.

View the code

Have a look at how the wizzi.PluginsManager is implemented in the `wizzi` package

The wizzi-plugin.FactoryPlugin API

This api must be implemented by any Wizzi plugin.

The methods of the api will be called by the wizzi.PluginsManager instance class on requests received by the wizzi.WizziFactory instance.


                       1 ...
   2   #
   3     # Retrieve a Wizzi Model factory by its schema name
   4     # Searching in this wizzi package. No search up in "node_modules" folders.
   5   m getModelFactory
   6     string schemaName
   7     ...
   8   -
   9   #
  10     # Retrieve a model transformer by its name
  11     # Searching in this wizzi package. No search up in "node_modules" folders.
  12   m getModelTransformer
  13     string transformerName
  14     ...
  15   -
  16   #
  17     # Retrieve an artifact generator by its name
  18     # Searching in this wizzi package. No search up in "node_modules" folders.
  19   m getArtifactGenerator
  20     string generationName
  21   -
  22   #
  23     # Retrieve a wizzi schema definition in JSON format
  24     # Searching in this wizzi package. No search up in "node_modules" folders.
  25   m getSchemaDefinition
  26     string schemaName

Object returned by the getModelFactory method

This api is requested to the wizzi.PluginsManager from the wizzi.WizziFactory when a client needs to load a Wizzi model . The wizzi.WizziFactory, and not the client, will call the createLoadModel and loadModel functions.


                       1 {
   2   func createLoadModel
   3     # HOF : returns the loadModel function for the given factory
   4     { wizziObject
   5       func loadMTree
   6         api-ref wizzi-mtree.loader.loadMTree
   7         # This function is prepared by the wizzi.WizziFactory instance class
   8         # and has repository access functions and load options in its closure.
   9       { file
  10         api-ref wizzi.util.file
  11         # TODO this object should be a virtual file system service provided by
  12         # store implementations.
  13       { errors
  14         api-ref wizzi.errors
  15     ...
  16     return
  17       func loadModel
  18         # This function require a complex 'loadContext'
  19         # parameter.
  20         # It will be called by the wizzi.WizziFactory instance and
  21         # not directly from client code.
  22         string ittfDocumentUri
  23           # The path to the primary ittf document from which
  24           # the mTree will be loaded
  25         { loadContext
  26           { __productionManager
  27             api-ref wizzi.production.productionManager
  28             { productionContext
  29               api-ref wizzi.production.productionContext
  30               { aclstat
  31                 api-ref wizzi.production.aclstat
  32           { __ittfDocumentStore
  33             api-ref wizzi-repo.ittfDocumentStore
  34           { mTreeBuildUpContext
  35             optional
  36             | api-ref wizzi-plugin.wizziModel
  37             | POJO
  38         callback

Object returned by the getModelTransformer method


                       1 {
   2   func trans
   3     { model
   4       | api-ref wizzi-plugin.wizziModel
   5       | POJO
   6     { ctx
   7       api-ref wizzi.artifact.genContext
   8     callback

Object returned by the getArtifactGenerator method


                       1 {
   2   func gen
   3     { model
   4       | api-ref wizzi-plugin.wizziModel
   5       | POJO
   6     { ctx
   7       api-ref wizzi.artifact.genContext
   8     callback

Object returned by the getSchemaDefinition method

The object returned is a JSON representation of the requested schema. See the `wfjob` JSON schema definition .

View the code

Have a look at how the wizzi-plugin.FactoryPlugin API is implemented in the `wizzi-js` plugin . See the ITTF source also.

Core plugins

The Wizzi Factory is a content agnostic data processor and is not aimed at any particular domain. The plugins are domain specific and content aware. The plugins do the real work.

Anyhow the Wizzi Factory has one core plugin, the ` wizzi-core ` plugin, that is integrated in its API.

Default plugins

Default plugins are starter plugins to help the creation of the firsts domain specific generations.

Currently available default plugins

The `wizzi-js` and `wizzi-web` plugin at the moment are integrated in the Wizzi API.

Npm plugins

Npm plugins are public Wizzi plugins published in the npm registry.

They should be prefixed with wizzi-plugin- .

Create your first Wizzi plugin using the wizzi-starter-wizzi-plugin starter.

Local plugins

Local plugins can be located anywhere on the user drive and the plugin folder path is declared to the Wizzi factory instead of the plugin name.

The package.json file is not required. The plugin interface must be exposed in the index.js file located in the plugin folder.

Sample Wizzi factory instantiation with local plugins


                       1 ...
   2   _ wizzi.fsnoaclFactory
   3     { plugins
   4       [ items
   5         @ './packages/wizzi-core/dist/index.js'
   6         @ './packages/wizzi-js/dist/index.js'
   7         @ './packages/wizzi-web/dist/index.js'
   8       @ pluginsBaseFolder
   9         _ path.resolve
  10           @ __dirname
  11           @ '..'
  12           @ '..'
  13           @ '..'
  14     @ globalContext: globalContext || {}
  15     =>
  16       param err
  17       param wizziFactory
  18       if err
  19         throw ...
  20       _ wizziFactory.loadModelAndGenerateArtifact
  21         ...