Developer Docs

Appearance

On this page

Forms widget ​

Forms API ​

This guide is about how to use the fields returned from the forms fetch api from Bildhive platform in order to build custom form widget.

The forms api can be used to fetch the form structure and the fields from Bildhive platform. You can review api specific documentation here.

In this guide, we are going to look at how to use the fields returned by the /v1/forms/:formId API to populate the correct input for your users and map them properly when submitting to the Bildhive platform.

Basic field types ​

It is important to note that all basic field types have a predefined name attribute. Please refer to the sample HTML under each basic field type for their predefined names. Also, basic field types have an additional hide field that custom field types do not, which indicates whether the field is supposed to be shown on the form or not.

Email ​

The email field is a mandatory field in your form and should be included in all forms.

Sample Email Field Object:

json
{
	"type": "email",
	"id": 1625071276284,
	"label": "Email",
	"placeholder": "Email",
	"required": true
}

Sample HTML with Email Field:

liquid
<div>
    <div>{{ field.label }}</div>
    <input type=”email” name=”email” id=”{{ field.id }}” placeholder=”{{ field.placeholder }}” required />
</div>

Name ​

The name field contains a first and last name, with an optional prefix, middle initial, and suffix.

Sample Name Field Object:

json
{
	"id": 1690986621629,
	"hide": false,
	"type": "name",
	"label": "Name",
	"required": false,
	"middleInitial": false,
	"prefix": false,
	"suffix": false,
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…"
}

Sample HTML with Name Field:

liquid
{% if field.prefix %}
<div>
	<div>Prefix</div>
	<input type=”text” name=”prefix” id=”{{field.id}}” placeholder=”Prefix” />
</div>
{% endif %}

<div>
	<div>First Name</div>
	<input type=”text” name=”firstName” id=”{{field.id}}” placeholder=”First Name” {{required if field.required == true}} />
</div>

{% if field.middleInitial %}
<div>
	<div>Middle Name</div>
	<input type=”text” name=”middleName” id=”{{field.id}}” placeholder=”Middle Name” />
</div>
{% endif %}

<div>
	<div>Last Name</div>
	<input type=”text” name=”lastName” id=”{{field.id}}” placeholder=”Last Name” {{required if field.required == true}} />
</div>

{% if field.suffix %}
<div>
	<div>Suffix</div>
	<input type=”text” name=”suffix” id=”{{field.id}}” placeholder=”Suffix” />
</div>
{% endif %}

Phone Number ​

The phone number field represents the phone number associated with the lead.

Sample Phone Number Field Object:

json
{
	"country": "",
	"default": "",
	"format": "National",
	"hide": false,
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": 1690986621630,
	"label": "Phone Number",
	"placeholder": "",
	"required": false,
	"type": "phone"
}

Sample HTML with Phone Number Field:

liquid
<div>
	<div>{{field.label}}</div>
	<input type=”tel” name=”phone” id=”{{field.id}}” maxlength=”10” placeholder=”{{field.placeholder}}” {{required if field.required == true}} />
</div>

Address ​

The address field represents the lead’s address which includes: Address One, Address Two, City, Province, Postal, and Country fields

Sample Address Field Object:

json
{
	"id": 1690986621631,
	"hide": false,
	"type": "address",
	"label": "Address",
	"required": false,
	"country": "Canada",
	"options": {
		"addressOne": true,
		"addressTwo": true,
		"city": true,
		"province": true,
		"postal": true,
		"country": false
	},
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…"
}

Sample HTML with Address Field:

liquid
{% if field.options.addressOne %}
<div>
	<div>Address One</div>
	<input type=”text” name=”address” id=”{{field.id}}” placeholder=”Address One” {{required if field.required == true}} />
</div>
{% endif %}

{% if field.options.addressTwo %}
<div>
	<div>Address Two</div>
	<input type=”text” name=”address2” id=”{{field.id}}” placeholder=”Address Two” {{required if field.required == true}} />
</div>
{% endif %}

{% if field.options.city %}
<div>
	<div>City</div>
	<input type=”text” name=”city” id=”{{field.id}}” placeholder=”City” {{required if field.required == true}} />
</div>
{% endif %}

{% if field.options.province %}
<div>
	<div>Province</div>
	<input type=”text” name=”region” id=”{{field.id}}” placeholder=”Province” {{required if field.required == true}} />
</div>
{% endif %}

{% if field.options.postal %}
<div>
	<div>Postal Code</div>
	<input type=”text” name=”postal” id=”{{field.id}}” placeholder=”Postal Code” {{required if field.required == true}} />
</div>
{% endif %}

Agent ​

The agent field allows the lead to determine whether they are an agent or not. There are multiple ways that this field can be configured which is denoted by the displayType field. Please refer to the documentation below.

Sample Agent Field Object:

