surveyJS

API

Options | Methods | Prototype | Events | Templates

NOTE
surveyJS class extends formJS class ( NOT Lite version ), so it:

Inherits all formJS features ( properties, options, methods and built-in events ). See formJS API
Has also its own properties, methods, built-in events as listed below

Keep in mind that options.url is mandatory as shown in page Get Started

Features included in Lite version have this badge: Lite

Get a quick peek of features included in Lite version: show more close

Options

cssClasses ( all )
initAjaxOptions ( all )
messages ( all )
showErrorMessage
templates ( all )

Methods

as main version

Prototype

as main version

Events

as main version

Templates

as main version

Options

surveyJS inherits all formJS options and you can initialize the survey with some extra options:

name

name, type

description

cssClasses

Lite

Type: object

JS object with keys:

checkbox: ( string ) css class(es) to be applied to checkbox fields
field: ( string ) css class(es) to be applied to input fields in general ( if the specific one is not found )
file: ( string ) css class(es) to be applied to field with type="file"
label: ( string ) css class(es) to be applied to label tags
radio: ( string ) css class(es) to be applied to radio fields
wrapper: ( string ) css class(es) to be applied to select fields
- checkbox: ( string ) css class(es) to be applied to checkbox fields wrapper ( wrapper HTML is defined in options.tempaltes.wrapper.field )
- field: ( string ) css class(es) to be applied to form fields wrapper in general ( if the specific one is not found. Wrapper HTML is defined in options.tempaltes.wrapper.field )
- radio: ( string ) css class(es) to be applied to radio fields wrapper ( wrapper HTML is defined in options.tempaltes.wrapper.field )

NOTE: specific field types can be added. For example you can add email: 'field-email' and the specified CSS class(es) will be added to all inputs with of type "email".

fieldOptions

Type: object

JS object with field options to run the Form instance for the Survey.
See formJS plugin for details.

formOptions

Type: object

JS object with field options to run the Form instance for the Survey.
See formJS plugin for details.

initAjaxOptions

Lite

Type: object

JS object with ajax options passed to the fetch call to retrieve the survey data.

messages

Lite

Type: object

JS object with keys:

error: ( string ) Text to show on generic field error validation. You can also specify a custom error message in JSON file ( see JSON File )
errorMultiChoice: ( string ) Text to show on error validation of checkboxes with multiple choice.
maxChoice: ( string ) This text can be used for quesions that let the user choose more than one answer ( checkboxes ).

showErrorMessage

Lite

Type: boolean

whether or not to create the field error message inside the HTML ( shown on failed field validation )

templates

Lite

Type: object

Templates used to create the survey.
See Templates section for details.

JS object with keys:

error: ( string ) HTML string to be used as field error message container ( on failed field validation ).
input: ( string ) HTML string to be used for input fields
label: ( string ) HTML string to be used for label elements
loading: ( string ) HTML container and text for the loading box. Used when waiting survey data
select: ( string ) HTML string to be used for select fields
textarea: ( string ) HTML string to be used for textarea fields
wrapper: ( object )
- field: ( string ) HTML string to be used as wrapper for each field ( input, select, textarea )
- nested: ( string ) HTML string to be used as wrapper for nested fields ( see example in demos )
- question: ( string ) HTML string to be used as wrapper for each question
- related: ( string ) HTML string to be used as wrapper for related fields ( see example in demos )

useWebStorage

Type: boolean

Whether or not to use JS session storage to save user answers while compiling the survey.
When reloading the page, JS session storage will be used to polulate the questions with the answers selected/typed by the user.
Note that sessionStorage for the survey will be cleared on submit success.

Default options:

{
    cssClasses: {
        checkbox:           'form-check-input',
        field:              'form-control',
        file:               'form-control-file',
        label:              'form-check-label',
        radio:              'form-check-input',
        wrapper: {
            checkbox:       'form-check',
            field:          '',
            radio:          'form-check'
        }
    },
    formOptions: {
        getFormData:        getFormData
    },
    initAjaxOptions: {
        cache:              'no-store',
        credentials:        'same-origin',
        headers: {
                            'Content-Type': 'application/json',
                            'Accept':       'application/json'
        },
        method:             'GET',
        mode:               'same-origin',
        redirect:           'follow',
        timeout:            0
    },
    messages:{
        maxChoice:          'answers max',
        error:              'Answer is necessary.',
        errorMultiChoice:   'You must choose from {{checksMin}} to {{checksMax}} answers.'
    },
    showErrorMessage:       true,
    templates: {
        error:              // SEE TEMPLATES SECTION
        input:              // SEE TEMPLATES SECTION
        label:              // SEE TEMPLATES SECTION
        loading:            // SEE TEMPLATES SECTION
        select:             // SEE TEMPLATES SECTION
        textarea:           // SEE TEMPLATES SECTION
        wrapper: {
            field:          // SEE TEMPLATES SECTION
            nested:         // SEE TEMPLATES SECTION
            question:       // SEE TEMPLATES SECTION
            related:        // SEE TEMPLATES SECTION
        }
    },
    useWebStorage:          true
}

Methods

surveyJS inherits all formJS methods and has its own:

name

name, description & parameters

return value

destroy()

Lite

Description:

This method will:

Remove all events listeners from the form.
Remove the form instance attached to the form element ( by calling method destroy of formJS )
Lite Remove the survey instance attached to the form element

Prototype Methods

You can use these methods ONLY from the original Survey object ( not from a new instance ):

name, parameters

parameters

notes

setOptions( options )

Lite

Parameters:

options: JS object with the survey options to override ( see Options section )

Description:

This will affect ONLY new instances

Examples of usage:

Survey.setOptions( { showErrorMessage: false } );

Built-in Events

surveyJS inherits all formJS built-in events and has its own. By default all built-in events will bubble.

name, description

event detail object

sjs:destroy

Lite

Emitted after method destroy has been called.

sjs:init

Lite

Emitted when the survey is initialized ( on constructor call ).

event detail object

In this case, the Promise returned by the AJAX call ( to retrieve JSON data ) will be assigned to event.detail, to which will be passed the ajax response.

Templates

You can initialize the survey with your custom HTML templates ( all templates are also included in Lite version ).
NOTE: Use ALL the data-* attributes and placeholders with the curly braces, for example {{answerType}}, in your custom templates.
Below, the default templates:

Template error

For field error message container ( on failed field validation )

<div class="surveyjs-error-message">{{errorMessage}}</div>

Template input

For input fields

<input {{fieldAttributes}} name="surveyjs-answer-{{questionNumber}}{{addMoreName}}" class="surveyjs-input surveyjs-{{answerType}} {{fieldClasses}}" />

Template label

For label elements

<label for="{{answerCode}}" class="surveyjs-label {{labelClasses}}">{{labelString}}</label>

Template loading

For the loading box. Used when waiting survey data

<div class="surveyjs-loading" data-surveyjs-loading>Loading...</div>

Template select

For select fields

<select {{fieldAttributes}} name="surveyjs-answer-{{questionNumber}}{{addMoreName}}" class="surveyjs-select {{fieldClasses}}">
    {{optionsHtml}}
</select>

Template textarea

For textarea fields

<textarea {{fieldAttributes}} name="surveyjs-answer-{{questionNumber}}" class="surveyjs-textarea {{fieldClasses}}"></textarea>

Template wrapper.field

As wrapper for each field ( input, select, textarea )

<div class="surveyjs-field-wrapper surveyjs-{{answerType}}-wrapper {{wrapperClasses}}">
    {{fieldTemplate}}
    {{labelTemplate}}
</div>

Template wrapper.nested

As wrapper for nested fields ( see example in demos )

<div class="surveyjs-field-wrapper surveyjs-nested-wrapper">
    {{labelTemplate}}
    <div class="surveyjs-nested-inner">
        {{nestedFieldsHTML}}
    </div>
</div>

Template wrapper.question

As wrapper for each question.

Lite version does NOT include attribute data-formjs-question

<div class="surveyjs-question-wrapper" data-question-id="{{questionId}}" data-formjs-question>
    <div class="surveyjs-question-text">{{questionText}}</div>
    <div class="surveyjs-answers-wrapper">
        {{answersHTML}}
    </div>
    <div class="surveyjs-errors-wrapper" data-surveyjs-errors>{{errorTemplates}}</div>
</div>

Template wrapper.related

As wrapper for related fields ( see example in demos and Bootstrap Input Group )

<div class="surveyjs-field-wrapper surveyjs-related-wrapper input-group">
    <div class="input-group-prepend">
        <div class="surveyjs-radio-wrapper input-group-text form-check">
            {{fieldTemplate}}
            {{labelTemplate}}
        </div>
    </div>
    {{relatedFieldHTML}}
</div>