How it Works

You can enable your users to add forms in Beefree SDK with two methods:

• by passing in the configuration parameters a single, default JSON form, potentially including all the fields your application supports, and then have customers build and style forms with our form content block.

• by implementing a content dialog on top of the form content block and building a user interface on top of the builder, so that your users can either browse and select pre-built forms or build a new form.

Pass a Single Form

Your application passes a single JSON form, potentially including all the fields that may be required in a form. You are in control of which fields are visibile when the form is dragged. From there, users have a vast control on how to customize the form, by:

• adding or removing fields

• rearranging their order

• renaming their labels

• editing their type

This is the quickest way to get started using forms. You may also decide to include such forms inside templates provided by your application.

Learn more about this method

Pass Multiple Forms

If you want to pass more than one form to the builder, you can do so by implementing a Content dialog on top of the form content block.

With a content dialog, you have full control over the experience of adding a form. A few examples:

• users can select a form from a predefined list

• users can browse a list of forms and pick one

• users can pick a form and have configuration options (e.g. define a layout) before adding it

Here is an example of form selection built with a Content Dialog.

Once the content dialog returns a form to the application, users can then change the form content properties in the builder, by adding and removing fields, rearranging their order. and customizing their labels and style

Learn more about this method

Load Your Form Builder

You may even want to go a step further and use the Content dialog to load your UI for form creation, on top of the builder; your users will be able to create a new form and add it to the web content they’re building, without interrupting their workflow.

Embed a Third-Party Form

As an alternative to the above-mentioned methods, your users can add an HTML block and easily embed forms created with any form builder available on the market (e.g. Typeform, JotForm, etc.).

Form builders typically offer different options to get an embed code:

• if the embed code is a script, it will not appear in the stage when building the web content. Due to security reasons, we need to remove such scripts during edit mode. The form will appear regularly both in the preview and in the final HTML output. An example of this behavior is the embed code produced by Typeform;

• If the embed code lives in an iframe, it will be visible during editing as well. For example, Jotform and Google Forms offer this kind of embedding option.

Customizing forms

Once a form is added to the web content, the user has these options to manage fields:

• Add and remove fields (unless they are marked as required)

• Rearrange their order

• Rename their labels

Besides, end users can edit fields, when the “edit” action is available.

Finally, users can apply various styling options to the form:

• change font type, size, and style;

• change colors for text and input backgrounds

• change size for field inputs

• define borders and paddings

• position field labels on the top or on the side of the input fields

• style buttons

• and more . . .

Editing Form Fields

When managing fields in a form block, users can click on the “Edit” action to change field types and properties. To facilitate the user, the icon next to the label highlights the current field type.

A modal window will pop up:

From this modal, users can:

• change field type

• change general field properties

  • label (available also in the sidebar)

  • placeholder (not available for date, multiple/single choice, dropdown)

  • required field

  • read-only field

Clicking on “Type” will open a dropdown with all the available field types:

All fields can be edited, unless:

• you defined the field in the JSON form as not editable, using the canBeModified attribute

• the field type is

  • Submit

  • Hidden

  • File upload

  • Label (a special field type with plain text)

Now, let’s have a closer look at the field types that can be configured with the “Edit field” modal.

Email / Phone / Text / Url

These are the easiest field types to configure, as they only have the optional Placeholder property.

The email and URL types will check at form submission, through HTML5 validation, that the value entered is a formally correct email/web address.

Single choice / Multiple choice / Dropdown

Users need to enter the values that will be displayed to visitors. To do this, they will add those values under Options:

They can either:

• Enter a single value, which will be both the label and the value passed to the host app in the form.

• Enter couplets such as label | value to differentiate the label shown to visitors from the value passed to your app after form submission. In the example above, users will select Milan from the dropdown at the city they want to visit, but your app will receive “A” as the response for that field.

The Multiple choice type can also be used to create checkboxes, e.g. privacy policy acceptance. In this case, no value should be specified, and any external URL should be added in the field label, like in this example:

Date

