Custom Element

Initialization

Create a js file and add that file right after <script src="visual-editor/visual-editor-primary-elements.js"></script> and do not change the orders of other scripts at all.

Next follow the structure given below.

cmbAllElements['cmb_your_custom_element']= {
    // Options goes here
    // methods goes here
};

Custom element key must have a prefix cmb_ and will be snake case (Mandatory).

Options

Available Options

allowedParent	title	addButtonText	elementTabName
html	htmlVariation	subWrapper	hideActionSymbol
customAction	allowedActionElement	avoidableTabs	avoidableTabSettings
avoidElementListing	tabSettingOptionOnly	avoidableTabSettingOptions	settings
elementType	icon	dynamicOptions

allowedParent:

type: (array) []

required: True

value: element name of targeted parent from cmbAllElements object keys or content-wrapper

Note: can be multiple. This is used to define under which element we can add this element.

title:

type: string

required: True

value: any custom name

Note: This name is used in action element bar (move delete setting option bar) and setting bar

elementType:

type: string

required: True

value: dynamic-layout or static-layout

Note: dynamic layout is for if data comes from database and static layout is if data is built without server script support

icon:

type: string

required: True

value: fontawesome icon can be used

Note: it is used in action element bar

addButtonText:

type: string

required: True

value: any custom name

Note: This name is used in add element tab when allowed parent add button is clicked.

elementTabName:

type: string

required: True

value: we have some built in tab name that can be used

    container
    component
    header
    media
    pre-build-template
    dynamic-layout

if custom tab name is required add the variable key once

cmbElementTabs['key'] = 'value'

and then use the key several times in tabname

Note: This tabname is shown in element library tab

html:

type: string

required: True if htmlVariation is not added

value: html text of your element and this html grand wrapper must have the exact

htmlVariation:

type: (object) {}

required: True if html is not added

value:

htmlVariation : {
    'blank' : {
        subtitle: 'something',
        icon: '<i class="cm cm-section-blank"></i>',
        html: `<tag></tag>`
    },
    'filled' : {
        subtitle: 'something else',
        icon: '<i class="cm cm-section-blank"></i>',
        html: `<tag></tag>`
    },
}

htmlVariation and each variation as object where subtitle icon and html is required. html will follow the html rules.

hideActionSymbol:

type: (object) {}

required: True if html is not added

value:

htmlVariation : {
    'blank' : {
        subtitle: 'something',
        icon: '<i class="cm cm-section-blank"></i>',
        html: `<tag></tag>`
    },
    'filled' : {
        subtitle: 'something else',
        icon: '<i class="cm cm-section-blank"></i>',
        html: `<tag></tag>`
    },
}

htmlVariation and each variation as object where subtitle icon and html is required. html will follow the html rules.

subWrapper:

type: boolean

required: optional

value: if true, action element bar (move delete setting option bar) will have no icon and name

customAction:

type: (object) {}

required: optional

value:

customAction:{
    'add-row' : {title : 'add row',text : '<i class="fa fa-bars"></i>'},
    'add-col' : {title : 'add column',text : '<i class="fa fa-columns"></i>'},
},

