Element Structure

Every element is represented with settings files and js/PHP files. The best way to understand element structure is to clone our boilerplate repository on GitHub.

There are certain files required to build element:

  • manifest.json – describes element data, preview, thumbnail, description, category and PHP files;
  • package.json – npm install/update files for required node modules;
  • webpack.config – files to build a component with Webpack;
  • Directory {tag}*:
    • cssMixins directorycssMixin.pcss: POSTCSS file that holds mixin for custom generated style;
    • public directory – may contain custom CSS, JS, and images for public view
    • index.js – the main file, build with Webpack;
    • component.js – ReactJs component contains VCWB editor component. This component is used only in the editor and contains element built-in methods that provide additional functionality.
    • settings.json – describes element attributes;
    • *.php files – required PHP files (must be described in ../manifest.json);
    • editor.css – CSS files which will be used only in the editor;
    • style.css – CSS files which will be used on the frontend to display content.

Settings File

File settings.json stores description of attributes and element dependencies. An attribute is an object with a unique key. Attributes have a type, access, value and options (optional). Access represents an ability to change a value of the attribute from the inner part of the system. Options can differ for different attributes.

Attributes

There are two types of access of attributes:

  • Edit form attribute;
  • Meta attribute.

Edit form attributes are those attributes that represent any settings in editForm for a user. The editor has public access to attributes. Each attribute is displayed element form control which can be easily managed by customers with programming knowledge. Public attribute values can be accessed in the component.js file via this.props.atts. Each attribute has a type and options. Type is how this attributes will be displayed in editForm and how it will be saved in data storage of edited document. Options property is an object that may contain multiple properties which can extend an attribute.

Most common attribute options:

Nr Option Description
1 label A label which will be displayed in the Edit Form right before the attribute field
2 description A description which will be displayed in the Edit Form right after the attribute field
3 values An array of objects. Usually, each object consists of label and value properties
4 cssMixins Defines which POST CSS mixin to use, mixin variable and pattern
5 onChange Defines how to react to self or other attributes change

There are following attribute types available:

Nr Type Description
1 ajaxForm A form that is requested via AJAX call
2 animateDropdown Dropdown with a list of animation classes
3 attachimage Allows adding an image from Media Library
4 attachvideo Allows adding a video from Media Library
5 autocomplete Allows searching for value through the list
6 buttonGroup A set of buttons allowing to select one value out of multiple
7 checkbox Checkbox
8 color Colorpicker
9 customId String field used to add a custom id to element wrapper
10 designOptions Design Options to set margins, paddings, background color, etc.
11 dropdown List of values
12 element Allows inserting another element
13 googleFonts List of available Google Fonts with weight
14 group List of data values (used to group edit form attributes in edit form)
15 htmleditor WordPress Classic TinyMCE editor
16 iconpicker Icon picker to select an icon from the predefined libraries
17 inputIcon Icon picker with a search to select an icon from the predefined libraries
18 inputSelect Selector with a search to browse multiple data
19 multipleDropdown Dropdown with multiple select
20 number Input field with number type
21 paramsGroup A set of attributes contained within a separate group
22 radio Input field with radio type
23 range Slider with a range of values
24 rawCode Raw HTML code editor
25 string Input field
26 textarea Text area
27 toggle switcher (works as a checkbox)
28 toggleSmall A smaller version of toggle attribute is used to toggle skin color of TinyMCE editor
29 treeView Displays child elements as Tree View in Edit Form
30 url Link field which works via Link editor for WordPress

Meta attributes are system attributes with protected access. Meaning that these attributes can’t be edited and are used by the editor. There are following meta attribute keys available:

Nr Key Description
1 tag This unique tag is used to undefine and find element components and settings.
2 relatedTo Relation to groups. Used for drag and drop and add element panel. The default value is “General”
3 editFormTab1 List of edit form attributes in General section of the edit form
4 metaEditFormTabs List of sections in editForm. A section can be a group like “editFormTab1” or attribute like “designOptions”
5 containerFor Defines child element dependencies
6 initChildren Used to initiate child elements
7 groups Used to assign an element to a group of elements. Used for replacing elements
8 metaPublicJs A list of custom JS libraries which will be used by and related to a particular element
9 sharedAssetsLibrary A list of JS libraries which can be enqueued and used by multiple elements

