Form Methods
Forms are a good way to interact with visitors in an Experience. Often forms require dynamically set data, or even dynamically defined fields. Using the Experience JS SDK it is possible to set form field values and show or hide form fields. The methods bellow all work on Forms in one way or another.
Setting Values​
Often times a value needs to be set in an Experience, this can be a specific ID, or the value of a form field. The following functions allow these values to be set programmatically.
External User Id​
The Wyng platform provides several different ways to identify users, however to better integrate with other systems it can be useful to use a non-Wyng User Id. Wyng provides the possibility to do so through the setUserId()
function. Any string or numeric value can be used as an Id. To make forms aware of the External User Id, a field of "Hidden Value: External User ID" can be added to the form. This field will be hidden from the user, and will be populated with the string or numeric value that is set through the setUserId()
function.
Examples​
Setting a User Id from custom code​
The user Id can be set using any type of code. This example shows how to set the user Id using some custom code that produces the user Id
function customFunctionGetUserId() {
// custom javascript code to get the user Id in a variable called userId
return userId
}
window.wyng['_WYNG_ID_'].setUserId(customFunctionGetUserId());
Setting a User Id from a URL parameter​
This example shows how to set the user Id that is passed in using a URL parameter. In this example, the URL parameter is userId
function getUrlParameter(name) {
name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]');
var regex = new RegExp('[\\?&]' + name + '=([^&#]*)');
var results = regex.exec(location.search);
return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' '));
};
window.wyng['_WYNG_ID_'].setUserId(getUrlParameter('userId'));
Setting form fields​
Forms are a big part of most Experiences. Often times the fields in forms need to be dynamically set. Fields can be set dynamically using the setField (for one field at a time) and setFields (multiple fields at once) functions.
Fields types with non-string values​
Most form fields will expect a string as the value. However there are a few form field types that expect a different data type for the value. See the examples listed by the setAndValidateFormField method for all the different field types their possible formats.
In the examples listed below, we have tried to incorporate some non-string type examples. However we refer back to the setAndValidateFormField section for all possible examples. Unless otherwise indicated, the setField
and setFields
methods use the same formats as setAndValidateFormField to set Values.
Examples​
Setting a single field value​
The following code will set the value for a field named email_address_7615019884892
to john.smith@my-email.com
window.wyng['_WYNG_ID_'].setField('email_address_7615019884892', 'john.smith@my-email.com');
Setting multiple values at once​
The following code will set multiple values in one call. It will set
email_address_7615019884892
to john.smith@my-email.com, first_547245235432
to John and last_356363463634
to Smith
It will also check the checkboxes for "Choice 2", and "Choice 4" in the mult-select field multi_select_543216449245
, while unchecking all of its other fields. For the date field date_9876543210
is will set the value to January 25, 2014. The calendar date field calendar_date_56798723424987
will be set to August 7,1993
window.wyng['_WYNG_ID_'].setFields({
email_address_7615019884892: 'john.smith@my-email.com',
first_547245235432: 'John',
last_356363463634: 'Smith',
multi_select_543216449245: ["Choice 2", "Choice 4"],
date_98776543210: {
monthValue: '1',
dayValue: '25',
yearValue: '2014',
},
calendar_56798723424987: new Date("1993-08-07"),
});
Normalized field names​
Wyng form fields are given names that are made up out of a part identifying the field type, and a randomly generated integer. While it is possible to rename most fields to something else, this is almost never done. Because it can be tedious to have to find the exact field Id, the setField
and setFields
functions have been written to allow for normalized field names to be set. Utilizing this feature also increases the ease of use when reusing code from different experiences.
caution
When using the normalized field names, it is important to realize that the setField
and setFields
functions will set ALL matching fields in all components in the experience. If an experience has multiple components that have form fields that match, all those fields will be set. However if a single component has multiple fieds that could match the normalized name, a warning will be thrown which can be found in the console.
Examples​
Set a single field value​
The same examples are used as described above. A field named email_address_7615019884892
will be set to john.smith@my-email.com
window.wyng['_WYNG_ID_'].setField('email_address', 'john.smith@my-email.com');
Setting multiple values at once​
Again the same example as above. The following code will set multiple values in one call. It will set
email_address_7615019884892
to john.smith@my-email.com, first_547245235432
to John and last_356363463634
to Smith
window.wyng['_WYNG_ID_'].setFields({
email_address: 'john.smith@my-email.com',
first: 'John',
last: 'Smith',
multi_select: ["Choice 2", "Choice 4"],
date: {
monthValue: '1',
dayValue: '25',
yearValue: '2014',
},
calendar: new Date("1993-08-07"),
});
Hiding Fields​
Fields can be defined in the Form, but under certain circumstances the field might not be needed. In that case, the field needs to be hidden. This can be done with either the hideFields
or the hideField
method. Both methods do the same thing. The only difference being that hideField
will only hide one field at a time, while hideFields
allow multiple fields to get hidden in one function call.
When fields get hidden using the SDK the fields will be removed from the front-end completely. Please be advised that fields that have been marked as Required in the Experience Builder will not be allowed to be hidden. If a field is marked as required and it matches the hideField
or hideFields
call, an error will be printed in the console about that specific field, and the specific field will not get hidden.
hideFields​
Arguments:​
Argument | Type | Description |
---|---|---|
fields | array of strings - required | All field ID's that need to get hidden. Values can be normalized |
componentId | string | The componentId of the form that the fields are in |
Hide multiple form fields at once. The argument componentId
is optional. If it is not provided, all matching form fields in all forms in the experience will get hidden.
The form fields are normalized
- All Forms
- Specific Form
This example will hide all form fields named form_field_123456
as well as form fields starting with first_
(normalized). Form fields named first
will also get hidden.
window.wyng['_WYNG_ID_'].hideFields([ 'form_field_123456', 'first' ]);
This example will hide all form fields in the form with component ID sign_up_436366175206
named form_field_123456
as well as form fields starting with first_
(normalized). Form fields named first
will also get hidden.
window.wyng['_WYNG_ID_'].hideFields([ 'form_field_123456', 'first' ], 'sign_up_436366175206');
hideField​
Arguments:​
Argument | Type | Description |
---|---|---|
field | string - required | Field ID of the field that will get hidden. Values can be normalized |
componentId | string | The componentId of the form that the fields are in (optional) |
Hide a form field. The argument componentId
is optional. If it is not provided, all fields that having a matching Field ID on all forms in the experience will get hidden.
The form fields are normalized
- All Forms
- Specific Form
This example will hide all form fields named form_field_123456
. No componentId is specified, so matching fields in all forms in the experience will get hidden.
window.wyng['_WYNG_ID_'].hideField('form_field_123456');
This example will hide all form fields in the form with component ID sign_up_436366175206
named form_field_123456
window.wyng['_WYNG_ID_'].hideField('form_field_123456', 'sign_up_436366175206');
Showing Fields​
revealFields​
Arguments:​
Argument | Type | Description |
---|---|---|
fields | array of strings - required | All field ID's that need to get shown. Values can be normalized |
componentId | string | The componentId of the form that the fields are in |
Show multiple hidden form fields at once. The argument componentId
is optional. If it is not provided, all matching form fields in all forms in the experience will get hidden.
The form fields are normalized
- All Forms
- Specific Form
This example will show all form fields named form_field_123456
as well as form fields starting with first_
(normalized). Form fields named first
will also get revealed.
window.wyng['_WYNG_ID_'].revealFields([ 'form_field_123456', 'first' ]);
This example will reveal all form fields in the form with component ID sign_up_436366175206
named form_field_123456
as well as form fields starting with first_
(normalized). Form fields named first
will also get revealed.
window.wyng['_WYNG_ID_'].revealFields([ 'form_field_123456', 'first' ], 'sign_up_436366175206');
revealField​
Arguments:​
Argument | Type | Description |
---|---|---|
field | string - required | The field ID that need to get shown. Values can be normalized |
componentId | string | The componentId of the form that the field is in (optional) |
Show multiple hidden form fields at once. The argument componentId
is optional. If it is not provided, all matching form fields in all forms in the experience will get hidden.
The form fields are normalized
- All Forms
- Specific Form
This example will show all form fields named form_field_123456
.
window.wyng['_WYNG_ID_'].revealField('form_field_123456');
This example will reveal the form field in the form with component ID sign_up_436366175206
named form_field_123456
.
window.wyng['_WYNG_ID_'].revealField('form_field_123456', 'sign_up_436366175206');
Making Fields Required​
Making fields be required dynamically can be done using these methods. Please be advised that while this will add the verification to the front end, the back end will not do any additional validations. If it is important that the backend does a validation, the required checkbox in the Form Edit Modal in the Experience Builder should be used.
requireFields​
Arguments:​
Argument | Type | Description |
---|---|---|
fields | array of strings - required | Array of field ID's that need to be made required shown. Values can be normalized |
componentId | string | The componentId of the form that the field is in (optional) |
Make multiple form fields required at once. The argument componentId
is optional. If it is not provided, all matching form fields in all forms in the experience will get hidden.
The form fields are normalized
- All Forms
- Specific Form
This example will make form fields named form_field_123456
required as well as all form fields that normalize to last
.
window.wyng['_WYNG_ID_'].requireFields(['form_field_123456', 'last']);
This example will make the form fields in the form with component ID sign_up_436366175206
named form_field_123456
and fields that normalize to last
required.
window.wyng['_WYNG_ID_'].requireFields(['form_field_123456', 'last'], 'sign_up_436366175206');
requireField​
Arguments:​
Argument | Type | Description |
---|---|---|
field | string - required | Field ID of the field that will be made required. Values can be normalized |
componentId | string | The componentId of the form that the field is in (optional) |
Make a form field required. The argument componentId
is optional. If it is not provided, all matching form fields in all forms in the experience will get hidden.
The form field can be a normalized value
- All Forms
- Specific Form
This example will make form field named form_field_123456
required.
window.wyng['_WYNG_ID_'].requireField('form_field_123456');
This example will make the form field in the form with component ID sign_up_436366175206
named form_field_123456
required.
window.wyng['_WYNG_ID_'].requireField('form_field_123456', 'sign_up_436366175206');