This type has no additional properties. The date format of the value returned to the host app will be coherent with browser locale information.

Visitors will enter the date using the browser’s date picker. Otherwise, they can input the date directly, following the automatically generated placeholder for the expected date format.

Number

This type has the option to enter a minimum and/or a maximum allowed value. If not entered, the field will accept any number.

Number fields have a “spinner” input that visitors can use to cycle through allowed values. Visitors can also input a number directly, but the HTML 5 validation will verify if the submitted number falls into the permitted interval.

Long text

This type is just like a text field, but it’s meant for longer inputs. It has an additional “row height” property to define the default height for the text area – which can be adjusted by the visitor by dragging the bottom right corner. Here is how a long text field looks like in a form:

What happens after a form is submitted?

Beefree SDK just passes the data back to the host application. It doesn’t save anything or touch any of the data.

You can implement client-side validation in your JSON forms using the built-in HTML5 form validation, to validate things like:

• required field;

• response length, for strings (“must be less than” or “must be higher than” n characters);

• response value for numbers (minimum or maximum value allowed);

• correct type (i.e. the field must contain a number, email address, or some other specific preset type);

• check against a regular expression that defines a pattern the entered data needs to follow.

Any other post-submission validation and action must be defined and performed by your application, for instance:

• validating whether the data is acceptable, i.e. email already registered;

• saving it into a database;

• passing it to a 3rd application;

• performing other actions (e.g. sending an email notification).

Developer resources

Passing forms to the Builder

Learn how to implement the different methods to pass forms to the Builder

Form structure and parameters

A closer look at how to structure a JSON form

Sample forms and templates

Visit our GitHub account to:

• dive into some sample forms and quick start your integration;

• download templates that include those forms;

• get a validation JSON schema to test your forms with.

Global Attributes

The following global attributes are applicable across all field types. They define essential properties related to accessibility, content structure, behavior, and presentation. Reference the Global attributes and Attributes sub-sections of the to try out the attributes and learn more about their specifications.

List of Global Attributes and their corresponding explanations:

• accesskey: Defines a shortcut key to activate or focus an element.

• class: Assigns one or more class names to an element, used for styling and script interaction.

• contenteditable: Indicates whether the content of the element is editable.

• dir: Specifies the text direction (ltr, rtl, or auto).

• disabled: Disables an element, making it not selectable.

• readonly: Prevents modification of the element’s content while still allowing interaction.

• draggable: Allows the element to be dragged.

• hidden: Hides the element.

• id: Assigns a unique identifier to an element.

• name: Specifies the name of the form control. Reference the mdn web docs on the name attribute to try it and learn more about its specifications.

• itemid: Provides a unique identifier for items when using microdata.

• itemprop: Specifies properties for microdata.

• itemref: References other items related to the current item for microdata.

• itemscope: Defines the scope of an item for microdata.

• itemtype: Defines the type of an item for microdata.

• lang: Declares the language of the element’s content.

• tabindex: Defines the tab order for focusable elements.

• title: Provides additional information about an element, often used as a tooltip.

• value: Specifies the value of the input element.

Unique Attributes

Checkbox Field

The checkbox field allows users to select multiple options from a list. It is often used to toggle between two states, like "checked" or "unchecked."

Unique Attributes:

• checked (boolean): Specifies whether the checkbox is selected by default.

Available Options:

• options: An array of options, each with:

  • value (string)

  • label (string)

Color Field

The color field allows users to select a color from a color picker.

Unique Attributes:

• autocomplete (string): Specifies if the browser should provide autocomplete suggestions.

• list (string): Refers to a <datalist> that provides predefined color options.

• required (boolean): Specifies that the field must be filled before form submission.

Datalist Field

The datalist field provides a list of predefined options for other input fields, enhancing usability by offering suggestions.

Unique Attributes:

No unique attributes.

Available Options:

• options: An array of options, each with:

  • value (string)

Date Field

The date field allows users to select a date, displayed as a date picker.

Unique Attributes:

• autocomplete (string): Specifies if the browser should suggest previously entered dates.