Code example of settings file:

{
  "output": {
    "type": "htmleditor",
    "access": "public",
    "value": "<p>ElementBoilerplate API. HTML editor also the part of the editor</p>"
  },
  "designOptions": {
    "type": "designOptions",
    "access": "public",
    "value": {},
    "options": {
      "label": "Design Options"
    }
  },
  "editFormTab1": {
    "type": "group",
    "access": "protected",
    "value": [
      "output"
    ],
    "options": {
      "label": "General"
    }
  },
  "metaEditFormTabs": {
    "type": "group",
    "access": "protected",
    "value": [
      "editFormTab1",
      "designOptions"
    ]
  },
  "relatedTo": {
    "type": "group",
    "access": "protected",
    "value": [
      "General"
    ]
  },
  "tag": {
    "access": "protected",
    "type": "string",
    "value": "elementBoilerplate"
  }
}

Attributes may react to self or other attributes value change. The change is defined by the rules set and the action applied when the rule is matched (e.g. toggle attribute may show/hide another attribute field.) Rules and actions are defined under the onChange property within an attribute options property. An attribute may have multiple rules. A rule may have additional options.

Rule types:

Rule Description
true Reacts to any change of attribute
toggle Reacts to toggle type attribute value change
minlength Reacts to value change, checks for a min number of character in a string or min number of items in an array
maxlength Reacts to value change, checks for a max number of character in a string or max number of items in an array
range Reacts to value change, checks for a value in the range of min and max character numbers
minvalue Reacts to value change, checks for min value (number)
maxvalue Reacts to value change, checks for max value (number)
between Reacts to value change, checks for a value between min and max number values
value Reacts to value change, checks for the defined value
valueIn Reacts to value change, checks for a value in the defined values array
valueContains Reacts to value change, checks for a value in the defined value string
required Reacts to value change, checks for an empty value

Action types:

Action Description
toggleVisibility Toggles visibility of the attribute
toggleSectionVisibility Toggles visibility of the section in Edit Form (e.g. Button element section)
attachImageUrls Toggles visibility of Link Selector for attachimage attribute
fieldMethod Executes the method of the attribute

Manifest File

File manifest.json stores main meta information about the element:

  • Tag;
  • Name;
  • Description;
  • Thumbnail/Preview images URLs;
  • The category where the element should be available;
  • phpFiles list of PHP files to be autoloaded on WordPress init.
{
  "elements": {
    "imageGalleryWithTestZoom": {
      "settings": {
        "name": "Image Gallery With Test Zoom",
        "metaThumbnailUrl": "[publicPath]/image-gallery-with-zoom-thumbnail.png",
        "metaPreviewUrl": "[publicPath]/image-gallery-with-zoom-preview.png",
        "metaDescription": "A grid type image gallery with a test zoom effect upon hover to catch visitors' attention."
      }
    }
  },
  "categories": {
    "Image gallery": {
      "elements": [
        "imageGalleryWithTestZoom"
      ]
    }
  }
}

Note: The placeholder [publicPath] is required for the Visual Composer modules to automatically replace URL to element (relative to absolute).

Element categories

Element category specifies to which category the element belongs. Depending on a category a corresponding icon will be displayed in the Tree View panel and in the element controls when you hover over the element. Element category is specified in the manifest.json file and should always start with a capital letter. Below is the list of all available categories and how they should be defined, copy and paste to your project:

  • Row
  • Column
  • Tabs
  • Tab
  • Button
  • Header & Footer
  • Feature
  • Feature section
  • Section
  • Hero section
  • Icon
  • Image Slider
  • Single image
  • Image gallery
  • Text block
  • Misc
  • Pricing table
  • Social
  • Videos
  • WooCommerce
  • Separators
  • Maps
  • Grids
  • _postsGridSources
  • _postsGridItems
  • Toggle
  • Message Box
  • Hover Box
  • WordPress
  • Feature Description
  • Call To Action
  • Empty Space
  • Testimonial
  • Accordions
  • Accordion Section
  • Charts

Webpack Configs and Build

When all settings and components are done need to build element with a help of Webpack. Just use yarn install && yarn build.

yarn install // Install all the element dependencies (must be same as visualcomposer)
yarn build // Build development build
yarn watch // Watches & Build development version on file modification
yarn build-production // Builds the minified build