Flowblocks - Reusable flow diagram blocks

Building flow diagrams

Flowblocks - Reusable flow diagram blocks

• General info
• Building blocks
  • TypeDefinition
  • PortTemplates
  • Block
    • Properties
    • Validations
• API
  • Flowblocks
    • getDefinition(typeName)
  • Flowblocks.Block
    • block.getConfigurable(name)
    • block.getConfigurables()
    • block.getStatus()
    • block.setConfigurable(name, value)
    • block.setConfigurables(configurablesArray)

General info

Building blocks

TypeDefinition

Specifies block attributes and behaviour

In Flowblocks each block that is created in the diagram is a block of a given type. Types allow to specify all attributes and block behaviour, they are like a template from which all blocks of given type are created.

Name	Type	Description
name	string	Unique Name/Id of the type, when block is created this is passed as its type (block property block._type is set to this value)
template	string	Ports template to be used when block of given type is created. See PortTemplates for more details.
style	`string	object`
icon	string	Name of the flowblocks preset icons or a link to a resource that is an icon. See flowblocks-icons for a list of available icons.
configurables	array<objec>	Array of configurables definitions. These specify what custom attributes can be set on the block. See Configurables for a detailed description.
category	string	When there are plenty of available block types that can be used to build flowblocks diagrams category can be used to group types into similar categories. When used in graphical designer this usually is rendered as groups of available types
validationSrc	string	Source code of a custom validation functions. See Validations for a detailed description of how such a function should be constructed

PortTemplates

Specifies input and output port for a block

Name	Description
Start	Types that use this template have only one output port named out1. These are always used as an input/start blocks in diagrams
End	Types that use this template have only one input port named in1. These are always used as an output/end blocks in diagrams
PassThrough	Types that use this template have single input port named in1 and a single output port out1.
Split	Types that use this template have single input port named in1 and a two output ports named out1, out2.
Join	Types that use this template have two input port named in1, in2 and a single output port out1.
Mixer	Types that use this template have two input port named in1, in2 and a two output ports named out1, out2.

Block

Block represents a single element on a flow diagram

Each block is represented by inputs and outputs (connections with other blocks) as well as block parameters that can be configured by user.

Each block has its state (valid/invalid). Each time block is changed (either connection is added or configurable value is changed) validation is triggered and block state is updated accordingly.

Each block has a definition of parameters that can be configured on the block. The definition defines the name, type and mandatory of the configurable.

Properties

Name	Type	Description
configurablesDefinitions	array<object>	Definition of configurables available in the block
configurablesDefinitions.id	string	Name/Id of the configurable. When calling block.get/setConfigurable() this id/name is used
configurablesDefinitions.label	string	Label of the configurable. Used to display in designer/ui
configurablesDefinitions.placeholder	string	Placeholder of the configurable. Used to display in designer/ui
configurablesDefinitions.type	string	Type of the configurable. One of TEXT, NUMBER, LIST, BOOLEAN
configurablesDefinitions.options	array<{v,l}>	Used when type of configurable is LIST. Provides available options on the list that can be selected by the user
configurablesDefinitions.required	boolean	When true user must provide the configurable of the block will be marked as invalid
configurables	array<{i: configurable name/id, v: configurable value}>	Configuration parameters of the block. Each time configuration parameter is updated block revalidation is performed

Validations

When block is updated validations are triggered. There are two types of validations for each block.

Built in validations

These include

• checking that all ports (input/output) are connected
• checking that all configurables markes as required are provided

Custom validations

Each block can have its custom validations. Configuration of the custom validation is by providing custom validation function for block:

function (blockData) {
    var errors = [];   
                
    var item = blockData.configurable('units');
                
    if(item && (isNaN(Number(item))||Number(item)<0 ||!Number.isInteger(Number(item)))){
        errors.push({ code: 'P_UNITS', cId: 'Units', msg: 'Units must be a positive integer' })
    }                     
                
    return errors;
}

Each custom validation functions takes blockData as its input and is expected to return array of errors. When there are no errors (validation successfull) then error array must be empty, when there are any validation errors then these errors must be put into the resulting error array.

API

Flowblocks

getDefinition(typeName)

Returns type definition registered with given name

var typeDefinition = flowblocks.getDefinition('myType');

Kind	Parameter	Type	Description
Argument	name	string	Required Name of the configurable
Returns		`string	number

Flowblocks.Block

block.getConfigurable(name)

Returns configurable value with given name

var units = block.getConfigurable('units');

Kind	Parameter	Type	Description
Argument	name	string	Required Name of the configurable
Returns		`string	number

block.getConfigurables()

Returns block configurables array

var configurables = block.getConfigurables();
configurables.forEach(configurable=>{
    var idName = configurable.i;
    var value = configurable.v;
})

Kind	Parameter	Type	Description
Returns		array<{i, v}>	Array of block configurable items

block.getStatus()

Returns validation status of block

var status = block.getStatus();
var isValid = status.valid;
var errors = status.errors;
errors.forEach(error=>{
    var errorCode  = error.code; // 'FIELD_REQUIRED',
    var errorAttributeId = error.cId;
    var errorMessage = error.msg// 'Field ['+requiredItem.id+'] is required'
})

Kind	Parameter	Type	Description
Returns		object	Status of the block
Returns	.valid	boolean	True when block is valid
Returns	.errors	array<{code, cId, msg}>	Array of errors
Returns	.errors[i].code	string	Error code
Returns	.errors[i].cId	string	Id of the invalid element/property/configurable
Returns	.errors[i].msg	string	Error message

block.setConfigurable(name, value)

Sets/updates configurable with given name. Revalidation is performed.

block.setConfigurable('units',7);

Kind	Parameter	Type	Description
Argument	name	string	Required Name of the configurable
Argument	value	any	Required Value of the configurable

block.setConfigurables(configurablesArray)

Sets/updates configurables. Revalidation is performed.

var configurables = [
    {i: 'name1', v: '7'},{i: 'name2', v: 'something'},
]
block.setConfigurables(configurables);

Kind	Parameter	Type	Description
Argument	configurablesArray	array<{i, v}>	Required Configurables array

Events

Model lifecycle events

flowblocks:save-ok

Emmited when model is saved (either via creation or update). Updated values are returned

Parameters	Description
datatype	type of the entity
specificationId	id of the saved entity
specificationVersion	version of the saved entity
specificationData	data of the saved enitty