Skip to content
UI plugin example
Vue JavaScript
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode
out
src
.editorconfig
.eslintrc.js
.gitignore
README.md
babel.config.js
package-lock.json
package.json
server.js

README.md

brewblox-plugin

This is a small example of how to write a plugin for the BrewBlox UI.

The BrewBlox UI can load and use UMD packages from an URL at startup. This allows adding plugins without rebuilding the UI.

To install the plugins, the Vue plugin mechanism is used. A plugin must have an install() function, in which it can register Vue components and BrewBlox widgets.

In this plugin, the install() function can be found in ./src/index.js.

Editor

You're free to use whatever editor or IDE you prefer, but we preconfigured some settings for VSCode.

Recommended VSCode plugins:

  • Vetur
  • ESLint
  • Prettier
  • EditorConfig

Changing the plugin name

It's recommended you change the plugin name to something other than brewblox-plugin. You can do so in package.json. The name occurs multiple times, so it's best to use a search and replace.

Serving the plugin

You can publish your plugin package to NPM to easily load it with unpkg.

This is convenient for releases, but less so for development. Here the simplest solution is to host a web server on localhost. For this, the server.js file exists. Run it in the background, and you can load your plugin from http://localhost:8200/{PLUGIN_NAME}.umd.js

Note: hot reloading is not yet implemented. To see your changes, run npm run build, and then reload your BrewBlox UI page.

BrewBlox Architecture

BrewBlox mostly adheres to the Vue application structure, but defines a set of concepts within this framework.

Feature

Features define the Vue components required to create and display dashboard items. Features must be registered on startup, in the plugin install() function.

Dashboard Item

Dashboard items are instances of features. This is the configuration data, and is stored in VueX. The widget component has a DashboardItem as property. The wizard component is expected to create a DashboardItem

Widget, Wizard, Form

To implement specific functionality, features can offer various Vue components. These components are passed configuration as Vue props, and are expected to emit events when they want to change the configuration.

  • To be displayed on a dashboard, a feature must have a widget.
  • To allow the user to create new dashboard items, a feature must have a wizard.
  • For more extensive configuration, features can provide a Form. These are rendered in modal windows. The feature itself is responsible for bringing up a form.

Data Management

Local application state is kept using VueX. Settings that are not session-specific (dashboards, dashboard items, services) are persisted to the BrewBlox datastore.

The full datastore state is loaded on startup, and all changes are persisted here.

Your plugin has full access to the BrewBlox store, but can't use the Typescript wrappers from the brewblox-ui repository.

You can also register your own store module. See the store example for how to do this.

For reference, these are the relevant store modules in brewblox-ui:

All modules are namespaced. For example, the Typescript definition for creating dashboard items is:

@Action({ rawError, commit: 'commitDashboardItem' })
public async createDashboardItem(item: DashboardItem): Promise<DashboardItem> {
return await createDashboardItemInApi(item);
}

In Javascript, you can call this store action using:

this.$store.dispatch('dashboards/createDashboardItem', item);

Using BrewBlox components

Because the plugin is loaded in the BrewBlox UI, you have full access to all Vue components registered in the BrewBlox UI. This includes those registered by other plugins.

Registered components fall under two groups:

  • Those provided by Quasar
    • Quasar component names always start with q-, and are kebab-cased (eg. q-item)
  • Those defined in BrewBlox itself (Everything in the components directory).
    • For convenience, we use PascalCase for local components. This makes it easier to identify local and imported components.

Quasar also offers useful functions added to this in Vue components. The most noteworthy are this.$q.dialog() and this.$q.notify(). See the dialog and notify documentation pages for more details.

Commands

Project setup

npm install

Compiles and minifies for production

npm run build

Serves the generated files locally

node server.js

Lints and fixes files

npm run lint

Customize configuration

See Configuration Reference.

You can’t perform that action at this time.