surveyJS
Get Started
Dependencies
surveyJS is developed with these dependencies:
- formJS ( version 5.2.0 or higher - for survey form validation and submit - NOT for Lite version )
- Bootstrap 4 CSS ( Optional - only form CSS ) but you can write the CSS by yourself ;)
Install
Include these scripts in your page:
<script src="https://unpkg.com/formjs-plugin@5"></script>
<script src="https://unpkg.com/surveyjs@4"></script>
<script src="https://cdn.jsdelivr.net/gh/simplysayhi/formJS@5/dist/formjs.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/simplysayhi/surveyJS@4/dist/surveyjs.min.js"></script>
or Install via NPM and import as ES Module:
npm install formjs-plugin@5 surveyjs
import Survey from 'surveyjs';
In folder dist
( and via CDNs ) are also available these versions:
- ES Module
- SystemJS
-
Lite - in folder
dist/lite
HTML
Basic HTML structure to initialize the survey.
Questions & answers will be put inside element with attribute data-surveyjs-body
.
<div class="surveyjs-wrapper" data-surveyjs-wrapper>
<form action="page.jsp" name="surveyjs-form" class="surveyjs-form" data-surveyjs-form novalidate>
<div class="surveyjs-body" data-surveyjs-body></div>
<div class="surveyjs-footer">
<button type="submit">SEND</button>
</div>
</form>
</div>
Mandatory attributes:
-
data-surveyjs-*
attributes -
action
the page where to send the users answers ( with the AJAX call ) - NOT for Lite version
CSS classes ( like .surveyjs-*
) are optional but used to give styles to the demos.
To add one ( or more ) external questions ( for example privacy acceptance ) you can set a question object as shown in the JSON ( see question with external: true
):
<div class="surveyjs-question-wrapper" data-formjs-question data-surveyjs-external="1">
<div class="surveyjs-answers-wrapper">
<div data-question></div>
<div data-answer>
<input name="surveyjs-answer-external" data-exclude-storage data-field/>
<label>
<span data-label></span>
</label>
</div>
<div data-answer>
<input name="surveyjs-answer-external" data-exclude-storage data-field/>
<label>
<span data-label></span>
</label>
</div>
</div>
</div>
Include a bit of HTML code ( see above ), keeping in mind that:
-
It must be a child of element with attribute
data-surveyjs-wrapper
( see demos ) -
Attribute
data-surveyjs-external
must have an integer number as value ( see example above ). The number is equal to the item position of the external question ( considering only external questions ) -
Attribute
data-exclude-storage
is optional ( used to avoid saving the answer in session storage ) - NOT for Lite version
JSON File
Example of JSON file for the survey is here.
During initialization, the survey will fetch data from url passed in options.url
.
The survey will be built if status
is "success" and array questions
has items.
{
"status": "success",
"data": {
"id": 1,
"questions": [
{
"id": "1",
"question": "What's your name?",
"answers": [ { "id": "1", "type": "text", "data": { "subtype": "alphabeticExtended" } } ]
},
{
"id": "1c",
"question": "What's your email address?",
"answers": [
{ "id": "1ca", "type": "email", "placeholder": "address@email.ext" }
],
"errorMessage": "We need your email in case you win :)",
"required": true
},
{
"id": "8",
"question": "What do you like about this survey?",
"answers": [
{ "id": "43", "value": "value-43", "type": "checkbox", "label": "Clear of communication", "sort": 1 },
{ "id": "44", "value": "value-44", "type": "checkbox", "label": "Simplicity of usage", "sort": 2 },
{ "id": "45", "value": "value-45", "type": "checkbox", "label": "Graphic style and language", "sort": 3 },
{ "id": "46", "value": "value-46", "type": "checkbox", "label": "Duration", "sort": 4 }
],
"checks": "[1,2]",
"required": true
}
]
}
}
JSON file is pretty self explanatory but here you can find a reference for less clear items.
For each question, each answer in answers
will be used to build the HTML field.
All keys of the object will generate the equivalent HTML attribute ( except for data
id
label
nested
related
sort
) with the specified value ( in case answer type
is equal to "option" or "textarea", also these keys will be ignored for this purpose: type
value
).
All keys in data
will generate the equivalent data-attribute data-*
.
In particular, you can use them to enable formJS superpowers ( see JSON file and formJS API for details ), for example:
-
subtype
to specify a custom validation method -
validateIfFilled
to validate a field only if filled
HTML attribute id
is automatically generated like:
`${answerType}-${surveyId}-${questionId}-${answerId}`
where:
-
answerType
same astype
( if "option", it will be "select" ) -
surveyId
the id of the survey. Seedata.id
-
questionId
the id of the question -
answerId
the answer id ( or answer index in caseanswerType => 'select'
)
In case you need, answers can also be "nested" or "related":
-
nested
when some answers are "grouped" as child ( see key "nested" in JSON file ) -
related
when an answer, if selected, requires an additional answer ( tipically a radio and an input field - see key "related" in JSON file )
You can use these keys on each question object:
-
checks
( string ) to enable formJS mutliple-checks validation ( see formJS doc ) -
errorMessage
( string | object ) the error message that will be shown to the user if answered is given. It can also be an object to show detailed error messages based on validation rule ( formJS doc ) -
required
( boolean ) if the user must give an answer ( if omitted, it will be considered asfalse
) -
sort
( number ) used to set the order of the questions ( it's also available in answers )
Initialize
const $form = document.querySelector('[data-surveyjs-form]');
const options = { url: 'json/survey.json' };
const mySurvey = new Survey( $form, options );
You must specify at least options.url
to retrieve the JSON data and build the survey.
-
$form
( required ) must be a single form node ( not a nodelist! ) or a CSS string selectorconst $form = '.my-container .my-form';
-
options
( required ) a JS object as defined in Options section with at leasturl
You can also access to:
-
Survey version: via
Survey.prototype.version
or$form.surveyjs.version
-
Survey instance: once the instance is created, via
$form.surveyjs
-
Survey initialization: boolean via
$form.surveyjs.isInitialized
-
Survey data: the survey data structure returned from the AJAX call. Accessible via
$form.surveyjs.data