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

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 npm install && npm run build.

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