json
{
	"id": 1690986621632,
	"hide": false,
	"type": "isAgent",
	"displayType": "checkbox",  //checkbox, radio, or dropdown
	"label": "Are you a realtor?",
	"required": false,
	"default": 1,  //either 1 or 0
	"options": [
		{
			"option": 1
		},
		{
			"option": 0
		}
	],
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…"
}

Please refer to the Sample HTML on how to integrate each displayType into your form.

Sample HTML with Agent Field - "checkbox" Display Type:

liquid
<div>
	<label>
		<input type=”checkbox” id=”{{field.label}}” name=”isAgent” value=”1” />
		<span></span>
		{{field.label}}
	</label>
</div>

Sample HTML with Agent Field - "radio" Display Type:

liquid
<div>
	<div>{{field.label}}</div>
	<div>
		<div>
			<label>
				<input type=”radio” {{checked if field.default == 1}} id=”{{option.option}}” name=”isAgent” value=”1” {{required if field.required == true}} />
				<span></span>
				Yes
			</label>
		</div>
		<div>
			<label>
				<input type=”radio” {{checked if field.default == 0}} id=”{{option.option}}” name=”isAgent” value=”0” {{required if field.required == true}} />
				<span></span>
				No
			</label>
		</div>
	</div>
</div>

Sample HTML with Agent Field - "dropdown" Display Type:

liquid
<div>
	<div>{{field.label}}</div>
	<select name=”isAgent” id=”{{field.id}}” value=”{{field.selected}}” {{required if field.required == true}}>
		<option value=”” disabled selected>Please select</option>
		<option value=”1” {{selected if field.default == 1}}>Yes</option>
		<option value=”0” {{selected if field.default == 0}}>No</option>
	</select>
</div>

Custom field types ​

Unlike basic field types, custom field types do not have a predefined name attribute but instead, are named using the field’s id. Please refer to the sample HTML under each custom field type on how each field is named.

Custom field types also include a displayType field which represents the HTML tag/type that is supposed to be used in order to correctly show each field.

Text Input ​

The text input field is the most common field used to collect text input from a lead. Although the displayType defaults to text, it can be displayed with either a normal text input, or a textarea input.

Sample Text Input Field Object:

json
{
	"includeEmail": false,
	"type": "text",
	"label": "Text Input",
	"displayType": "text",
	"placeholder": "",
	"required": false,
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986639410XXX"
}

Sample HTML with Text Input Field:

liquid
<div>
	<div>{{field.label}}</div>
	<textarea rows=”5” name=”custom.{{field.id}}” id=”{{field.id}}” placeholder=”{{field.placeholder}}” {{required if field.required == true}}></textarea>
</div>

OR

liquid
<div>
	<div>{{field.label}}</div>
	<input type=”text” name=”custom.{{field.id}}” id=”{{field.id}}” placeholder=”{{field.placeholder}}” {{required if field.required == true}} />
</div>

Number Input ​

The number input field is used to collect any sort of number information that is not the phone number.

Sample Number Input Field Object:

json
{
	"includeEmail": false,
	"type": "number",
	"label": "Number Input",
	"displayType": "number",
	"placeholder": "",
	"required": false,
	"min": "1",
	"max": "100",
	"digitLength": "",
	"decimal": 0,
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986642088XXX"
}

Sample HTML with Number Input Field:

liquid
<div>
	<div>{{field.label}}</div>
	<input type=”number” min=”{{field.min}}” max=”{{field.max}}” minlength=”{{field.digitLength}}” maxlength=”{{field.digitLength}}” name=”custom.{{field.id}}” id=”{{field.id}}” placeholder=”{{field.placeholder}} {{required if field.required == true}} />
</div>

PLEASE NOTE: If field.digitLength is not an empty string, ensure to include the following oninput inside your <input> tag:

oninput=”javascript: if (this.value.length > this.maxLength) this.value = this.value.slice(0, this.maxLength);”

Sample Dropdown List Field Object:

json
{
	"includeEmail": false,
	"type": "dropdown",
	"label": "Dropdown List",
	"displayType": "select",
	"placeholder": "",
	"required": false,
	"selected": "",
	"options": [
		{
			"option": "Option 1"
		},
		{
			"option": "Option 2"
		},
		{
			"option": "Option 3"
		}
	],
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986644345XXX"
}

Sample HTML with Dropdown List Field:

liquid
<div>
	<div>{{field.label}}</div>
	<select name=”custom.{{field.id}}” id=”{{field.id}}” value=”{{field.selected}}” {{required if field.required == true}}>
		{% if field.placeholder != ‘’ %}
		<option value=”” disabled selected>{{field.placeholder}}</option>
		{% endif %}

		{% for option in field.options %}
		<option value=”{{option.option}}” {{selected if option.option == field.default}}>{{option.option}}</option>
		{% endfor %}

		{% if field.other %}
		<option value=”other”>Other</option>
		{% endif %}
	</select>
