Class
Survey123 Web form class.
Constructors
constructor
Class Constructornew Survey123WebForm(): Survey123WebFormCreate a Survey123Webform instance.
For example:
var webform = new Survey123WebForm({
clientId: "ABC1234567890",
container: "formDiv",
itemId: "129132bbedcb490488a162aa996b12323"
}Returns
Survey123WebFormMethods
| Method | Returns | Notes |
|---|---|---|
addRepeat(options) | Promise<any> | Add repeat record. For example: |
associateMapDrawComplete(options?) | void | Mark the user has complate the editing for associcate map. Only works if there is Map question in the survey and the associateMap is enabled. Supported formats are either GeoJSON, Esri Geometry Object, or XLSForm Geotrace/Geoshape format. |
associateMapDrawStart(options?) | void | |
collapse(name) | void | Collapse group or repeat question. |
copyFeature(globalId) | void | Clone a new web form that is populated with the contents from an existing entry by the globalId. |
deleteRepeat(options) | Promise<any> | Delete repeat record. For example: |
expand(name) | void | expand group or repeat |
getContainer()inherited | any | Get Container. |
getForm() | Form | Get survey form. Only available after onFormLoaded(). |
getItemId()inherited | string | Get item id. |
getLanguages() | Promise<any[]> | |
getOptions(key?)inherited | any | Get options. |
getPages() | Promise<FormPagesInfo> | Get current pages. |
getQuestionValue() | Promise<QuestionValue> | Get question value. |
getQuestions() | any[] | Get questions in JSON format. |
getRepeatCount(questionName) | Promise<number> | Get the count of records in a repeat question. For example: |
goToPage(pageIndex) | Promise<GoToPageResultInfo> | Navigated to specified page. |
off(eventName, callback) | void | Remove registered event.Supported with version ≥ 3.14 |
on(eventName, callback) | void | Register event listener. Supported with version ≥ 3.14. Valid event names are: |
scrollTo(name) | void | Scroll to a question. |
setCredential(credential)inherited | void | Set credential. |
setGeometry(geometry) | void | Dynamically set geometry on Map question. Only works if there is Map question in the survey. Supported formats are either GeoJSON, Esri Geometry Object, or XLSForm Geotrace/Geoshape format. To clear the question value, set it to null. |
setGeopoint(geopoint) | void | Dynamically set coordinates on Geopoint question. Only works if there is Geopoint question in the survey. To clear the question value, set it to null. |
setItemId(itemId)inherited | void | Set item id. IFrame will be reloaded. |
setLanguage(lanauge) | void | Change the form language, only work for multilingual survey. |
setMode(options) | void | Sets the mode of the web form. Valid values are |
setOnFormFailed(fx) | void | Set OnFormFailed event. For example: |
setOnFormLoaded(fx) | void | Set OnFormLoaded event. For example: |
setOnFormResized(fx) | void | Set OnFormResized event. For example: |
setOnFormSubmit(fx) | void | Set OnFormSubmit event. For example: |
setOnFormSubmitted(fx) | void | Set OnFormSubmitted event. For example: |
setOnQuestionValidated(fx) | void | Set onQuestionValidated event. For example: |
setOnQuestionValueChanged(fx) | void | Set onQuestionValueChanged event. For example: |
setQuestionValue(value) | void | Dynamically set value on each question. To clear the question value, set it to null. |
setStyle(styleObj) | void | Set CSS style of any UI element using the JSS syntax. |
setTheme(theme) | void | Set form theme. |
submitForm() | void | Submit the survey based on the current question values. |
validateForm() | Promise<any> | validateForm |
addRepeat
Class MethodaddRepeat(options: { count?: number[]; questionName: string; questionValues?: any[] }): Promise<any>Add repeat record. For example:
webform.addRepeat({
questionName: "CapturedFish",
count: 2,
questionValues: [
{
Species: "Mooneye",
FishSize: 10,
condition: "good",
fishPosition: {
x: 151.123,
y: 13.123
}
},
{
Species: "Paddlefish",
FishSize: 20,
condition: "normal",
fishPosition: {
x: 101.123,
y: 29.123
}
}
]
});Parameters
| Parameter | Type |
|---|---|
options | { count?: number[]; questionName: string; questionValues?: any[] } |
Returns
Promise<any>associateMapDrawComplete
Class MethodassociateMapDrawComplete(options?: OnAssociateMapDrawCompletedData): voidMark the user has complate the editing for associcate map. Only works if there is Map question in the survey and the associateMap is enabled. Supported formats are either GeoJSON, Esri Geometry Object, or XLSForm Geotrace/Geoshape format.
For example:
webform.setEditAssociateMapComplated(
{
"rings": [
[
[86.06251716611514, 56.9269796817211],
[109.68749999997128, 53.72920275233425],
[100.68750858304249, 50.2682616540679],
[82.68752574918487, 49.543728300312914],
[86.06251716611514, 56.9269796817211]
]
]
}
)Parameters
| Parameter | Type |
|---|---|
options | OnAssociateMapDrawCompletedData |
Returns
voidassociateMapDrawStart
Class MethodassociateMapDrawStart(options?: OnAssociateMapDrawStartedData): voidParameters
| Parameter | Type |
|---|---|
options | OnAssociateMapDrawStartedData |
Returns
voidcollapse
Class Methodcollapse(name: string): voidCollapse group or repeat question.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
voidcopyFeature
Class MethodcopyFeature(globalId: string): voidClone a new web form that is populated with the contents from an existing entry by the globalId.
Parameters
| Parameter | Type |
|---|---|
global | string |
Returns
voiddeleteRepeat
Class MethoddeleteRepeat(options: { indexes?: number[]; questionName: string }): Promise<any>Delete repeat record. For example:
webform.deleteRepeat({
questionName: "CapturedFish",
indexes: [1,2]
});Parameters
| Parameter | Type |
|---|---|
options | { indexes?: number[]; questionName: string } |
Returns
Promise<any>expand
Class Methodexpand(name: string): voidexpand group or repeat
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
voidgetContainer
getContainer(): anyGet Container.
Returns
anygetItemId
getItemId(): stringGet item id.
Returns
stringgetLanguages
Class MethodgetLanguages(): Promise<any[]>getLanguages().then(languages => {
console.log(languages);
// Example response:
// [
// { code: "en-us", isDefault: true, label: "English" },
// { code: "eu", isCustomLocale: true, isActive: true, label: "Euskera" },
// { code: "ja", label: "Japanese" }
// ]
});Returns
Promise<any[]>A promise that resolves to an array of language objects. Each object contains language metadata such as the language code, display label, and optional properties indicating whether it's the default or a custom locale.
getOptions
getOptions(key?: string): anyGet options.
Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
anygetPages
Class MethodgetPages(): Promise<FormPagesInfo>Get current pages.
Returns
Promise<FormPagesInfo>getQuestionValue
Class MethodgetQuestionValue(): Promise<QuestionValue>Get question value.
Returns
Promise<QuestionValue>getRepeatCount
Class MethodgetRepeatCount(questionName: string): Promise<number>Get the count of records in a repeat question. For example:
webform.getRepeatCount('CapturedFish')
})Parameters
| Parameter | Type |
|---|---|
question | string |
Returns
Promise<number>goToPage
Class MethodgoToPage(pageIndex: number): Promise<GoToPageResultInfo>Navigated to specified page.
Parameters
| Parameter | Type |
|---|---|
page | number |
Returns
Promise<GoToPageResultInfo>off
Class Methodoff(eventName: string, callback: EventFunction): voidRemove registered event.Supported with version ≥ 3.14
Parameters
| Parameter | Type |
|---|---|
event | string |
callback | EventFunction |
Returns
voidon
Class Methodon(eventName: string, callback: EventFunction): voidRegister event listener. Supported with version ≥ 3.14. Valid event names are:
- formLoaded, which will be triggered when the form is fully loaded.
- formResized, which will be triggered when the form is resized.
- formSubmitted, which will be triggered when the response is submitted.
- questionValueChanged, which will be triggered when the question value is changed.
- repeatIndexChanged, which will be triggered when the active repeat record is changed.
- propertyChanged, which will be triggered when the locale or theme of the web app is changed.
Parameters
| Parameter | Type |
|---|---|
event | string |
callback | EventFunction |
Returns
voidscrollTo
Class MethodscrollTo(name: string): voidScroll to a question.
Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
voidsetCredential
setCredential(credential: any): voidSet credential.
Parameters
| Parameter | Type |
|---|---|
credential | any |
Returns
voidsetGeometry
Class MethodsetGeometry(geometry: any): voidDynamically set geometry on Map question. Only works if there is Map question in the survey. Supported formats are either GeoJSON, Esri Geometry Object, or XLSForm Geotrace/Geoshape format. To clear the question value, set it to null.
For example:
webform.setGeometry(
{
"rings": [
[
[86.06251716611514, 56.9269796817211],
[109.68749999997128, 53.72920275233425],
[100.68750858304249, 50.2682616540679],
[82.68752574918487, 49.543728300312914],
[86.06251716611514, 56.9269796817211]
]
]
}
)
webform.setGeometry(null)Parameters
| Parameter | Type |
|---|---|
geometry | any |
Returns
voidsetGeopoint
Class MethodsetGeopoint(geopoint: { x: number; y: number }): voidDynamically set coordinates on Geopoint question. Only works if there is Geopoint question in the survey. To clear the question value, set it to null.
Parameters
| Parameter | Type |
|---|---|
geopoint | { x: number; y: number } |
Returns
voidsetItemId
setItemId(itemId: string): voidSet item id. IFrame will be reloaded.
Parameters
| Parameter | Type |
|---|---|
item | string |
Returns
voidsetLanguage
Class MethodsetLanguage(lanauge: string): voidChange the form language, only work for multilingual survey.
For example:
webform.setLanguage('ja');Parameters
| Parameter | Type |
|---|---|
lanauge | string |
Returns
voidsetMode
Class MethodsetMode(options: { globalId?: string; mode: string; objectId?: string }): voidSets the mode of the web form. Valid values are
- edit, which sets the survey to edit an existing entry rather than create one, and
- view, which opens an existing entry in read-only mode, and
- copy, which will create a new web form that is populated with the contents from an existing entry.
When setting the mode, the globalId parameter (version ≥ 3.9) or objectId(version ≤ 3.9) parameter must also be provided.
For example:
webform.setMode({
mode: 'view',
globalId: '<globalId>'
})Parameters
| Parameter | Type |
|---|---|
options | { globalId?: string; mode: string; objectId?: string } |
Returns
voidsetOnFormFailed
Class MethodsetOnFormFailed(fx: OnFormFailed): voidSet OnFormFailed event. For example:
webform.setOnFormFailed((data)=>{
console.log('onFormFailed', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnFormFailed |
Returns
voidsetOnFormLoaded
Class MethodsetOnFormLoaded(fx: OnFormLoaded): voidSet OnFormLoaded event. For example:
webform.setOnFormLoaded((data)=>{
console.log('onFormLoaded', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnFormLoaded |
Returns
voidsetOnFormResized
Class MethodsetOnFormResized(fx: OnFormResized): voidSet OnFormResized event. For example:
webform.setOnFormResized((data)=>{
console.log('onFormResized', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnFormResized |
Returns
voidsetOnFormSubmit
Class MethodsetOnFormSubmit(fx: () => ""): voidSet OnFormSubmit event. For example:
webform.setOnFormSubmit(()=>{
console.log('onFormSubmit')
})Parameters
| Parameter | Type |
|---|---|
fx | () => "" |
Returns
voidsetOnFormSubmitted
Class MethodsetOnFormSubmitted(fx: OnFormSubmitted): voidSet OnFormSubmitted event. For example:
webform.setOnFormSubmitted((data)=>{
console.log('onFormSubmitted', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnFormSubmitted |
Returns
voidsetOnQuestionValidated
Class MethodsetOnQuestionValidated(fx: OnQuestionValidated): voidSet onQuestionValidated event. For example:
webform.setOnQuestionValidated((data)=>{
console.log('onQuestionValidated', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnQuestionValidated |
Returns
voidsetOnQuestionValueChanged
Class MethodsetOnQuestionValueChanged(fx: OnQuestionValueChanged): voidSet onQuestionValueChanged event. For example:
webform.setOnQuestionValueChanged((data)=>{
console.log('onQuestionValueChanged', data)
})Parameters
| Parameter | Type |
|---|---|
fx | OnQuestionValueChanged |
Returns
voidsetQuestionValue
Class MethodsetQuestionValue(value: { [key: string]: any }): voidDynamically set value on each question. To clear the question value, set it to null.
For example:
webform.setQuestionValue({
'ReportDate': '2020-07-11',
'Location': {
x: 129.1236,
y: 29.1236,
spatialReference: {
wkid: 4326
}
},
'HoursFished': 10,
'WaterbodyName': 'change by setDefatulValue()',
'Weather': 'rain',
// This is a repeat question
'CapturedFish': [{
'Species': 'Paddlefish',
'FishSize': 5,
'FishWeight': 10,
'condition': 'normal',
'fishPosition': {
x: 161.123,
y: 29.123
}
},{
'Species': 'Trout',
'FishSize': 7,
'FishWeight': 12,
'condition': 'poor',
'fishPosition': {
x: 169.123456,
y: 19.123456
}
}]
});If the question includes attachments, use the question name and file object to set its value:
const imageObj = {
name: 'avatar.jpg',
file: file // File object
};
const questionValue = {};
questionValue[questionName] = [imageObj];
webform.setQuestionValue(questionValue);Parameters
| Parameter | Type |
|---|---|
value | { [key: string]: any } |
Returns
voidsetStyle
Class MethodsetStyle(styleObj: any): voidSet CSS style of any UI element using the JSS syntax.
For example:
webform.setStyle({
'& .question-label': {
'color': '#ff0000 !important',
'font-size': '30px !important'
},
'& .form-header': {
'color': '#ff0000 !important'
}
});Parameters
| Parameter | Type |
|---|---|
style | any |
Returns
voidsetTheme
Class MethodsetTheme(theme: FormTheme): voidSet form theme.
For example:
webform.setTheme({
header: {
backgroundColor: "#25838f",
textColor: "#ffffff"
},
form: {
backgroundColor: "#143438",
backgroundOpacity: 1,
backgroundImage: "image url",
backgroundImageFit: "repeat | repeatY | fit | center",
textColor: "#ffffff",
primaryColor: "#25838f",
primaryTextColor: "#ffffff",
inputTextColor: "#505050",
inputBackgroundColor: "#ffffff"
},
webpage: {
backgroundColor: "#005d65",
backgroundImageFit: "fill | fit | repeat | center",
backgroundImage: "image url"
}
});Parameters
| Parameter | Type |
|---|---|
theme | FormTheme |
Returns
void