Form Elements
The Form Elements component enables real-time synchronization of form elements, such as input fields, checkboxes, and radio buttons, among participants in the same room as well as seeing who is typing in real-time.
Before we start
Before utilizing the Form Elements component, it is essential to initialize a room with a defined name and ID for the participant and the group. You will also need that every form element on your page has a unique ID, including each value of a radio button or checkbox.
Supported form elements
When using the Form Elements component, you will be able to synchronize the following input types: text
, textarea
, checkbox
, color
, date
, datetime-local
, email
, month
, number
, password
, radio
, range
, search
, tel
, time
, url
and week
.
When using the date
, datetime-local
, and time
, please note that it will be synchronized once the user finalizes typing a valid value, not while typing. Also, please use the password
input type with caution.
Unsupported form elements
The following input types are not supported: div
with content-editable
, reset
, submit
, button
, file
, hidden
, image
, and input
with type="hidden"
.
How to use
To add the Form Elements component on your web page, you will need form elements with unique IDs and then use the following code in your HTML file:
<label>
Name:
<input type="text" id="name" name="name" />
</label>
<label>
Email:
<input type="email" id="email" name="email" />
</label>
<label>
What is your kind of pet?
<input type="radio" name="pet" value="cat" id="cat" /> Cat
<input type="radio" name="pet" value="dog" id="dog" /> Dog
<input type="radio" name="pet" value="fish" id="fish" /> Fish
</label>
To make this form synchronize with every participant, you will need to add the following code in your JavaScript file:
import { FormElements } from '@superviz/sdk';
const formElements = new FormElements({
fields: ['name', 'email', 'dog', 'cat', 'fish'],
});
room.addComponent(formElements);
Properties
See below the parameters to use when initializing the Form Elements:
Name | Type | Description |
---|---|---|
fields | string[] or string | Specify the ID of the form elements that you want to be synchronized. |
disableOutline | boolean | Disables the outline of the form elements. |
disableRealtimeSync | boolean | Disables the real-time synchronization of the form content. |
When adding a form element ID to the fields
property, make sure that the is rendered on the page before initializing the Form Elements component.
Events
The Forms Elements in SuperViz SDK offer a range of events that allow you to monitor and respond to interactions and changes within the input elements.
BLUR
The BLUR
event is triggered when an input element loses focus.
Example:
- JavaScript
- TypeScript
formElements.subscribe('field.blur', onBlur);
function onBlur(event) {
// do something
}
import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';
formElements.subscribe(FieldEvents.BLUR , onBlur);
function onBlur(event: InputEvent) {
// do something
}
On the callback function, you will receive an InputEvent
object.
FOCUS
The FOCUS
event is triggered when an input element gains focus.
Example:
- JavaScript
- TypeScript
formElements.subscribe('field.focus', onFocus);
function onFocus(event) {
// do something
}
import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';
formElements.subscribe(FieldEvents.FOCUS , onFocus);
function onFocus(event: InputEvent) {
// do something
}
On the callback function, you will receive an InputEvent
object.
CONTENT_CHANGE
The CONTENT_CHANGE
event is triggered when the content of an input element changes, it only works when a field is registered and Real-time Sync is enabled.
Example:
- JavaScript
- TypeScript
formElements.subscribe('field.contentChange', onContentChange);
function onContentChange(event) {
// do something
}
import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';
formElements.subscribe(FieldEvents.CONTENT_CHANGE , onContentChange);
function onContentChange(event: InputPayload) {
// do something
}
On the callback function, you will receive an object with the following arguments:
Name | Type | Description |
---|---|---|
value | string | The new value of the input element. |
fieldId | string | The ID of the input element. |
color | string | The color of the participant that is currently editing the element. |
showOutline | boolean | Whether the outline of the input element is enabled. |
syncContent | boolean | Whether the real-time synchronization of the input element is enabled. |
attribute | string | The attribute of the input element that was changed. |
INTERACTION
The INTERACTION
event is triggered when a participant interacts with an input element, such as typing or selecting a value. This event only works when a field is registered, but it will also fire when the Real-time Sync is disabled.
Example:
- JavaScript
- TypeScript
formElements.subscribe('field.interaction', onInteraction);
function onInteraction(event) {
// do something
}
import { FieldEvents } from '@superviz/sdk/lib/components/form-elements/types';
formElements.subscribe(FieldEvents.INTERACTION , onInteraction);
function onInteraction(event: InputPayload) {
// do something
}
On the callback function, you will receive an object with the following arguments:
Name | Type | Description |
---|---|---|
value | string | The new value of the input element. |
fieldId | string | The ID of the input element. |
color | string | The color of the participant that is currently editing the element. |
showOutline | boolean | Whether the outline of the input element is enabled. |
syncContent | boolean | Whether the real-time synchronization of the input element is enabled. |
attribute | string | The attribute of the input element that was changed. |
Methods
enableOutline()
The enableOutline
method allows you to enable the outline of a specific form element. You need to pass the ID of the element as a parameter.
Enabling this feature through this method overrides the global flag enableOutline
set in the constructor for this particular input.
Example:
formElements.enableOutline("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
disableOutline()
The disableOutline
method allows you to disable the outline of a specific form element. You need to pass the ID of the element as a parameter.
Disabling this feature through this method overrides the global flag disableOutline
set in the constructor for this particular input.
Example:
formElements.disableOutline("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
enableRealtimeSync()
The enableRealtimeSync
method allows you to enable the real-time synchronization of the data of an input element. You need to pass the ID of the element as a parameter.
Enabling this feature through this method overrides the global flag disableRealtimeSync
set in the constructor for this particular input.
Example:
formElements.enableRealtimeSync("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
disableRealtimeSync()
The disableRealtimeSync
method allows you to disable the real-time synchronization of the data of an input element. You need to pass the ID of the element as a parameter.
Disabling this feature through this method overrides the global flag disableRealtimeSync
set in the constructor for this particular input.
Example:
formElements.disableRealtimeSync("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
registerField()
The registerField
method allows you to register a form element to receive updates from other participants. By utilizing this method, you don't need to enable the input field on the Form Elements constructor, allowing you to add a form element to the synchronization after the initialization. You need to pass the ID of the element as a parameter.
Example:
formElements.registerField("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
deregisterField()
The deregisterField
method allows you to deregister a form element to stop receiving updates from other participants. You need to pass the ID of the element as a parameter.
Example:
formElements.deregisterField("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |
sync()
When using the sync
method, a registered field will be monitored and most interactions with it will be shared with every other user in the room that is tracking the same field. Examples of common interactions that will be monitored include typing, focusing, and blurring.
Example:
formElements.sync("name");
Parameters
Name | Type | Description |
---|---|---|
fieldId | string | Required. The ID of the form element. |