• max (string): Sets the maximum date allowed.

• min (string): Sets the minimum date allowed.

• required (boolean): Specifies that a date must be selected before submission.

• step (string): Specifies the granularity of selectable dates (e.g., steps in days).

Datetime-Local Field

The datetime-local field allows users to input both a date and a time.

Unique Attributes:

• autocomplete (string)

• max (string): Sets the maximum allowed date and time.

• min (string): Sets the minimum allowed date and time.

• required (boolean): Requires a date and time before form submission.

• step (string): Specifies the granularity of selectable times (e.g., steps in minutes).

Email Field

The email field is used for inputting one or more email addresses.

Unique Attributes:

• autocomplete (string)

• maxlength (string): Specifies the maximum number of characters allowed.

• minlength (string): Specifies the minimum number of characters required.

• multiple (boolean): Allows multiple email addresses.

• placeholder (string): Displays a hint to the user.

• required (boolean): Requires an email address before form submission.

• size (string): Sets the visible width of the input.

File Field

The file field allows users to upload one or more files from their device.

Unique Attributes:

• accept (string): Specifies the types of files accepted by the server (e.g., image/png).

• capture (string): Allows capturing images/audio from the camera/microphone if supported.

• multiple (boolean): Allows selecting multiple files.

• required (boolean): Specifies that at least one file must be uploaded.

Hidden Field

The hidden field stores data that the user cannot see or interact with but is submitted with the form.

Unique Attributes:

• autocomplete (string)

Image Field

The image field creates a graphical submit button using an image.

Unique Attributes:

• alt (string): Provides alternate text if the image cannot be displayed.

• height (string): Specifies the image URL.

• src (string): Defines the height of the image (in pixels).

• width (string): Defines the width of the image (in pixels).

Label Field

The label field associates a text label with a form control, improving accessibility.

Unique Attributes:

No unique attributes.

Month Field

The month field allows users to select a month and year without choosing a specific day.

Unique Attributes:

• autocomplete (string)

• max (string): Specifies the latest allowed month.

• min (string): Specifies the earliest allowed month.

• required (boolean): Ensures a selection is made before form submission.

• step (string): Defines the interval for month selection.

Number Field

The number field allows users to input numeric values.

Unique Attributes:

• autocomplete (string)

• max (number): Sets the maximum allowed value.

• min (number): Sets the minimum allowed value.

• required (boolean): Requires a numeric value before submission.

• step (number): Specifies the allowed increment for numbers.

Password Field

The password field allows users to input masked text (e.g., passwords).

Unique Attributes:

• autocomplete (string)

• maxlength (string): Limits the number of characters allowed.

• minlength (string): Sets the minimum number of characters required.

• pattern (string): Specifies a regular expression for validation.

• placeholder (string): Provides a hint to the user.

• required (boolean): Specifies that the field must be filled.

• size (string): Defines the visible width of the input.

Radio Field

The radio field allows users to select one option from a group.

Unique Attributes:

• checked (boolean): Indicates whether the radio button is selected by default.

• required (boolean): Specifies that one option must be selected before form submission.

Available Options:

• options: An array of options, each with:

  • value (string)

  • label (string)

Range Field

The range field allows users to select a numeric value within a range, often displayed as a slider.

Unique Attributes:

• autocomplete (string)

• max (number): Sets the maximum allowed value.

• min (number): Sets the minimum allowed value.

• step (number):Defines the granularity of the range (e.g., steps in increments of 1 or 10).

Select Field

The select field creates a dropdown list that allows users to choose one or more options.

Unique Attributes:

• autocomplete (string)

• multiple (boolean): Allows multiple selections if set to true.

• required (boolean): Specifies that the user must select at least one option.

• size (string): Defines the number of visible options in the dropdown.

Available Options:

• options: An array of options, either:

  • option elements, with:

    • value (string)

    • label (string)

  • optgroup elements, containing groups of options.

Search Field

The search field allows users to enter search queries with specialized input handling.

Unique Attributes:

• autocomplete (string)

• dirname (string): Submits the text directionality of the search field with the form.

• maxlength (string): Limits the number of characters allowed in the input.

• minlength (string): Specifies the minimum number of characters.

• placeholder (string): Provides a hint about the expected input.

• required (boolean): Ensures that a search term is entered before submission.

Submit Field

The submit field creates a button that submits the form data.

Unique Attributes:

• data-sitekey (string): Used in conjunction with reCAPTCHA to verify form submissions.

• data-callback (string): Defines a JavaScript function to be executed after submission.

• data-action (string): Defines an action to be associated with the submit button.

• width (string): Defines the width of the submit button.

Tel Field

The tel field allows users to enter telephone numbers.

Unique Attributes:

• autocomplete (string)

• maxlength (string): Limits the number of characters allowed.

• minlength (string): Sets the minimum number of characters required.

• pattern (string): Provides a pattern for validation (e.g., for formatting telephone numbers).

• placeholder (string): Displays a hint about the expected input.

• required (boolean): Specifies that a telephone number must be entered before submission.

• size (string): Defines the visible width of the input.

Text Field

The text field allows users to input text.

Unique Attributes:

• autocomplete (string)

• maxlength (string): Limits the number of characters allowed.

• minlength (string): Specifies the minimum number of characters.

• pattern (string): Provides a regular expression for validation.

• placeholder (string): Displays a hint for the expected input.

• required (boolean): Ensures that a value is entered before form submission.

• size (string): Specifies the visible width of the text input.

Textarea Field

The textarea field allows for multi-line text input, offering more space than the text field.

Unique Attributes:

• autocomplete (string)

• cols (number): Defines the visible width of the textarea in characters.

• rows (number): Defines the visible height of the textarea in lines.

• maxlength (string): Limits the number of characters allowed.

• minlength (string): Sets the minimum number of characters required.

• placeholder (string): Provides a hint about the expected input.

• spellcheck (string): Enables or disables spell checking.

• wrap (string): Controls text wrapping behavior (e.g., "hard" or "soft").

• required (boolean): Specifies that input is mandatory before form submission.

Time Field

The time field allows users to input a time (hours, minutes, and optionally seconds).

Unique Attributes:

• autocomplete (string)

• max (string): Sets the latest allowable time.

• min (string): Sets the earliest allowable time.

• required (boolean): Requires a time to be entered before form submission.

• step (string): Specifies the time granularity (e.g., steps in seconds).

URL Field

The url field is used for inputting valid URLs.

Unique Attributes:

• autocomplete (string)

• maxlength (string): Sets the maximum number of characters allowed.

• minlength (string): Specifies the minimum number of characters required.

• placeholder (string): Provides a hint for the expected input.

• required (boolean): Ensures that a valid URL is entered before form submission.

Week Field

The week field allows users to select a specific week within a year.

Unique Attributes:

• autocomplete (string)

• max (string): Specifies the latest week that can be selected.

• min (string): Specifies the earliest week that can be selected.

• required (boolean): Requires a week to be selected before form submission.

• step (string): Specifies the granularity of week selection.

Form fields that can be edited

The following table provides an overview of the form fields that support the edit form field modal, including a description of each field and an example of its content.

Form fields that cannot be edited

The following table provides an overview of the form fields that do not support the edit form field modal, including a description of each field and an example of its content.

Overview of Form Block

The Form Block within Beefree SDK allows you to easily create and integrate customizable forms into your application. This feature is particularly useful for capturing user information, feedback, and other data directly through interactive forms. With various pre-built templates and customization options, the Form Block is easy to integrate for developers and intuitive to use for end users.

into page or popup builders is straightforward. The SDK provides intuitive methods to embed forms within your web pages or popups. With drag-and-drop functionality and predefined settings, adding a form to a design can be accomplished in just a few steps, enhancing workflow efficiency for your application's end users.