</div>

Radio Button ​

Sample Radio Button Field Object:

json
{
	"includeEmail": false,
	"type": "radio",
	"label": "Radio Button",
	"displayType": "radio",
	"required": false,
	"selected": "Option 1",
	"options": [
		{
			"option": "Option 1"
		},
		{
			"option": "Option 2"
		},
		{
			"option": "Option 3"
		}
	],
	"other": false,
	"otherText": "Other:",
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986646756XXX"
}

Sample HTML with Radio Button Field:

liquid
<div>
	<div>{{field.label}}</div>
	<div>
		{% for option in field.options %}
		<label>
			<input {{checked if option.option == field.default}} type=”radio” id=”{{option.option}}” name=”custom.{{field.id}}” value=”{{option.option}}” {{required if field.required == true}} />
			<span></span>
			{{option.option}}
		</label>
		{% endfor %}

		{% if field.other %}
		<div>
			<label>
				<input type=”radio” name=”custom.{{field.id}}” value=”other”>
				{% if field.otherText and field.otherText != ‘’ %}
				<span>{{field.otherText}}</span>
				{% else %}
				<span></span>
				{% endif %}

				<input type=”text” name=”custom.{{field.id}}.other” style=”max-width: 100px;” />
			</label>
		</div>
	</div>
</div>

Checkbox ​

The checkbox input field can be displayed in two different ways. One is with multiple checkbox options, the other is just a single checkbox. The specific checkbox type is denoted with the “multiple” field. Please refer to the sample HTML below for reference on how to show each type.

Sample Checkbox Field Object:

json
{
	"includeEmail": false,
	"type": "checkbox",
	"label": "Checkbox",
	"displayType": "checkbox",
	"required": false,
	"multiple": true,
	"selected": "Option 1",
	"options": [
		{
			"option": "Option 1"
		},
		{
			"option": "Option 2"
		},
		{
			"option": "Option 3"
		}
	],
	"other": false,
	"otherText": "Other:",
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986648739XXX"
}

Sample HTML with Checkbox Field - Multiple Type:

liquid
<div>
	<div>{{field.label}}</div>
	<div>
		{% for option in field.options %}
		<div>
			<label>
				<input data-input-checkbox=”{{required if field.required==true}}” type=”checkbox” {{checked if
					option.option==field.default}} id=”{{option.option}}” value=”{{option.option}}”
					name=”custom.{{field.id}}” />
				<span></span>
				{{option.option}}
			</label>
		</div>
		{% endfor %}

		{% if field.other %}
		<div>
			<label>
				<input type=”checkbox” id=”other” name=”custom.{{field.id}}” />

				{% if field.otherText and field.otherText != ‘’ %}
				<span>{{field.otherText}}</span>
				{% else %}
				<span></span>
				{% endif %}

				<input type=”text” name=”custom.{{field.id}}.other” style=”max-width: 100px;” />
			</label>
		</div>
		{% endif %}
	</div>
</div>

Sample HTML with Checkbox Field - Single Type:

liquid
<div>
	<label>
		<input type=”checkbox” id=”{{field.label}}” name=”custom.{{field.id}}” {{required if field.required == true}} />
		<span></span>
		{{field.label}}
	</label>
</div>

Date/Time ​

Sample Date/Time Field Object:

json
{
	"includeEmail": false,
	"type": "date",
	"label": "Date/Time",
	"displayType": "date",
	"placeholder": "",
	"required": false,
	"dateFormat": "HH:mm",
	"timeEnable": false,
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986650823XXX"
}

Sample HTML with Date/Time Field - With Time Enabled:

liquid
<div>
	<div>{{field.label}}</div>
	<input type=”datetime-local” id=”{{field.id}}” name=”custom.{{field.id}}” value=”” {{required if field.required == true}} />
</div>

Sample HTML with Date/Time Field - With Time Disabled:

liquid
<div>
	<div>{{field.label}}</div>
	<input type=”date” id=”{{field.id}}” name=”custom.{{field.id}}” value=”” {{required if field.required == true}} />
</div>

File Attachment ​

Sample File Attachment Field Object:

json
{
	"includeEmail": false,
	"type": "file",
	"label": "File Attachment",
	"displayType": "file",
	"buttonLabel": "Upload",
	"maxSize": 10,
	"placeholder": "",
	"format": "any",
	"required": false,
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986653060XXX"
}

Sample HTML with File Attachment Field:

liquid
<div>
	<div>{{field.label}}</div>

	<div style=”display: flex;”>
		<input type=”file” accept=”image/jpeg, image/png, application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document” name=”custom.{{field.id}}” id=”{{field.id}}” data-inputid=”{{field.id}}” {{required if field.required == true}} />
		<label for=”{{field.id}}” >Upload</label>
	</div>