if a custom button is required in action element bar (move delete setting option bar), it can be added this way and custom jquery can be called with $('.cmb-custom-action[data-action="add-row"]). // add-row will be replaced with your key here.

avoidElementListing:

type: boolean

required: optional

value: if true, item will not be appeared in element modal as adding option

allowedActionElement:

type: (array) []

required: optional

value:

allowedActionElement: [
    'cmb-option-prev', 
    'cmb-option-next', 
    'cmb-option-move', 
    'cmb-option-add', 
    'cmb-option-delete', 
    'cmb-option-copy', 
    'cmb-option-settings'
],

use when you want to show specific button. default button names are provided. just remove any button you do not want to you in the action element bar (move delete setting option bar)

avoidableTabs:

type: string array or object

required: optional

value:

[
    {
        general: ['tab1','tab2']
    },
    'display'
]

Setting options are multi dimentional and if any tabs are needed to be removed it needs to be in array or string finally. for instance if 1 tab needs to be removed, we can use string. if multi tab needs to be removed we can use array. if there is a condition where a tab1 is under general and we need to remove tab1 then we need to use an object and key will be general and value will be tab1. if there are tab1 and tab2 under general, we can use array. our common tabs are general position design background. listed item here will be avoided

avoidableTabSettings:

type: loop of object and final item is array

required: optional

value:

{
    position : ['align-self','float'],
    design : ['padding-left','padding-right']
},                     

always loop of tab as key name and finally array value for settings. listed item here will be avoided

available common options right now

{
    general : [
       'xs-hide','sm-hide','md-hide','lg-hide','xl-hide','class','id'
    ],
    position : [
        'float','display','flex','justify-content','align-content','align-item','align-self',
    ],
    design : [
        'padding-top','padding-right','padding-bottom','padding-left','margin-top','margin-right','margin-bottom','margin-left','text-align',
    ],
    background : [
        'background-color','background-image','background-position','background-attachment','background-repeat','background-size',
    ]

}

avoidableTabSettingOptions:

type: loop of object and final item is array

required: optional

value:

{
    position : {
        display : ['d-*-none','d-*-flex']
    }
}                   

always loop of tab or settings as key name and finally array value for options. in the example under position tab, display settings will avoid d-*-none and d-*flex

tabSettingOptionOnly:

type: loop of object and final item is array

required: optional

value:

{
    position : {
        display : ['d-*-none','d-*-flex']
    }
}                   

always loop of tab or settings as key name and finally array value for options. in the example under position tab, display settings will only have d-*-none and d-*flex

dynamicOptions:

type: (object) {}

required: required if elementType == "dynamic-layout"

value:

    dynamicOptions: {
        column: 3,
        item: 6,
        name: 'blog'
    }                  

must have key name and a unique name and other parameters for queryable data

settings:

type: (object) {}

required: required but can be empty

value:

settings:{
        tabname: {
            title: 'Column Setting',
            options: [
                {
                    settings1: {
                        title: 'Column',
                        // ....
                    },
                    settings2: {
                        title: 'Order',
                        // ....
                    },
                    offset: {
                        title: 'Offset',
                        // ....
                    },
                }
            ]
        }
    },              

settings must have a tabname as key and under value title and options are required. options will be array and inside that array an object. every single settings will go inside the final object.

name	is required	value	details
title	always required	responsive-class / input
type	always required
optionName	required if inputType == "responsive-class"	cmbClassTypes key from class-setting.js
subTitle	required if inputType == "input"
attribute	required if type == "input"	style / class / id / custom-class / prop / dynamic-layout
inputType	required if type == "input"	text / number / url / colorPicker / range / textarea / select / switch / dropdown / toggle / fourSided / fourCornered / image
defaultValue	required for toggle input type		mainly for toggle value, may be class name
styleName	required if type == "input" and attribute == "style		value is css style attribute if single field , for 4 sided input first part (margin, padding), wild card for border radius (border-*-radius), for border style first part only (border)
tagProp	if type=="input" and attribute == "prop"	name of the target prop
childItem			if option is required for subitem dom
pseudo	if attribute == "style"		if pseudo is required for the item
childPseudo	if attribute == "style"		if pseudo is required for any child item
unit	optional		t is px,%,rem etc. if unit is available in param then param unit is used else if main object unit is available then that one is used
placeholder	optional		mainly usable for text , url , number , some of border where text fields are used , fourSided , borderRadius, image if placeholder is available in param then param placeholder is used else if main object placeholder is available then that one is used
wrapperClass	optional		it is added in the setting input wrapper if given
blackList	optional		used if attribute == ( class / id ) if any value is available in blackList, value is removed
fieldParam	Required for select, switch etc	{}	if fieldParam is available in param then param fieldParam is used else if main object fieldParam is available then that one is used
param		{}/[]	if single input, use 0 as key and options as object if multiple object (for styles) use style attribute subpart (i.e: for margin, use left/right) as key and options as object param can be array if only value is required
relatedDynamicField	if attribute=="dynamic-layout"		value is a key from dynamicOptions

Param options

param options if object
//--------------
placeholder : '',       - optional, mainly usable for text , url , number , some of border where text fields are used , fourSided , borderRadius, image. if placeholder is available in param then param placeholder is used else if main object placeholder is available then that one is used

unit : [],              - optional. it is px,%,rem etc. if unit is available in param then param unit is used else if main object unit is available then that one is used

options : {},           - required for switch and select

fieldParam : {}         - Required for some input types (range). if fieldParam is available in param then param fieldParam is used else if main object fieldParam is available then that one is used

Methods

element Methods

onLoad: function(){},

beforeAdd: function(wrapperItem, addableContent){},

afterAdd: function(addedItem){},

beforeClone: function(copyableItem){},

afterClone: function(addedItem){},

beforeMove: function(movableItem){},

afterMove: function(movedItem, previousParent){},

beforePrev: function(processableItem,futureIndex){},

afterPrev: function(processedItem,PreviousIndex){},

beforeNext: function(processableItem,futureIndex){},

afterNext: function(processedItem,PreviousIndex){},

beforeDelete: function(deletableItem){},

afterDelete: function(parent){},

beforeSave: function(){},

afterSave: function(){},

Setting methods (inside settings)

beforeChange(targetDom){}

afterChange(targetDom){}

Follow These rules

do not use element name as id or class anywhere else

do not use prefix with cmb_ anywhere but in element

do not use cmb-element-tab- prefix anywhere in class name

do not use cmb-settings-tab- prefix anywhere in class name

do not use cmb-option-box-input anywhere

Forbidden Classes

cmb_*

cmb-element-tab-*

cmb-settings-tab-*

cmb-option-box-input

Forbidden IDs

cmb_*

Other Caution

setting tab name should not contain "|"