The Form Block supports a wide range of input types, such as text fields, radio buttons, checkboxes, and dropdown menus. This flexibility ensures that end users can gather the exact type of information they need from the form. Additionally, form submissions can be easily configured to trigger actions, such as email notifications or data storage, providing a robust and integrated data collection solution.

Learn more about to use and integrate Form Block in the following section:

Overview

A form is defined through the structure object, which includes its main properties.

This is the object that the host application passes to Beefree SDK, 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 the application and is saved in the design’s JSON file. Therefore, the same form can be used in different designs, and have message-specific styles.

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

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

Attributes

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

Fields

If you want to use a single form, 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

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

Layout

If you want to leverage the full power of Beefree SDK 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:

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.

Using reCAPTCHA

To embed Google ReCaptcha in a Form you need a Google API key for ReCaptcha, the key has to be enabled for a specific website URL or domain; this is crucial because otherwise the script will load but will fail its validation, returning API key errors.

Here’s what’s needed in the submit action when passing a form configuration:

In addition, you have to add an HTML block that imports the reCaptcha library inside the template that encapsulates the form:

Here’s a sample JSON config for the submit button:

Ensure you keep the following in mind:

• Make sure HTML sanitize is OFF (this is the default value).

• Remember that the reCaptcha UI elements will be visible neither in the Beefree SDK work area nor in the Preview, but they will be integrated when the page will be published. Furthermore, the page has to be hosted on the domain that was enabled on the Google Developers Console when setting the reCaptcha.

Overview

This document outlines how you can customize a form’s layout, and discusses the available layout customization options. These options allow you to adjust various elements of forms to improve your end's user experience creating them. Form layout options ensure your application's end users have more tools to create a more effective presentation of their forms.

Key form layout customization options include:

• Multiple choice and radio button orientation: You can adjust the orientation of multiple choice and radio button elements, choosing between horizontal or vertical alignment to suit your design preferences or space constraints.

• New layout presets: Three layout presets are available: horizontal, vertical, and grid. These presets define the overall structure of the form, allowing you to easily apply a consistent layout across fields.

The form field width includes the following customization option:

• Form field width property: A new boolean property, fullWidth, enables you to manage form field widths. When set to true, the field will expand to 100% width. When set to false, it the field width is set to 50%.

The following video provides a visual representation of these customization options and how they function within the user interface.

Prerequisites

Prior to getting started, ensure you have the following:

• Beefree SDK Plan

  • Page builder or Popup builder application within your Dev Console

Implementing Multiple and Single Choice Orientation

For this implementation, there is a field called orientation in the JSON at the field object level. This field controls the layout orientation for multiple-choice and single-choice fields, which include radio buttons and checkboxes. The orientation field accepts the following two values:

• horizontal

• vertical

JSON Structure Example

The following JSON display an example of the updated structure for a radio button field with the orientation field included:

{
    "structure": {
        "fields": {
            "gender": {
                "type": "radio",
                "label": "Gender",
                "orientation": "vertical",  // Newly added field for layout orientation
                "attributes": {},
                "options": [
                    {
                        "type": "option",
                        "value": "M",
                        "label": "Male"
                    },
                    {
                        "type": "option",
                        "value": "F",
                        "label": "Female"
                    },
                    {
                        "type": "option",
                        "value": "-",
                        "label": "Not telling"
                    }
                ]
            }
        },
        "layout": [
            [
                "gender"
            ]
        ]
    },
    "attributes": {},
    "style": {
        "labels": {},
        "fields": {},
        "buttons": {}
    }
}

Steps to Configure the Orientation Field in JSON

Take the following steps to configure the orientation field:

1. Locate the form field object in the JSON: Find the field you want to configure, such as a radio button or checkbox field. This will be under the "fields" key within the JSON structure.

2. Add the orientation property: Inside the field object, add a new property called orientation.

3. Set the value: Assign the orientation field a value of either "horizontal" or "vertical", depending on how you want the options displayed in the form.

   Copy

   "orientation": "vertical"

4. Save the changes: After making the necessary updates to the JSON structure, ensure that the changes are saved.

