Wappler Extensibility - Writing Custom Modules and Formatters for Server Connect

Wappler opens up its extensibility powers!

Now you can define your own custom modules and formatters for Server Connect. You can write your own custom code but also provide a UI definition of your extensions so they integrate directly visually in Wappler!

Writing Extensions for Server Connect

Folder Structure

All extensions files are placed in your project folder under the following folders:

Writing Server Code

The server code for your module or formatters depend on your server model. So check:

Extensions UI

To define an UI for your module actions or formatters, you need to place a special Hjson file that describes your UI. Hjson is just a more readable json format that makes it easier to write.

The Module UI

You can place your Hjson file in extensions/server_connect/modules/mymodule.hjson
An example is:

{
  type: 'world_hello',
  module : 'world',
  action : 'hello',
  groupTitle : 'Custom Actions',
  groupIcon : 'fas fa-lg fa-database comp-data',
  title : 'Hello World',
  icon : 'fas fa-lg fa-table comp-data',
  dataScheme: [
    {name: 'name', type: 'text'},
    {name: 'age', type: 'number'}
  ],
  dataPickObject: true,
  globalVars: {
    '$_GET' : [
			{name: 'sort', type: 'text'},
			{name: 'dir', type: 'text'}
  		   ]
  },
  properties : [
    {
      group: 'Hello Properties',
      variables: [
        { name: 'actionName', optionName: 'name', title: 'Name', 
          type: 'text', required: true, defaultValue: ''},
        { name: 'actionData', optionName: 'data', title: 'Data',
          type: 'text', defaultValue: ''}
      ]
    }
  ]
}

As you can see the structure is pretty readable. You define a type name for your module, usually a combination of module name and action, give it some titles and icons, define the output scheme if needed and specify input variables.

Note: You can have multiple actions within the same module. So you can also have multiple UI definitions for those actions in the same Hjson file. Just put an array element around them - enclose them in brackets and make sure there is a comma between.

Module UI Options

Key Type Description
type text, required an unique name for your module
module text, required an unique module name
action text, required an unique action name within this module
groupTitle text, required an group title to show all modules with the same group name together
groupIcon text, required an font awesome icon for the group, use also color modifiers
title text, required an title that describes your action
icon text, required an font awesome icon for action, use also color modifiers
dataScheme array, optional an array of objects with name and type that define the output data for your action
dataPickObject boolean, optional is the main action name pickable as data
globalVars object, optional an object that defines input data to be auto defined when the action is inserted
properties array, optional an array of groups with properties defining the input of the action. You can have multiple groups

Module UI Variables

For each group of UI input options you can have multiple variables with the following structure:

{ name: 'actionName', optionName: 'name', title: 'Name', 
  type: 'text', required: true, defaultValue: ''},

where:

Key Type Description
name text, required an unique name for your input variable on the UI
optionName text, required the name that gets used as option
title text, required the prompt for the variable on the UI
type text, required the input variable display type, see display types
required boolean, optional is the input required
defaultValue text/boolean, optional the default value for this input
serverDataBindings boolean, optional display a data bindings picker next to the input for easy data pickup. This also makes your control a visual expression tag editor
help text, optional the help text describing this input

The Formatter UI

You can place your HJson file in extensions/server_connect/formatters/myformatter.hjson
An example is:

{
  type: 'method_boeh',
  groupTitle : 'Custom Formatters',
  groupIcon : 'fa fa-lg fa-key',
  addTitle: 'Add Boeh',
  title : 'Add Boeh',
  icon : 'fa fa-lg fa-hashtag',
  state : 'opened',
  help : 'Say boeh en more',
  properties : [
    {
      group: 'Boeh Properties',
      variables: [
        {
            name: '1', optionName: '1', title: 'Param 1', type: 'text',
            serverDataBindings: true, defaultValue: '',
            help: 'Some great param.'
        }
      ]
    }
  ]
}

