Survey123WebForm

Class

Survey123 Web form class.

Inheritance: Survey123WebFormSurvey123JsApiCommon

Constructors

constructor

Class Constructor
new Survey123WebForm(): Survey123WebForm

Create a Survey123Webform instance.

For example:

Use dark colors for code blocksCopy
1
2
3
4
5
var webform = new Survey123WebForm({
  clientId: "ABC1234567890",
  container: "formDiv",
  itemId: "129132bbedcb490488a162aa996b12323"
}
Returns 
Survey123WebForm

Methods

Hide inherited methods
MethodReturnsNotes
addRepeat(options)
Promise<any>

Add repeat record. For example:

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.

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.

Form

Get survey form. Only available after onFormLoaded().

getItemId()
inherited
string

Get item id.

Promise<any[]>
getOptions(key?)
inherited
any

Get options.

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

void

Set OnFormFailed event. For example:

void

Set OnFormLoaded event. For example:

void

Set OnFormResized event. For example:

void

Set OnFormSubmit event. For example:

void

Set OnFormSubmitted event. For example:

void

Set onQuestionValidated event. For example:

void

Set onQuestionValueChanged event. For example:

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 Method
addRepeat(options{ count?: number[]; questionName: string; questionValues?: any[] }): Promise<any>

Add repeat record. For example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
ParameterType
options
{ count?: number[]; questionName: string; questionValues?: any[] }
Returns 
Promise<any>

associateMapDrawComplete

Class Method
associateMapDrawComplete(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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
webform.setEditAssociateMapComplated(
  {
     "rings": [
      [
        [86.06251716611514, 56.9269796817211],
        [109.68749999997128, 53.72920275233425],
        [100.68750858304249, 50.2682616540679],
        [82.68752574918487, 49.543728300312914],
        [86.06251716611514, 56.9269796817211]
      ]
     ]
   }
)
Parameters
ParameterType
options
OnAssociateMapDrawCompletedData
Returns 
void

associateMapDrawStart

Class Method
associateMapDrawStart(options?OnAssociateMapDrawStartedData): void
Parameters
ParameterType
options
OnAssociateMapDrawStartedData
Returns 
void

collapse

Class Method
collapse(namestring): void

Collapse group or repeat question.

Parameters
ParameterType
name
string
Returns 
void

copyFeature

Class Method
copyFeature(globalIdstring): void

Clone a new web form that is populated with the contents from an existing entry by the globalId.

Parameters
ParameterType
globalId
string
Returns 
void

deleteRepeat

Class Method
deleteRepeat(options{ indexes?: number[]; questionName: string }): Promise<any>

Delete repeat record. For example:

Use dark colors for code blocksCopy
1
2
3
4
webform.deleteRepeat({
questionName: "CapturedFish",
indexes: [1,2]
});
Parameters
ParameterType
options
{ indexes?: number[]; questionName: string }
Returns 
Promise<any>

expand

Class Method
expand(namestring): void

expand group or repeat

Parameters
ParameterType
name
string
Returns 
void

getContainer

inherited
Class Method
getContainer(): any

Get Container.

Returns 
any
Inherited from Survey123JsApiCommon.getContainer

getForm

Class Method
getForm(): Form

Get survey form. Only available after onFormLoaded().

Returns 
Form

getItemId

inherited
Class Method
getItemId(): string

Get item id.

Returns 
string
Inherited from Survey123JsApiCommon.getItemId

getLanguages

Class Method
getLanguages(): Promise<any[]>
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
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

inherited
Class Method
getOptions(key?string): any

Get options.

Parameters
ParameterType
key
string
Returns 
any
Inherited from Survey123JsApiCommon.getOptions

getPages

Class Method
getPages(): Promise<FormPagesInfo>

Get current pages.

Returns 
Promise<FormPagesInfo>

getQuestionValue

Class Method
getQuestionValue(): Promise<QuestionValue>

Get question value.

Returns 
Promise<QuestionValue>

getQuestions

Class Method
getQuestions(): any[]

Get questions in JSON format.

Returns 
any[]

getRepeatCount

Class Method
getRepeatCount(questionNamestring): Promise<number>

Get the count of records in a repeat question. For example:

Use dark colors for code blocksCopy
1
2
webform.getRepeatCount('CapturedFish')
})
Parameters
ParameterType
questionName
string
Returns 
Promise<number>

goToPage

Class Method
goToPage(pageIndexnumber): Promise<GoToPageResultInfo>

Navigated to specified page.

Parameters
ParameterType
pageIndex
number
Returns 
Promise<GoToPageResultInfo>

off

Class Method
off(eventNamestring, callbackEventFunction): void

Remove registered event.Supported with version ≥ 3.14

Parameters
ParameterType
eventName
string
callback
EventFunction
Returns 
void