5. Test the form: Once the JSON is updated, test the form to ensure that the options are displayed in the correct orientation. If the field is missing, check if the default horizontal orientation is applied.

These steps will allow you to effectively control the layout orientation of multiple-choice fields in your forms.

Implementing New Form Layout Presets

The layout of the form fields can be controlled using a new layoutPreset field. This field is located in the structure object of the JSON and supports three possible values:

• vertical

• horizontal

• grid

JSON Structure Example

Here is an example of a form JSON structure utilizing layout presets:

{
    "structure": {
        "layoutPreset": "grid",  // New field to define form layout
        "fields": {
            "email": {
                "type": "email",
                "label": "Email Address",
                "fullWidth": true,  // Only applicable for 'grid' preset
                "attributes": {}
            }
        }
    },
    "attributes": {},
    "style": {
        "labels": {},
        "fields": {},
        "buttons": {}
    }
}

Layout Presets

The following list shows the available options for layout presets.

• Vertical: Fields will be stacked vertically, one on top of another.

• Horizontal: Fields will be aligned horizontally, side by side.

• Grid: Fields will be organized into a grid layout, allowing for more complex positioning.

Steps to Configure Form Layout Presets in JSON

Take the following steps to configure the layoutPreset field:

1. Locate the structure object in the JSON: Find the structure key within the form’s JSON definition where the fields and layout are defined.

2. Add or modify the layoutPreset field: Inside the structure object, add a new property called layoutPreset.

3. Set the desired value: Assign the layoutPreset field one of the following values to control the layout of the form:

   • "vertical": Stack fields vertically.

   • "horizontal": Align fields horizontally.

   • "grid": Organize fields in a grid format.

   Example:

   Copy

   "layoutPreset": "horizontal"

4. Configure field properties (if applicable): If you are using the grid layout, you may also need to adjust other field properties like fullWidth to control the width of individual fields. For example, set "fullWidth": true to make a field span the full width of the grid column.

5. Save and test the form: After setting the layoutPreset, save the updated JSON structure and test the form layout to ensure the fields are displayed according to the selected preset.

By following these steps, you can easily configure and control the layout of your form fields using the new layoutPreset field.

Implementing the fullWidth Field

A new boolean field, fullWidth, has been introduced within each form field object. This field is applicable only when the layout preset is set to grid. If a layout other than grid is used, the fullWidth field will be ignored or removed from the JSON structure.

In a grid layout, setting fullWidth to true will cause the form field to span the entire width of the grid column, while setting it to false will restrict the field's width to a smaller portion of the grid.

Steps to Configure the fullWidth Field in JSON

Take the following steps to configure the fullWidth field:

1. Ensure the layout preset is set to grid: The fullWidth field only functions when the form’s layout preset is set to "grid". Verify that the "layoutPreset" field in the JSON is set to "grid".

2. Locate the desired form field: In the JSON structure, find the field you want to configure, such as an email or text field.

3. Add the fullWidth field: Inside the form field object, add a new property called fullWidth.

4. Set the boolean value:

   • Set fullWidth to true to make the form field span the entire width of the grid column.

   • Set fullWidth to false if you want the form field to occupy half or a portion of the grid column.

   Example:

   Copy

   "fullWidth": true

5. Save the changes: After adding or modifying the fullWidth field, save the updated JSON structure.

6. Test the form in grid layout: Ensure that the form’s layout is set to grid and that the field's width behaves as expected.

By following these steps, you can effectively configure the fullWidth property to control the width of form fields in grid layouts.

End User Interaction

• Layout Widget: End users can change the layout preset using a layout widget available in the form sidebar.

• Field Width Widget: When the form is using the grid preset, the fullWidth field can be modified by users through a field width widget available in the Manage Fields section or the Edit Form Modal.

The Submit field will always have fullWidth set to true, and the corresponding widget will be disabled to ensure it spans the full width. For more details on the end user experience, reference the Form Layout Customization end user documentation.

Providing forms

You can load forms in the builder with two methods:

• by passing in the configuration parameters a single, default JSON form, potentially including all the fields your application supports;

