Form structure and parameters

  1. Overview
  2. Attributes
  3. Fields
  4. Layout
  5. Title and description

Overview

A form is defined through the structure object, which includes its main properties.
This is the object that the host application passes to BEE, and it includes fields, layout, and attributes along with a title and a description string values that you can use. The appearance of the form, in terms of styling of labels / fields / buttons (spacing, colors, etc…) is handled directly in BEE Plugin and is saved in the message’s JSON file. Therefore, the same form can be used in different messages, and have message-specific styles.

To take a look at real-world examples and samples, you can head to our dedicated GitHub page.

Let’s now examine the anatomy of a BEE form structure.




{
    "structure": {
        "attributes": {},
		"fields": {},
        "layout": [],
        "title": "Form title",
        "description": "Form description"
    }
}


Attributes

This object contains the general form attributes as strings: all of them are standard HTML5 attributes.

Property Value
action string
method string
target string
accept-charset string
autocomplete string
enctype string
novalidate boolean
dir string

Fields

An object that lists all the form fields included in the form with its relative properties. The order in which they appear only matters if you pass a single form to BEE Plugin. If you want to use the content dialog to feed forms in the BEE editor, the order is not relevant and you can set the form layout in the layout array.

BEE supports the vast majority of standard HTML5 form fields. A few of them (such as color, datetime, datalist) have mixed browser support, so please make sure to check browser compatibility before using them.

To see them in action, you can find a few examples on our dedicated GitHub page. Instead, head over here if you need the full list of allowed field types, along with the available attributes and options for each of them.

If you want to use a single form with BEE, you can use the optional canBeRemovedFromLayout and removeFromLayout attributes to determine (respectively) if that specific field can be removed from the layout by the user, and if it should appear in the stage when the form is dragged in.

Indicate when a field can be toggled off

 

Attribute Applies to Type Default value
canBeRemovedFromLayout all fields boolean true

This attribute indicates that a field can be toggled off by the user. If unspecified, it will be applied as true, allowing the user to switch it on or off in the builder UI.

It’s a best practice to add canBeRemovedFromLayout: false to mandatory fields (e.g., the email address field in a sign-up form) so that they can’t be excluded in the HTML form.

Toggle off a field when loading a form

 

Attribute Applies to Type Default value
removeFromLayout all fields boolean false

This attribute indicates that a field is toggled off by default when the form is loaded. This behavior is particularly useful to simplify the user experience when you implement forms in the Page Builder through a default form in the configuration parameters.

Layout

If you want to leverage the full power of BEE forms and use a content dialog to feed the form to the editor’s stage, the layout array will determine how the fields will appear to the user.
Each layout element is an array itself and represents a single line of fields. This allows different layout dispositions, including multi-column.

Probably the best way to represent this is with an example:

"layout":[
["name"],
["surname"],
["email"],
["privacy_checkbox"],
["submit"]
]
"layout":[
["email","telephone"],
["notes"],
["privacy_checkbox"],
["submit"]
]

Title and description

The form title is a string value. It is not displayed to the user while working in the editor but provides extra information that can be used later for troubleshooting. Likewise, description as a string value that is not displayed to the user while working in the editor, but provides extra information that can be used later for troubleshooting or internal reference.