Skip to main content

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:​

ArgumentTypeDescription
fieldsarray of strings - requiredAll field ID's that need to get hidden. Values can be normalized
componentIdstringThe 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

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' ]);

hideField​

Arguments:​

ArgumentTypeDescription
fieldstring - requiredField ID of the field that will get hidden. Values can be normalized
componentIdstringThe 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

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');

Showing Fields​

revealFields​

Arguments:​

ArgumentTypeDescription
fieldsarray of strings - requiredAll field ID's that need to get shown. Values can be normalized
componentIdstringThe 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

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' ]);

revealField​

Arguments:​

ArgumentTypeDescription
fieldstring - requiredThe field ID that need to get shown. Values can be normalized
componentIdstringThe 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

This example will show all form fields named form_field_123456.

window.wyng['_WYNG_ID_'].revealField('form_field_123456');

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:​

ArgumentTypeDescription
fieldsarray of strings - requiredArray of field ID's that need to be made required shown. Values can be normalized
componentIdstringThe 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

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']);

requireField​

Arguments:​

ArgumentTypeDescription
fieldstring - requiredField ID of the field that will be made required. Values can be normalized
componentIdstringThe 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

This example will make form field named form_field_123456 required.

window.wyng['_WYNG_ID_'].requireField('form_field_123456');