Create Custom Control

A super guide to let you create your own custom control for Vue-Form-Builder

Prepare your Custom Control stuff

Which are:

For the first guide, I'll show you how to add Switch UI for Vue-Form-Builder, based on Switchery

Core Concept

We will create & define 3 things:

Control View: where you create & initialize your custom control
Control Configuration View: where you configure specific data for your custom control
- This one is optional since there might a control without configuration
Control Definition: Follow this rule

Control Object

Control Object contains basic + specific Configuration in order to build up Vue Form Builder and your custom fields.

Base configuration data: https://github.com/sethsandaru/vue-form-builder/blob/master/src/configs/controls.js#L262-L289

Every time you create your custom field. Vue Form Builder will take the Basic Configuration Object and your configData object of your custom control and merge it into 1 object. So please make sure, you don't use the keys of the Basic Configuration Object.

Create a Custom Control

You need to extend from BaseControlSkeleton of Vue Form Builder:

import {BaseControlSkeleton} from 'v-form-builder'

export default {
    name: "SwitchControl",
    extends: BaseControlSkeleton,
}

Then, starting to build your control view:

<template>
    <input
        :id="control.uniqueId"
        :name="control.name || control.uniqueId"

        type="checkbox"

        @change="updateValue($event.target.checked)"
    />
</template>

<script>
    import {BaseControlSkeleton} from 'v-form-builder'
    import Switchery from '../../assets/switchery.min'
    import '../../assets/switch.css'

    export default {
        name: "SwitchControl",
        extends: BaseControlSkeleton,

        data: () => ({
            switcherInstance: null,
        }),

        watch: {
            /**
             * Watcher for Configuration - FormBuilder Mode
             * @param val
             */
            "control.switchColor": function(val) {
                this.switcherInstance.options.color = val

                if (this.switcherInstance.isChecked()) {
                    this.switcherInstance.switcher.style.backgroundColor = val
                    this.switcherInstance.switcher.style.borderColor = val
                }
            }
        },

        mounted() {
            // Initialize Checked
            if (this.control.isChecked) {
                this.$el.checked = true
                this.updateValue(true)
            }

            // CREATE UI CONTROL
            this.switcherInstance = new Switchery(this.$el, {
                color: this.control.switchColor
            })
        },

        beforeDestroy() {
            this.switcherInstance.destroy()
        }
    }
</script>

Available Variables / Methods

Take a look at this file: https://github.com/sethsandaru/vue-form-builder/blob/master/src/mixins/control-field-extend-mixin.js

Variables:

this.control: Main Control Field's configuration object.
this.value: v-model's value

Can be override-variables:

this.stopDefaultValueAssign (boolean): set this to true if you want to handle (get/set/...) your own default data in mounted hook. Otherwise, Vue Form Builder will run this: https://github.com/sethsandaru/vue-form-builder/blob/master/src/mixins/control-field-extend-mixin.js#L87-L95

Computed:

this.controlFieldClass: Class for the input/textarea/... field. You can use it to set to your own field.
this.controlName: Get the name of the field with this logic: name => uniqueId

Methods:

this.updateValue(val): Use this method to emit a new value after users inputted/changed your own field.
this.setValue(val): (Need to override) Vue-Form-Builder always watch the value of the v-model, if it's changed, we need to update the value on the UI. So you can use this setValue method to set it. You can take a look at this example where I handle the date picker's value: https://github.com/sethsandaru/vue-form-builder/blob/master/src/views/controls/DatePickerControl.vue#L85

Notes

Use the method to updateValue(val) to emit the value to the FormRenderer.
These attribute must be defined:
- id
- name

Create Custom Control Configuration View

Most likely, you will have specific configurations for your Custom Control. Well, I got you fam. You can create your configuration view and let Vue Form Builder show it up for you.

So for the Switchery, I need 2 more configurations: isChecked and switchColor

<template>
    <div>
        <!---
        You can use the `control` object - basically, it's main data of your custom control field
        Because I had 2 more specific config data (isChecked & switchColor)
        So I added 2 more fields below to config it.
        --->
        <div :class="styles.FORM.FORM_GROUP">
            <label>
                Initialize Checked?
                <input type="checkbox" v-model="control.isChecked">
            </label>
        </div>

        <div :class="styles.FORM.FORM_GROUP">
            <label>
                Switch Color (HEX Color)
            </label>
            <input type="text"
                   :class="styles.FORM.FORM_CONTROL"
                   v-model="control.switchColor"
            >
        </div>
    </div>
</template>

<script>
    import { BaseControlConfigSkeleton } from 'v-form-builder'

    export default {
        name: "SwitchConfigView",
        extends: BaseControlConfigSkeleton,
    }
</script>

For the Save action, Vue Form Builder will handle it for you. No worries.

Available Variables

this.control: Main Control Field's configuration object.

Register your Custom Control

While registering VueFormBuilderPlugin, make sure you included the Control Definition:

Vue.use(VueFormBuilderPlugin, {
    controls: {
        'switch': {
            name: "Switch Field",
            description: "Single Switch",

            /**
             * Control View Mapping
             */
            fieldComponent: require('./custom-controls/switch/SwitchControl'),

            /**
             * Control Configuration View Mapping
             */
            configComponent: require('./custom-controls/switch/SwitchConfigView'),

            /**
             * Control-Data Extend
             * Your specific data for your custom control
             */
            configData: {
                isChecked: false,
                switchColor: "#64bd63"
            },

            /**
             * Default data of the Switch in Renderer
             * @returns {boolean}
             */
            rendererDefaultData() {
                return false
            },
        },
    }
})

Definition Key Description

Key

Data Type

Description

name

String

Your Control Name

description

String

Short description about your control

configData

Key-Value

Object

Specific configuration data for your custom control

rendererDefaultData

Function

The factory method to create a default value for your

custom control.

Must be a function and return a value

fieldComponent

Object

Vue Component

Control View Component of your Custom Control

configComponent

Object

Vue Component

Control Configuration View Component of

your Custom Control

disableValue

Boolean

Default: false

Is your control had value or not? (like Label/Text-Block

it doesn't have value)

disableValidation

Boolean

Default: false

If this set to false, the Validation section won't appear when you configure the control.

Test your Custom Control

Control View

Control Configuration

After added some configuration:

Online Demo

http://vue-form-builder.sethphat.com/custom-control

Code References

Global references:

I tried my best to wrote the most readable code :D

>o<

PreviousValidation

Last updated 3 years ago