on

Class Method
on(eventNamestring, callbackEventFunction): 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
ParameterType
eventName
string
callback
EventFunction
Returns 
void

scrollTo

Class Method
scrollTo(namestring): void

Scroll to a question.

Parameters
ParameterType
name
string
Returns 
void

setCredential

inherited
Class Method
setCredential(credentialany): void

Set credential.

Parameters
ParameterType
credential
any
Returns 
void
Inherited from Survey123JsApiCommon.setCredential

setGeometry

Class Method
setGeometry(geometryany): 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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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
ParameterType
geometry
any
Returns 
void

setGeopoint

Class Method
setGeopoint(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
ParameterType
geopoint
{ x: number; y: number }
Returns 
void

setItemId

inherited
Class Method
setItemId(itemIdstring): void

Set item id. IFrame will be reloaded.

Parameters
ParameterType
itemId
string
Returns 
void
Inherited from Survey123JsApiCommon.setItemId

setLanguage

Class Method
setLanguage(lanaugestring): void

Change the form language, only work for multilingual survey.

For example:

Use dark colors for code blocksCopy
1
 webform.setLanguage('ja');
Parameters
ParameterType
lanauge
string
Returns 
void

setMode

Class Method
setMode(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:

Use dark colors for code blocksCopy
1
2
3
4
webform.setMode({
      mode: 'view',
      globalId: '<globalId>'
   })
Parameters
ParameterType
options
{ globalId?: string; mode: string; objectId?: string }
Returns 
void

setOnFormFailed

Class Method
setOnFormFailed(fxOnFormFailed): void

Set OnFormFailed event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnFormFailed((data)=>{
 console.log('onFormFailed', data)
})
Parameters
ParameterType
fx
OnFormFailed
Returns 
void

setOnFormLoaded

Class Method
setOnFormLoaded(fxOnFormLoaded): void

Set OnFormLoaded event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnFormLoaded((data)=>{
 console.log('onFormLoaded', data)
})
Parameters
ParameterType
fx
OnFormLoaded
Returns 
void

setOnFormResized

Class Method
setOnFormResized(fxOnFormResized): void

Set OnFormResized event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnFormResized((data)=>{
 console.log('onFormResized', data)
})
Parameters
ParameterType
fx
OnFormResized
Returns 
void

setOnFormSubmit

Class Method
setOnFormSubmit(fx() => ""): void

Set OnFormSubmit event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnFormSubmit(()=>{
 console.log('onFormSubmit')
})
Parameters
ParameterType
fx
() => ""
Returns 
void

setOnFormSubmitted

Class Method
setOnFormSubmitted(fxOnFormSubmitted): void

Set OnFormSubmitted event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnFormSubmitted((data)=>{
 console.log('onFormSubmitted', data)
})
Parameters
ParameterType
fx
OnFormSubmitted
Returns 
void

setOnQuestionValidated

Class Method
setOnQuestionValidated(fxOnQuestionValidated): void

Set onQuestionValidated event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnQuestionValidated((data)=>{
 console.log('onQuestionValidated', data)
})
Parameters
ParameterType
fx
OnQuestionValidated
Returns 
void

setOnQuestionValueChanged

Class Method
setOnQuestionValueChanged(fxOnQuestionValueChanged): void

Set onQuestionValueChanged event. For example:

Use dark colors for code blocksCopy
1
2
3
webform.setOnQuestionValueChanged((data)=>{
 console.log('onQuestionValueChanged', data)
})
Parameters
ParameterType
fx
OnQuestionValueChanged
Returns 
void

setQuestionValue

Class Method
setQuestionValue(value{ [key: string]: any }): void

Dynamically set value on each question. To clear the question value, set it to null.

For example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
const imageObj = {
  name: 'avatar.jpg',
  file: file  // File object
};
const questionValue = {};
questionValue[questionName] = [imageObj];
webform.setQuestionValue(questionValue);
Parameters
ParameterType
value
{ [key: string]: any }
Returns 
void

setStyle

Class Method
setStyle(styleObjany): void

Set CSS style of any UI element using the JSS syntax.

For example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
 webform.setStyle({
  '& .question-label': {
    'color': '#ff0000 !important',
    'font-size': '30px !important'
   },
  '& .form-header': {
    'color': '#ff0000 !important'
   }
 });
Parameters
ParameterType
styleObj
any
Returns 
void

setTheme

Class Method
setTheme(themeFormTheme): void

Set form theme.

For example:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 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
ParameterType
theme
FormTheme
Returns 
void

submitForm

Class Method
submitForm(): void

Submit the survey based on the current question values.

Returns 
void

validateForm

Class Method
validateForm(): Promise<any>

validateForm

Returns 
Promise<any>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.