As you can see the structure is similar to the module UI, except you don’t have module and action. You define a type name for your module, must start with “method_” , give it some titles and icons, and specify input variables.

Note: You can have multiple formatters within the same code file. So you can also have multiple UI definitions for those formatters in the same Hjson file. Just put an array element around them - enclose them in brackets and make sure there is a comma between.

Formatter UI Options

Key Type Description
type text, required an unique name for your formatter, must start with “method_”
groupTitle text, required an group title to show all formatter with the same group name together
groupIcon text, required an font awesome icon for the group, use also color modifiers
title text, required an title that describes your formatter
icon text, required an font awesome icon for the formatter, use also color modifiers
properties array, optional an array of groups with properties defining the input of the formatter. You can have multiple groups

Formatter UI Variables

For each group of UI input options you can have multiple variables with the following structure:

{ name: '1', optionName: '1', title: 'Param 1', 
  type: 'text', required: true, defaultValue: ''},

where:

Key Type Description
name text, required is the order number of the parameter starting with 1
optionName text, required same as name
title text, required the prompt for the variable on the UI
type text, required the input variable display type, see display types
required boolean, optional is the input required
defaultValue text/boolean, optional the default value for this input
serverDataBindings boolean, optional display a data bindings picker next to the input for easy data pickup. This also makes your control a visual expression tag editor
help text, optional the help text describing this input

Input Reference

For both Module UI and Formatters UI the same variables options are valid.

Display Types

Type Description
text display text input
textarea display textarea
boolean display checkbox
number display number only input
numberorstring display number or string input
file choose a file
folder choose a folder
static not an input control but just a static text - use .help field to specify contents
droplist an advanced dropdown select control, see advanced types below*
enum an advanced multiselect control, see advanced types below*

Advanced Display Types

You can use also advanced display controls like dropdowns and multiple selectors

example:

{ name: 'oauth_service', optionName: 'service', title: 'Service', 
  type: 'droplist', 
  values: [
    {title: 'Google', value: 'google' },
    {title: 'Facebook', value: 'facebook' },
    {title: 'Instagram', value: 'instagram' },
    {title: 'Default', value: ''}
  ], defaultValue: '',
	help: 'Choose your OAuth2 Provider.'
}

Conditional Fields

Sometimes you need to show and hide some fields depending on chosen values of others.
So with the droplist field for example you can easily specify for each choice which fields to show or hide:

{ name: 'oauth_service', optionName: 'service', title: 'Service', 
  type: 'droplist', 
  values: [
    {title: 'Google', value: 'google', show:['oauth_key', 'oauth_url'], hide:[] },
    {title: 'Facebook', value: 'facebook', show:[], hide:['oauth_key', 'oauth_url'] },
    {title: 'Instagram', value: 'instagram', show:[], hide:['oauth_key', 'oauth_url'] },
    {title: 'Default', value: '', show:[], hide:['oauth_key', 'oauth_url']}
  ], defaultValue: '',
	help: 'Choose your OAuth2 Provider.'
},
{ name: 'oauth_key', optionName: 'key', title: 'Api Key', 
  type: 'text', defaultValue: '', initDisplay: 'none'},
{ name: 'oauth_url', optionName: 'url', title: 'URL', 
  type: 'text', defaultValue: '', initDisplay: 'none'},

Here only when Google is chosen, we display the additional two field otherwise they are just hidden - also initially with initDisplay option.

Color modifiers

Key Description
comp-flows color for flows
comp-errors color for errors
comp-data color for data elements
comp-loops color for loop actions
comp-general general color
comp-settings color for settings
comp-exec color for executions
comp-dialogs color for dialogs
comp-files color for files and operations
comp-images color for images
comp-security color for security

Installing Required Node Modules

Your custom extensions for NodeJS might need some special Node Modules. Now you can specify those in the Hjson and they will be installed automatically. Just add the following in your Hjson definition. You can pass multiple modules and required versions.

		usedModules : {
			node: {
				"sharp": "^0.29.3"
			}
		}
Community Page
Last updated: