Extended Integration

This example will demonstrate how to integrate @bluepjs more deep: example will control 2 divs and 2 buttons background and text colors and buttons click event:

To make example more “demonstratable” new Module will be created with special types defenitions (enums, structs, classes) and Actors will demonstrate OOP Inheritance.

HTML structure for demo is simple:

    <div class="demo-page" ref="demo">
      <div id="div-1">Div 1</div>
      <div id="div-2">Div 2</div>
      <button id="btn-1">Button 1</button>
      <button id="btn-2">Button 2</button>
    </div>

css:

.demo-page {
  margin: 15px;
  padding: 10px;
  background-color: #eee;
}
.demo-page div {
  min-width: 50px;
  min-height: 50px;
  border: 1px solid #ddd;
}

Module

Let’s see all file first, and describe it by parts after:

example/src/vm/page.module.js

const { AbstractModule } = require('@bluepjs/vm')

const DivActor = require('./div.actor')
const ButtonActor = require('./button.actor')

class PageModule extends AbstractModule {
  /**
    static method provides information about module for Vm and IDE
  */
  static metadata () {
    return {
      // module code to access module object with vm.M(code) or vm.module(code)
      code: 'page',
      name: 'Page',
      // let's define some module types
      enums: {
        // html colors
        'html/color': { // full type will be `bluep/enum/${enumCode}`
          code: 'html/color',
          name: 'Html color',
          values: {
            '#f00': 'Red',
            '#0f0': 'Green',
            '#00f': 'Blue',
            '#fff': 'White',
            '#000': 'Black',
            '#999': 'Grey'
          }
        }
      },
      structs: {
        // colors struct for background color and text color
        'element/colors': { // full type will be `bluep/struct/${structCode}`
          code: 'element/colors',
          name: 'Html elements colors',
          schema: {
            background: {
              code: 'background',
              name: 'Background color',
              type: 'bluep/enum/html/color'
            },
            text: {
              code: 'text',
              name: 'Text color',
              type: 'bluep/enum/html/color'
            }
          }
        }
      },
      // let's define IDE color for our structure
      types: {
        'bluep/struct/element/colors': {
          code: 'bluep/struct/element/colors',
          name: 'Html color',
          color: '#df883d'
        }
      },
      // ElementActor description:
      classes: {
        'html/element': { // full type will be `bluep/class/${classCode}`
          code: 'html/element',
          name: 'HTML Element',
          module: 'page',
          schema: {
            colors: {
              code: 'colors',
              name: 'Colors',
              access: 'public',
              readonly: true,
              type: 'bluep/struct/element/colors'
            }
          },
          methods: {
            colorize: {
              code: 'colorize',
              name: 'Colorize',
              access: 'public',
              type: 'method',
              class: 'html/element',
              module: 'page',
              context: {
                inputs: {
                  colors: {
                    code: 'colors',
                    name: 'Colors',
                    type: 'bluep/struct/element/colors'
                  }
                }
              }
            }
          }
        }
      }
    }
  }

  // init method will be called before Vm.start and allows module generate Actors for elements
  async init (htmlElements) {
    if (htmlElements && htmlElements.length) {
      for (let i = 0; i < htmlElements.length; i++) {
        const el = htmlElements[i]
        const tag = el.tagName
        const id = el.id
        if (tag === 'DIV') {
          const actor = new DivActor(id, el)
          this.vm().M('actor').addActor(actor)
        }
        if (tag === 'BUTTON') {
          const actor = new ButtonActor(id, el)
          this.vm().M('actor').addActor(actor)
        }
      }
    } else {
      /**
        Current example architecture is not really nice.
        Page module used only on frontend, but we take Vm.ideData() for IDE
        from "background Vm" instead of "frontend Vm" where page module
        will be really used.

        So we just know what actors will be used on frontend, and we create
        them here, to get them on IDE
      */
      if (typeof window === 'undefined') {
        const div1 = new DivActor('div-1', null)
        const div2 = new DivActor('div-2', null)
        const btn1 = new ButtonActor('btn-1', null)
        const btn2 = new ButtonActor('btn-2', null)
        this.vm().M('actor').addActor(div1)
        this.vm().M('actor').addActor(div2)
        this.vm().M('actor').addActor(btn1)
        this.vm().M('actor').addActor(btn2)
      }
    }
  }

  // executes on Vm.start
  async start () {
    // this module will be executed only in browser
    if (typeof window === 'undefined') {
      // use vm console for "outputs"
      this.vm().console().error('Page module can be started only in browser')
      return
    }
    this.vm().console().log('Page module starting')
  }
}

module.exports = PageModule

Module defines:

• enum html/color with pairs of cssColor - Color name. Full type code is bluep/enum/html/color

• struct element/colors with fileds background and text. Full type code is bluep/struct/element/colors

• special color for struct

• class html/element describes parent class of module actors. Because parent class is never directly used by Vm - it’s metadata can’t be directly accessible (from class metadata) and provided in module metadata.

Because of not really nice demo architecture (IDE using “backend Vm”, and demo module runs only on frontent) - module initialization is “tricky” and we initialize “empty” actors just to get module/actors information for IDE

const PageModule = require('./src/vm/page.module')
vm.addModule(PageModule)
vm.M('page').init()

But on frontend module initialized with real DOM elements:

import PageModule from '@/vm/page.module'
    this.vm.addModule(PageModule)
    await this.vm.M('page').init(this.$refs.demo.children)

Note

$refs is part of Vue 3 framework.

