Class
Survey123 Web form class.
Constructors
constructor
Class Constructornew Survey123WebForm(): Survey123WebForm
Create a Survey123Webform instance.
For example:
var webform = new Survey123WebForm({
clientId: "ABC1234567890",
container: "formDiv",
itemId: "129132bbedcb490488a162aa996b12323"
}
Returns
Survey123WebForm
Methods
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. |
Promise<any[]> | ||
getOptions(key?) inherited | any | Get options. |
getPages() | Promise<FormPagesInfo> | Get current pages. |
Promise<QuestionValue> | Get question value. | |
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: |
void | Set OnFormSubmitted event. For example: | |
void | Set onQuestionValidated event. For example: | |
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. |
void | Submit the survey based on the current question values. | |
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): 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.
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
void
associateMapDrawStart
Class MethodassociateMapDrawStart(options?: OnAssociateMapDrawStartedData): void
Parameters
Parameter | Type |
---|---|
options | OnAssociateMapDrawStartedData |
Returns
void
collapse
Class Methodcollapse(name: string): void
Collapse group or repeat question.
Parameters
Parameter | Type |
---|---|
name | string |
Returns
void
copyFeature
Class MethodcopyFeature(globalId: string): void
Clone a new web form that is populated with the contents from an existing entry by the globalId.
Parameters
Parameter | Type |
---|---|
global | string |
Returns
void
deleteRepeat
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): void
expand group or repeat
Parameters
Parameter | Type |
---|---|
name | string |
Returns
void
getContainer
getContainer(): any
Get Container.
Returns
any
getItemId
getItemId(): string
Get item id.
Returns
string
getLanguages
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): any
Get options.
Parameters
Parameter | Type |
---|---|
key | string |
Returns
any
getPages
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): void
Remove registered event.Supported with version ≥ 3.14
Parameters
Parameter | Type |
---|---|
event | string |
callback | EventFunction |
Returns
void
on
Class Methodon(eventName: string, callback: EventFunction): void
Register 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
void
scrollTo
Class MethodscrollTo(name: string): void
Scroll to a question.
Parameters
Parameter | Type |
---|---|
name | string |
Returns
void
setCredential
setCredential(credential: any): void
Set credential.
Parameters
Parameter | Type |
---|---|
credential | any |
Returns
void
setGeometry
Class MethodsetGeometry(geometry: any): 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.
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
void
setGeopoint
Class MethodsetGeopoint(geopoint: { x: number; y: number }): 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.
Parameters
Parameter | Type |
---|---|
geopoint | { x: number; y: number } |
Returns
void
setItemId
setItemId(itemId: string): void
Set item id. IFrame will be reloaded.
Parameters
Parameter | Type |
---|---|
item | string |
Returns
void
setLanguage
Class MethodsetLanguage(lanauge: string): void
Change the form language, only work for multilingual survey.
For example:
webform.setLanguage('ja');
Parameters
Parameter | Type |
---|---|
lanauge | string |
Returns
void
setMode
Class MethodsetMode(options: { globalId?: string; mode: string; objectId?: string }): void
Sets 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
void
setOnFormFailed
Class MethodsetOnFormFailed(fx: OnFormFailed): void
Set OnFormFailed event. For example:
webform.setOnFormFailed((data)=>{
console.log('onFormFailed', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnFormFailed |
Returns
void
setOnFormLoaded
Class MethodsetOnFormLoaded(fx: OnFormLoaded): void
Set OnFormLoaded event. For example:
webform.setOnFormLoaded((data)=>{
console.log('onFormLoaded', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnFormLoaded |
Returns
void
setOnFormResized
Class MethodsetOnFormResized(fx: OnFormResized): void
Set OnFormResized event. For example:
webform.setOnFormResized((data)=>{
console.log('onFormResized', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnFormResized |
Returns
void
setOnFormSubmit
Class MethodsetOnFormSubmit(fx: () => ""): void
Set OnFormSubmit event. For example:
webform.setOnFormSubmit(()=>{
console.log('onFormSubmit')
})
Parameters
Parameter | Type |
---|---|
fx | () => "" |
Returns
void
setOnFormSubmitted
Class MethodsetOnFormSubmitted(fx: OnFormSubmitted): void
Set OnFormSubmitted event. For example:
webform.setOnFormSubmitted((data)=>{
console.log('onFormSubmitted', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnFormSubmitted |
Returns
void
setOnQuestionValidated
Class MethodsetOnQuestionValidated(fx: OnQuestionValidated): void
Set onQuestionValidated event. For example:
webform.setOnQuestionValidated((data)=>{
console.log('onQuestionValidated', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnQuestionValidated |
Returns
void
setOnQuestionValueChanged
Class MethodsetOnQuestionValueChanged(fx: OnQuestionValueChanged): void
Set onQuestionValueChanged event. For example:
webform.setOnQuestionValueChanged((data)=>{
console.log('onQuestionValueChanged', data)
})
Parameters
Parameter | Type |
---|---|
fx | OnQuestionValueChanged |
Returns
void
setQuestionValue
Class MethodsetQuestionValue(value: { [key: string]: any }): void
Dynamically 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
void
setStyle
Class MethodsetStyle(styleObj: any): void
Set 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
void
setTheme
Class MethodsetTheme(theme: FormTheme): void
Set 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