• by implementing a content dialog and building a user interface on top of the builder, so that your users can browse and select forms.

If you successfully implement either method, you’ll see a new Form content tile in the builder Content tab.

Let’s see in detail how these methods work.

Default form in starting configuration

Use this method to provide a default form in the configuration parameters when the builder starts.

defaultForm: {
  // Form
},

The default form will load when the user drags the form tile from the “Content” tab into the stage.

Here is an example of a typical login form:

defaultForm: {
  structure: {
    title: 'Form title',
    fields: {
      email: {type: 'email', label: 'Email'},
      password: {type: 'password', label: 'Password'},
      submit: {type: 'submit', label: ' ', attributes: {value: 'Login'}},
    },
    layout: [
      ['email', 'password', 'submit']
    ]
  }
},

The default form you pass to a Beefree SDK application may consist of a simple form (e.g., the most used one), or a longer form that the user can customize using the options in the form content properties, as pictured here:

The flexibility of these properties allows you to cover multiple form building capabilities, even when implementing just a default form. Let’s see how.

For higher flexibility and better user experience, the form can be customized with the optional canBeModified, canBeRemovedFromLayout, and removeFromLayout attributes.

Disable editing for a field

This attribute can be used to turn off the “Edit field” dialog for a field. If set to false, the configuration for that field will be locked to the one defined in the form JSON you passed to the application, except for the label.

If unspecified, it will be applied as true, allowing the user to edit the field using the builder UI.

Indicate when a field can be toggled off

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

This attribute indicates that a field is toggled off by default when the form is loaded. This behavior is quite useful to simplify the first experience when working with forms:

1. you can use a single form with all the possible fields, so there is no form selection step;

2. you can hide less common fields to load the most used combination at first, and keep the starting point simple, or even empty;

3. the user than can explore available fields with the form properites and build their custom form

Here is an example:

defaultForm: {
    "structure": {
        "fields": {
            "name": {
                "type": "text",
                "label": "Name",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true
            },
            "surname": {
                "type": "text",
                "label": "Surname",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true,
            },
            "email": {
                "type": "email",
                "label": "Email *",
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "required": true
                }
            },
            "notes": {
                "type": "textarea",
                "label": "Notes",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true
            },
			"privacy": {
                "type": "checkbox",
                "label": "Accept privacy policy. [Read it here](http://example.com)",
                "canBeModified": false,
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "required": true
                }
            },
            "submit_button": {
                "type": "submit",
                "label": "",
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "value": "SEND DATA",
                    "name": "submit_button"
                }
            }
		}
	}
},

When added, the form shows the minimum fields for submtting an email, e.g. for subscribing to a newsletter:

but then, the user can toggle on the available fields to transform it:

Implementing a content dialog

The content dialog allows you to build a user interface for selecting a form, on top of the builder. It can be a simple list with prebuilt forms, a search through categorized forms, a small form configurator or wizard, or even a complete form builder tailored for your application’s data.

For detailed information about this feature, please check the content dialog section.

The object that defines the form content dialog is the following:

 manageForm: {
            label: 'Change form',
            handler: async (resolve, reject, args) => { 
              // Your function
            } 
          },

As with most content dialog objects, the label is used within the interface to trigger the function:

The resolve object in the handler function must return a form using the structure and parameters described in this section.

The args object in the handler function returns to the host application the form object already applied. With this information, the application can decide what to display to the user (e.g., edit the current form, suggest a similar form, etc.).

An example of the content dialog object in beeConfig that handles special links and forms:

contentDialog: {
  specialLinks: {
    label: 'Custom text for links',
    handler: function(resolve, reject) {
      openMySpecialLinkDialog() // Replace this with your application function
        .then(specialLink => resolve(specialLink))
        .catch(() => reject())
    }
  },
  manageForm: {
    label: 'Edit form',
    handler: async (resolve, reject, args) => { 
      const structure = await onHandleManageForm(args)
      structure ? resolve(structure) : reject()
      } 
  },
},