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:

NrOptionDescription
1labelA label which will be displayed in the Edit Form right before the attribute field
2descriptionA description which will be displayed in the Edit Form right after the attribute field
3valuesAn array of objects. Usually, each object consists of label and value properties
4cssMixinsDefines which POST CSS mixin to use, mixin variable and pattern
5onChangeDefines how to react to self or other attributes change

There are following attribute types available:

NrTypeDescription
1ajaxFormA form that is requested via AJAX call
2animateDropdownDropdown with a list of animation classes
3attachimageAllows adding an image from Media Library
4attachvideoAllows adding a video from Media Library
5autocompleteAllows searching for value through the list
6buttonGroupA set of buttons allowing to select one value out of multiple
7checkboxCheckbox
8colorColorpicker
9customIdString field used to add a custom id to element wrapper
10designOptionsDesign Options to set margins, paddings, background color, etc.
11dropdownList of values
12elementAllows inserting another element
13googleFontsList of available Google Fonts with weight
14groupList of data values (used to group edit form attributes in edit form)
15htmleditorWordPress Classic TinyMCE editor
16iconpickerIcon picker to select an icon from the predefined libraries
17inputIconIcon picker with a search to select an icon from the predefined libraries
18inputSelectSelector with a search to browse multiple data
19multipleDropdownDropdown with multiple select
20numberInput field with number type
21paramsGroupA set of attributes contained within a separate group
22radioInput field with radio type
23rangeSlider with a range of values
24rawCodeRaw HTML code editor
25stringInput field
26textareaText area
27toggleswitcher (works as a checkbox)
28toggleSmallA smaller version of toggle attribute is used to toggle skin color of TinyMCE editor
29treeViewDisplays child elements as Tree View in Edit Form
30urlLink 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:

NrKeyDescription
1tagThis unique tag is used to undefine and find element components and settings.
2relatedToRelation to groups. Used for drag and drop and add element panel. The default value is “General”
3editFormTab1List of edit form attributes in General section of the edit form
4metaEditFormTabsList of sections in editForm. A section can be a group like “editFormTab1” or attribute like “designOptions”
5containerForDefines child element dependencies
6initChildrenUsed to initiate child elements
7groupsUsed to assign an element to a group of elements. Used for replacing elements
8metaPublicJsA list of custom JS libraries which will be used by and related to a particular element
9sharedAssetsLibraryA 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:

RuleDescription
trueReacts to any change of attribute
toggleReacts to toggle type attribute value change
minlengthReacts to value change, checks for a min number of character in a string or min number of items in an array
maxlengthReacts to value change, checks for a max number of character in a string or max number of items in an array
rangeReacts to value change, checks for a value in the range of min and max character numbers
minvalueReacts to value change, checks for min value (number)
maxvalueReacts to value change, checks for max value (number)
betweenReacts to value change, checks for a value between min and max number values
valueReacts to value change, checks for the defined value
valueInReacts to value change, checks for a value in the defined values array
valueContainsReacts to value change, checks for a value in the defined value string
requiredReacts to value change, checks for an empty value

Action types:

ActionDescription
toggleVisibilityToggles visibility of the attribute
toggleSectionVisibilityToggles visibility of the section in Edit Form (e.g. Button element section)
attachImageUrlsToggles visibility of Link Selector for attachimage attribute
fieldMethodExecutes 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