Actors

html/element

Base class for actors in this demo named “HTML Element” (with code “html/element”).

example/src/vm/element.actor.js

const { AbstractActor } = require('@bluepjs/vm')

/**
  ElementActor will be base for other actors - DivActor and ButtonActor
  and implement parent methods

  ElementActor by itself will not be used - it's "abstract" class,
  so class will be defined in module classes metadata and here metadata will be skiped
*/
class ElementActor extends AbstractActor {
  /*
    override actor constructor to provide html element and set inital states
  */
  constructor (actorId, htmlElement) {
    super(actorId)

    this._element = htmlElement || null

    this._state = {
      // according to 'html/element' class schema, struct and enums description
      colors: {
        background: '#fff',
        text: '#000'
      }
    }
  }

  /*
    override non-static metadata method to set nicer names
  */
  metadata () {
    const base = this.constructor.metadata()
    const id = this.id()
    // required. exists in parent metadata() method
    base.id = id
    // new update
    base.name += ` (${id})`
    return base
  }

  // override async AbstractActor::method(code, inputs)
  method (code, inputs) {
    // all methods will be defined as functions named 'code'
    // so all child classes will not override this method
    if (!this._element || typeof this[code] !== 'function') return
    return this[code](inputs)
  }

  // method described for ElementActor
  async colorize ({ colors }) {
    // don't forget to update state
    this._state.colors = colors
    this._element.style.color = colors.text
    this._element.style['background-color'] = colors.background
  }
}

module.exports = ElementActor

Take attention to _state defenition (line 19). State described at Module metadata as variable with code colors typeof bluep/struct/element/colors.

          schema: {
            colors: {
              code: 'colors',
              name: 'Colors',
              access: 'public',
              readonly: true,
              type: 'bluep/struct/element/colors'
            }
          },

Struct element/colors described having 2 fileds type of bluep/enum/html/color:

        'element/colors': { // full type will be `bluep/struct/${structCode}`
          code: 'element/colors',
          name: 'Html elements colors',
          schema: {
            background: {
              code: 'background',
              name: 'Background color',
              type: 'bluep/enum/html/color'
            },
            text: {
              code: 'text',
              name: 'Text color',
              type: 'bluep/enum/html/color'
            }
          }
        }
      },

And enum type html/color described with next values:

        'html/color': { // full type will be `bluep/enum/${enumCode}`
          code: 'html/color',
          name: 'Html color',
          values: {
            '#f00': 'Red',
            '#0f0': 'Green',
            '#00f': 'Blue',
            '#fff': 'White',
            '#000': 'Black',
            '#999': 'Grey'
          }
        }

As result state definition is:

    this._state = {
      // according to 'html/element' class schema, struct and enums description
      colors: {
        background: '#fff',
        text: '#000'
      }
    }

colorize method, described at Module metadata is simple - it updated state colors variable and css styles of html element accordingly.

  async colorize ({ colors }) {
    // don't forget to update state
    this._state.colors = colors
    this._element.style.color = colors.text
    this._element.style['background-color'] = colors.background
  }

html/div

Div Actor is very simple:

src/vm/div.actor.js

const ElementActor = require('./element.actor')

/**
  Div actor is simple ElementActor child class
*/
class DivActor extends ElementActor {
  /*
    Div actor how nothing specal, so we can describe it only by metadata
  */
  static metadata () {
    return {
      code: 'html/div',
      name: 'Div Element',
      // all schema and methods are extended fom parent class
      extends: {
        'module/page/html/element': {
          module: 'page',
          code: 'html/element'
        }
      }
    }
  }
}

module.exports = DivActor

Actor just extends html/element class. But actors of this class will be used by Vm, so there is static metadata() method, describing it.

html/button

Button Actor has additional event click

src/vm/button.actor.js

const ElementActor = require('./element.actor')

/**
  Div actor is simple ElementActor child class
*/
class ButtonActor extends ElementActor {
  /*
    Div actor how nothing specal, so we can describe it only by metadata
  */
  static metadata () {
    return {
      code: 'html/button',
      name: 'Button Element',
      // all schema and methods are extended fom parent class
      extends: {
        'module/page/html/element': {
          module: 'page',
          code: 'html/element'
        }
      },
      events: {
        click: {
          code: 'click',
          name: 'Click'
        }
      }
    }
  }

  constructor (id, htmlElement) {
    super(id, htmlElement)

    if (htmlElement) {
      htmlElement.addEventListener('click', () => {
        this.emit('click')
      })
    }
  }
}

module.exports = ButtonActor

Actor constructor is oveeriden to bind event listener on element.

Actors are event emitters, and Vm manages described events.

Bleuprints

Our Module is complete and comnnected to Vm. Now all Actors behavior will be defined with Blueprints.

Vm start

Let’s colorize our actors on Vm start:

Button 1 click

Click on 1st button will take background color of button and apply it as text color of divs, keeping divs background color same.

If we click on 1st button - divs text color will become green:

Works! Great! :) But let’s do some “code optimization” before we touch 2nd button.

Colorize functions

Let’s create blueprint function to colorize text of our divs. Function will have one input typeof bluep/enum/html/color

Function do same thing as “button 1 click” blueprint with difference that text color is provided as input variable.

Now let’s do button 2 click blueprint.

Button 2 click

colorize blueprint is called on click with manually defined red color, than function waits for 2000ms (2sec) and call again colorize node with blue color input.

Project sources

Example project with all sources can be found here: https://github.com/bluep-js/example