</div>

Tag Field ​

The tag field applies the value(s) of the selected option(s) as a tag to the lead upon form submission. The tag field can either be in the form of a dropdown or multiple checkboxes. Please refer to the following for correct implementation.

Sample Tag Field Object:

json
{
	"includeEmail": false,
	"type": "tag",
	"label": "Tag Field",
	"displayType": "checkbox",
	"placeholder": "",
	"multiple": false,
	"required": false,
	"selected": "",
	"options": [
		{
			"option": "Option 1"
		},
		{
			"option": "Option 2"
		},
		{
			"option": "Option 3"
		}
	],
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986655077XXX"
}

If field.multiple is false, the tag field can be implemented as a dropdown.

Sample HTML with Tag Field - Single Dropdown:

liquid
<div>
	<div>{{field.label}}</div>
	<select name=”custom.{{field.id}}” id=”{{field.id}}” value=”{{field.selected}}” {{required if field.required == true}}>

		{% for option in field.options %}
		<option value=”{{option.option}}” {{selected if option.option == field.default}}>{{option.option}}</option>
		{% endfor %}
	</select>
</div>

If field.multiple is true, the tag field can be implemented with multiple checkboxes.

Sample HTML with Tag Field - Multiple Checkbox:

liquid
<div>
	<div>{{field.label}}</div>
	<div>
		{% for option in field.options %}
		<div>
			<label>
				<input data-input-checkbox=”{{required if field.required == true}}” type=”checkbox” {{checked if option.option == field.default}} id=”{{option.option}}” value=”{{option.option}}” name=”custom.{{field.id}}” />
				<span></span>
				{{option.option}}
			</label>
		</div>
		{% endfor %}
	</div>
</div>

Select Children ​

The Select Children field is used to feed children instances with leads. When the lead selects a specific child from the list of options and submits the form, they will also be registered as a lead in the child they selected. Please refer to the following for correct implementation.

The Select Children field is also the only custom field that includes the hide field. The hide field is usually used when you still want to feed specific children with the same lead without needing the user to physically select specific children on the form.

Sample Select Children Field Object:

json
{
	"includeEmail": false,
	"type": "child",
	"label": "Select Children",
	"displayType": "checkbox",
	"placeholder": "",
	"required": false,
	"hide": false,
	"selected": "",
	"options": [
		{
			"label": "Real Instance Name",
			"id": "607cf5a7bbd6f0132699faeb",
			"active": true,
			"selected": false,
			"option": "Child Instance One"
		}
	],
	"default": "",
	"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" style=\"margin-top…",
	"id": "1690986658556XXX"
}

If field.hide is true, ensure that the <input> has the display: none style applied to it.

Sample HTML with Select Children Field - Hidden:

liquid
{% for option in field.options %}
	<input data-input-checkbox=”{{required if field.required == true}} type=”checkbox” {{checked if option.selected == true}} id=”{{option.option}}” name=”custom.{{field.id}}” value=”{{option.option}}” style=”display: none;” />
{% endfor %}

If field.hide is false, show the Select Children Field as regular checkbox fields.

Sample HTML with Select Children Field - Checkbox:

liquid
<div>
	<div>{{field.label}}</div>
	<div>
		{% for option in field.options %}
		<div>
			<label>
				<input data-input-checkbox=”{{required if field.required == true}}” type=”checkbox” {{checked if option.selected == true}} id=”{{option.option}}” value=”{{option.option}}” name=”custom.{{field.id}}” />
				<span></span>
				{{option.option}}
			</label>
		</div>
		{% endfor %}
	</div>
</div>

Submit the Form ​

The payload for a form submission has to be submitted using the FormData object where all the field names on the form are appended to it.

For fields with the same “name” attribute, merge their values together and separate them with commas. Refer to the following:

custom.1690986648739XXX: Option 1,Option 2

Forms Tracking ​

With Bildhive, the forms created and implemented using the Bildhive website builder are automatically tracked for the information about the referrer, source and campaigns.

If you have implemented the form on a custom website, you have to setup your forms for tracking separately. Thankfully, we have created a code snippet that you can apply on the page where you have your form.

Place this snippet before the closing </body> tag

html
<body>
	<!-- Rest of the website -->

	<script src="https://res.bildhive.com/scripts/inbound-traffic-parser/inbound-traffic-parser.umd.cjs"></script>
	<script src="https://res.bildhive.com/scripts/inbound-traffic-parser/form-tracking.js"></script>

	<script>
	    (function() {
	        // Select all form elements with bildhive-form class
	        document.querySelectorAll('form.bildhive-form')
	            .forEach(function(form) {
	                /*
                     * To initialize the tracking for your form,
					 * pass the form element to the initializeTracking function.
					 */
	                initializeTracking(form);
	            });
	    })();
	</script>
</body>