@zenginehq/frontend-multi-config

zn-frontend-multi-config

Helper module for implementing settings forms. Contains a form-builder, support for multiple settings sections separated by tabs and also for multiple configurations.

Installation

# Run this from your frontend plugin's src diretory.
npm i @zenginehq/frontend-multi-config --save

It's important that this gets inside under the src directory, alongside your plugin's other code if not Maya won't build it properly.

Updating

In order to update this module to a newer version run this in your plugin's src directory:

npm i @zenginehq/frontend-multi-config@latest --save

Usage

Add the directive to you settings page template;

<script type="text/ng-template" id="wgn-settings">
	<wgn-multi-config settings="configSettings"></wgn-multi-config>
</script>

Then, build out and add configSettings to your controller's scope:

plugin.controller('wgnSettingsCtrl', ['$scope', function ($scope) {
  // Define plugin settings (see "Settings" section below)
  $scope.configSettings = {
    title: 'My Awesome Plugin Settings',
    icon: 'icon-emo-sunglasses',
    help: 'This is some instructional text explaining what these settings do. I am concise, yet informative.',
    multi: true,
    toggle: true,
    pages: [
      {
      	id: 'target',
      	name: 'Target Form',
      	fields: [],
      },
      {
      	id: 'logging',
      	name: 'Logging Form',
      	fields: []
      }
    ]    
  };
	
  // For advanced usage you can also listen for certain multi config events (see "Events" section).
  $scope.$on('wgnMultiConfigEdit', function (ev, config) {
    console.log('this is the config being edited', config);
  });
}]);

Boom!

We're done, that's it! Give it some settings and the directive will take care of the rest!

Settings

The following options are supported:

• title: A heading that will be displayed at the top of the page
• icon: Optional. An icon to display next to heading
• help: Optional. Help text that will be displayed below the heading
• multi: Optional. One of true to support multiple configurations or false to have a single configuration. Defaults to false
• toggle: Optional. One of true to allow enabling and disabling a configuration (ie: to prevent webhooks running) or false for configurations to be always on. Defaults to false
• pages: An array of settings pages (see next section)

Settings Pages

A settings page is what will actually hold the fields for your settings.

You may define as many as you want but must have at least one!

In the event that there are multiple settings pages, they will be navigatable using tabs.

{
	id: 'firstpage',
	name: 'First Page',
	fields: []
}

The following properties are supported:

• id: A slug
• name: The title to be displayed on the tab if there are more than one page
• fields: An array of settings fields for each page (see next section)

Settings Fields

A field is a simple object describing what the field should be:

[
  {
    id: 'targetFormId',
    name: 'Target Form',
    help: 'The form which contains the data to check.',
    required: true,
    type: 'form'
  },
  {
    id: 'targetFieldId',
    name: 'Target Field',
    help: 'The field which contains the specific data to check.',
    required: true,
    type: 'field',
    belongsTo: 'targetFormId',
    restrict: 'text-input'
  }
]

There are many different field types and some may have specific settings but all fields share the following base settings:

• id: A unique slug identifier. This will be used as the key in firebase to store the value
• name: The field name. This will be used as the field label
• help: Optional. Help text to display below the field
• required: One of true to make the field required or false to make it optional. Defaults to false.
• type: The field type (see next section)

Field Types

The following field types are available:

• form
• field
• text
• number
• textarea
• select
• markup

form

A form field is a dropdown input that allows you to pick one of the forms in the given workspace.

field

A field field is a special dropdown input that allows you to pick a field from a certain form, optionally limiting to a certain field type. It has the following extra settings:

• belongsTo: The field id for the form input this should display fields from
• restrict: Whether to restrict to a certain Zengine field type. Possible options are: text-input, date-picker, linked, etc.

text

A simple text input. It has the following extra setting:

• placeholder: Optional. Some content to display when the input is blank.

number

A simple numeric input. It has the following extra setting:

• placeholder: Optional. Some content to display when the input is blank.

textarea

A muli-line text input.

select

A dropdown input. It has the following extra setting:

• options: An array of Objects containing an option definition:

[
  {
    value: 'off',
    label: 'Off'
  },
  {
    value: 'on',
    label: 'On'
  }
]

markup

A special field that lets you display any arbitrary markup. Note: This field doesn't share any base settings and instead has just one:

• value: A string with any valid HTML

Configuration Examples

See here for additional configuration examples.

Multi Config Events

The following events are emitted at various stages of the multi config workflow and can be used to achieve deeper customization for more complex forms.

• wgnMultiConfigInit when all firebase data has been loaded and the plugin has initialized.
• wgnMultiConfigAdd when a new configuration is being created, receives no params. This is useful if you need to perform some first-time setup for new configurations.
• wgnMultiConfigSave when configuration is saved, receives the config as a param. This is useful if you need to perform tasks once a config is successfully saved, such as enable a webhook.
• wgnMultiConfigEdit when a configuration is selected for editing, receives the config as a param. This is useful if you need to load additional data such as fields for a selected form in the config.
• wgnMultiConfigDiscard when changes are being discarded for the config being edited, receives no params. This is useful if you need to perform additional cleanup or perform any extra action such as going to a default tab.
• wgnMultiConfigDelete when a configuration is deleted, receives the config as a param. This is useful to do some additional cleanup such as delete a webhook.
• wgnMultiConfigEnable when a configuration is enabled.
• wgnMultiConfigDisable when a configuration is disabled.

Backend Services

In order to leverage multiple configs in your backend services it's recommended to always pass the following query string parameter to both znPluginData requests and also webhook urls: '?config=' + encodeURI(config.$id)

Then in your backend service:

var configId = eventData.request.query.config;

if (!configId){
  eventData.response.status(403).send('Config id required');
}

// Vanilla (boo)
firebase().child(workspaceId).child('settings').child(configId).once('value', function(snapshot) {
  settings = snapshot.val();
  console.log('settings', settings);
});

// Using zn-backend-firebase (awesome)
var zbf = require('zn-backend-firebase');
zbf.load([workspaceId, 'settings', configId]).then(function (settings) {
  console.log('settings', settings);
});

Changelog

2.4.0 (2018-06-12)

Features

• add a visual loading indicator when a field input is disabled because its parent form is loading (4b5a6d4)
• disable field inputs when parent form data is being loaded (d7fdd74)
• improve theming of form level required fields warning (a61a62a)
• improve typography on card titles (79106d5)

Reverts

• refactor: rework how forms are fetched (a89f438)

<a name="2.3.0"></a>