XLSForm.

org

WhatisanXLSForm?
Basicformat
Thesurveyworksheet
Thechoices
worksheet
Questiontypes
GPS
GPSwith
accuracyThreshold
Multiplechoice
questions
Specifyother
Metadata
Hints
Constraints
Constraintmessage
Relevant
Formulas
Calculation
Required
Requiredmessage
Groupingquestions
Nestinggroupswithin
groups
Skipping
Repeats
Multiplelanguagesupport
Media
PreloadingCSVdata
Howtopulldatafrom
CSV
Dynamicselectsfrompre
loadeddata
Cascadingselects
Externalselects
Default
Readonly
Appearance

XLSFormReferenceTable

Styling
Settingsworksheet
Encryptedforms
Specifyform
submissionname
Multiplewebpage
forms
Gridthemeforms
Platforms/Toolsthat
supportXLSForms
Moreresources
Aboutthissite
History

WhatisanXLSForm?
XLSFormisaformstandardcreatedtohelpsimplifytheauthoringof
formsinExcel.Authoringisdoneinahumanreadableformatusinga
familiartoolthatalmosteveryoneknowsExcel.XLSFormsprovidea
practicalstandardforsharingandcollaboratingonauthoringforms.
Theyaresimpletogetstartedwithbutallowfortheauthoringof
complexformsbysomeonefamiliarwiththesyntaxdescribedbelow.
TheXLSFormisthenconvertedtoanXForm,apopularopenform
standard,thatallowsyoutoauthoraformwithcomplexfunctionalitylike
skiplogicinaconsistentwayacrossanumberofwebandmobiledata
collectionplatforms.XLSFormsarecompatiblewiththesubsetof
XFormfunctionalitysupportedbyJavarosaProject.XLSFormsare
supportedbyanumberofpopulardatacollectionplatforms.

Basicformat
EachExcelworkbookusuallyhastwoworksheets:surveyand
choices.Athirdoptionalworksheetcalledsettingscanaddadditional
specificationstoyourformandisdescribedbelow.
Thesurveyworksheet
Thisworksheetgivesyourformitsoverallstructureandcontainsmost
ofthecontentoftheform.Itcontainsthefulllistofquestionsand
informationabouthowtheyshouldappearintheform.Eachrowusually
representsonequestionhowever,therearecertainotherfeatures
describedbelowthatyoucanaddtotheformtoimprovetheuser
experience.
Thechoicesworksheet

Thechoicesworksheet
Thisworksheetisusedtospecifytheanswerchoicesformultiple
choicequestions.Eachrowrepresentsananswerchoice.Answer
choiceswiththesamelistnameareconsideredpartofarelatedsetof
choicesandwillappeartogetherforaquestion.Thisalsoallowsasetof
choicestobereusedformultiplequestions(forexample,yes/no
questions).

Bothoftheseworksheetshaveasetofmandatorycolumnsthatmust
bepresentfortheformtowork.Additionally,eachworksheethasaset
ofoptionalcolumnsthatallowfurthercontroloverthebehaviorofeach
entryintheform,butarenotessentialtohave.Everyentrymusthave
valuesforeachofthemandatorycolumns,buttheoptionalcolumns
maybeleftblank.
Thesurveyworksheethas3mandatorycolumns:type,name,and
label.
Thetypecolumnspecifiesthetypeofentryyouareadding.
Thenamecolumnspecifiestheuniquevariablenameforthat
entry.Notwoentriescanhavethesamename.
Thelabelcolumncontainstheactualtextyouseeintheform.
Alternatively,labeltranslationcolumnscanbeused.

Thechoicesworksheethas3mandatorycolumnsaswell:list
name,name,andlabel.
Thelistnamecolumnletsyougrouptogetherasetofrelated
answerchoices,i.e.,answerchoicesthatshouldappeartogether
underaquestion.
Thenamecolumnspecifiestheuniquevariablenameforthat
answerchoice.
Thelabelcolumnshowstheanswerchoiceexactlyasyouwant
ittoappearontheform.Alternatively,labeltranslationcolumns

canbeused.

ThecolumnsyouaddtoyourExcelworkbook,whethertheyare
mandatoryoroptional,mayappearinanyorder.Optionalcolumnsmay
beleftoutcompletely.Anynumberofrowsmaybeleftblank.All.xlsfile
formattingisignored,soyoucanusedividinglines,shading,andother
fontformattingtomaketheformmorereadable.
OnethingtokeepinmindwhenauthoringformsinExcelisthatthe
syntaxyouusemustbeprecise.Forexample,ifyouwriteChoicesor
choiceinsteadofchoices,theformwontwork.

Questiontypes
XLSFormsupportsanumberofquestiontypes.Thesearejustsomeof
theoptionsyoucanenterinthetypecolumninthesurveyworksheetin
yourXLSForm:
Question
type

Answerinput

integer

Integer(i.e.,wholenumber)input.

decimal

Decimalinput.

text

Freetextresponse.

select_one
[options]

Multiplechoicequestiononlyoneanswercanbeselected.

select_multiple
[options]

Multiplechoicequestionmultipleanswerscanbeselected.

note

Displayanoteonthescreen,takesnoinput.

geopoint

CollectasingleGPScoordinates.

geotrace

RecordalineoftwoormoreGPScoordinates.

geoshape

RecordapolygonofmultipleGPScoordinatesthelastpointisthesame
asthefirstpoint.

date

Dateinput.

time

Timeinput.

dateTime

Acceptsadateandatimeinput.

image

Takeapicture.

audio

Takeanaudiorecording.

video

Takeavideorecording.

barcode

Scanabarcode,requiresthebarcodescannerapptobeinstalled.

calculate

PerformacalculationseetheCalculationsectionbelow.

acknowledge

AcknowledgepromptthatsetsvaluetoOKifselected.

GPS

GPS
Forexample,tocollectthenameandGPScoordinatesofastore,you
wouldwritethefollowing:
survey

type

name

label

text

store_name

Whatisthenameofthisstore?

geopoint

store_gps

CollecttheGPScoordinatesofthisstore.

Seethequestion_typesXLSFormforalookateachquestiontypebeing
usedinaform.
GPSwithaccuracyThreshold
WhenrecordingGPScoordinatesinODKCollect,ODKcollect
automaticallycollectsthegpswhenanaccuracylevelof5metersor
lessisreached.Youcanchangethisdefaultbehaviourbyspecifyingan
accuracyThresholdthiscouldbelessthan5mormorethan5m.You
willneedtoaddacolumnwithheadingbody::accuracyThresholdon
thesurveysheetofyourXLSForm.Thenspecifyyourpreferred
accuracythresholdvalueforthiscolumnonyourgeopointquestion,as
intheexampleshownbelow:
survey

type

name

label

body::accuracyThreshold

geopoint

store_gps

CollecttheGPScoordinates
ofthisstore.

1.5

Seegps_accuracy_thresholdformforanexamplethatusesthis
attribute.
Multiplechoicequestions
XLSFormsupportsbothselect_one(selectonlyoneanswer)and
select_multiple(selectmultipleanswers)questions.Writingamultiple
choicequestionrequiresaddingachoicesworksheettoyourExcel
workbook.Hereisanexampleofaselect_onequestion:
survey

type

name

label

select_oneyes_no

likes_pizza

Doyoulikepizza?

choices

listname

name

label

yes_no

yes

Yes

yes_no

no

No

Notethattheyes_nointhesurveyworksheetmustmatchtheyes_no
inthelistnamecolumninthechoicesworksheet.Thisensuresthat
theformdisplaysthecorrectlistofanswerchoicesforaparticular
question.
Wecanalsoaddmultiplechoicequestionsthatallowmultipleanswers
tobeselected,likeso:
survey

type

name

label

select_multiple
pizza_toppings

favorite_toppings

Whatareyourfavoritepizza
toppings?

choices

listname

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

Specifyother
Formultiplechoicequestions,surveysoftenincludeanoptionof
markingotherwhentheiranswerchoiceisnotlisted.Thentheyare
usuallyaskedtospecifytheotheroption.Thisispossiblethrough
XLSFormbyincludingor_otheraftertheanswerchoicelistnameinthe
surveyworksheet.Thechoicesworksheetstaysthesame.Seebelow:
survey

type

name

label

select_multiplepizza_toppings
or_other

favorite_topping

Whatareyourfavorite
pizzatoppings?

choices

listname

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

Clickonthelinktolookatthecompletepizza_questionnaire.
Caveat
Whenyouexportdatausingthisor_otheroption,inthe
favorite_toppingcolumn,youwillseeavalueother.Aseparate
columnwillhavetheanswerforthequestionsinwhichtheuser
selectedother.Thismakesdataanalysismorecumbersome,sowedo
notrecommendtheor_otherconstructforlargescaledatacollection
efforts.SeetheRelevantsectionbelowforanalternativemethodmore
appropriateforlargescaleprojects.
Metadata

XLSFormhasanumberofdatatypeoptionsavailableformetadata
collection:
Metadatatype

Meaning

start

Startdateandtimeofthesurvey.

end

Enddateandtimeofthesurvey.

today

Dayofthesurvey.

deviceid

IMEI(InternationalMobileEquipmentIdentity)

subscriberid

IMSI(InternationalMobileSubscriberIdentity)

simserial

SIMserialnumber.

phonenumber

Phonenumber(ifavailable).

Notethatsomemetadatafieldsonlyapplyformobilephonebased
forms.
IfIwantedmysurveytocollectallofthesemetadata,Iwouldputthe
followingatthebeginningofthesurvey:
survey

type

name

label

start

start

end

end

today

today

deviceid

deviceid

subscriberid

subscriberid

simserial

simserial

phonenumber

phonenumber

Noticethattherearenolabelsassociatedwiththemetadataquestion
types.Thisisbecausethephonecapturesthesevariables
automatically.Thesequestionswillnotappearonthescreenofthe
phone,butyouwillseethemwhenviewingyoursubmittedsurveydata.
TheTutorialXLSFormshowshowmetadataisusedinaform.

Hints
Sometimesyouwanttoaddasmallhinttoaquestiononyourform,
instructingtheuserhowtoanswerthequestion,butyoudontwantthe
hinttobepartofthequestionitself.Itseasytoaddhintstoquestionsin
XLSForms.Simplyaddahintcolumnandaddyourhintmessage.See
belowforanexample.
survey

type

name

label

hint

text

name

Whatisthenameofthis
store?

Lookonthesignboardifthe
storehasasignboard.

survey

geopoint

geopoint

CollecttheGPS
coordinatesofthisstore.

TheTutorialXLSFormprovidesmoreexamplesofquestionswithhints.

Constraints
Onewaytoensuredataqualityistoaddconstraintstothedatafieldsin
yourform.Forexample,whenaskingforapersonsage,youwantto
avoidimpossibleanswers,like22or200.Addingdataconstraintsin
yourformiseasytodo.Yousimplyaddanewcolumn,called
constraint,andtypeintheformulaspecifyingthelimitsontheanswer.
Intheexamplebelow,theanswerforthepersonsagemustbeless
thanorequalto150.Notehowthe.intheformularefersbacktothe
questionvariable.
survey

type

name

label

constraint

integer

age

Howoldareyou?

.<=150

Inthisexample,theformula.<=150issayingthatthevalueentered
.forthequestionmustbelessthanorequalto150.Iftheuserputs151
oraboveastheanswer,s/hewillnotbeallowedtomoveontothenext
questionorsubmittheform.
Otherusefulexpressionstouseintheconstraintcolumncanbefound
here.LookundertheOperatorssection.
Constraintmessage
Ifyouwanttoincludeamessagewithyourconstraint,tellingtheuser
whytheanswerisnotaccepted,youcanaddaconstraint_message
columntoyourform.Seetheexamplebelow.
survey

type

name

label

constraint

constraint_message

integer

respondent_age

Respondents
age

.>=18

Respondentmustbe
18oroldertocomplete
thesurvey.

Inthisexample,iftheuserentersanagelessthan18,thentheerror
messageintheconstraint_messagecolumnappears.Moreexamples
onconstraintshavebeenillustratedinthisXLSForm.

Relevant

Relevant
OnegreatfeatureofXLSFormistheabilitytoskipaquestionormake
anadditionalquestionappearbasedontheresponsetoaprevious
question.Belowisanexampleofhowtodothisbyaddingarelevant
columnforaselect_onequestion,usingourpizzatoppingexample
frombefore:
survey

type

name

label

relevant

select_oneyes_no

likes_pizza

Doyoulike
pizza?

select_multiplepizza_toppings
or_other

favorite_topping

Favorite
toppings

${likes_pizza}
=yes

Inthisexample,therespondentisasked,Doyoulikepizza?Ifthe
answerisyes,thenthepizzatoppingquestionappearsbelow.Notethe
${}aroundthevariablelikes_pizza.Thesearerequiredinorderfor
theformtoreferencethevariablefromthepreviousquestion.
Inthenextexample,below,weuserelevantsyntaxfora
select_multiplequestion,whichisslightlydifferentfromtheselect_one
questionexampleabove.
survey

type

name

label

relevant

select_one
yes_no

likes_pizza

Doyoulike
pizza?

select_multiple
pizza_toppings
or_other

favorite_topping

Favorite
toppings

${likes_pizza}=yes

selected(${favorite_topping},
cheese)

text

favorite_cheese

Whatis
your
favorite
typeof
cheese?

choices

listname

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

Sincethepizzatoppingquestionallowsmultipleresponses,wehaveto
usetheselected(${favorite_topping},'cheese')expression,
becausewewantthecheesequestiontoappeareverytimetheuser
selectscheeseasoneoftheanswers(regardlessofwhetheradditional
answersareselected).
Earlierwementionedtherewasanalternativemethodforspecifying
otherformultiplechoicequestionswhichismoreappropriateforlarge

scalesurveys.Thiscanbedoneusingthesamerelevantsyntaxfrom
theexampleabove:
survey

type

name

label

relevant

select_multiple
pizza_toppings

favorite_toppings

Whatare
your
favorite
pizza
toppings?

text

favorite_toppings_other

Specify
other:

selected(${favorite_toppings},
other)

choices

listname

name

label

pizza_toppings

cheese

Cheese

pizza_toppings

pepperoni

Pepperoni

pizza_toppings

sausage

Sausage

pizza_toppings

other

Other

Notethatyoumustincludeotherasananswerchoiceinthechoices
worksheet.

Formulas
Formulasareusedintheconstraint,relevantandcalculationcolumns.
YouvealreadyseensomeexamplesintheandConstraintand
Relevantsectionsabove.Formulasallowyoutoaddadditional
functionalityanddataqualitymeasurestoyourforms.Formulasare
composedoffunctionsandoperators(+,*,div,etc.).Thefulllistofthese
canbefoundhere.

Calculation
Yoursurveycanperformcalculationsusingthevaluesofpreceding
questions.Inmostcasesthiswillrequireinsertingacalculatequestion.
Forexample,inthesurveybelow,wehavecalculatedthetipforameal
anddisplayedittotheuser:
survey

type

name

label

calculation

decimal

amount

Whatwasthepriceofthemeal?

calculate

tip

${amount}*0.18

note

display

18%tipforyourmealis:${tip}

Notethatthe${tip}inthelastlinewillbereplacedwiththeactualtip
amountwhenviewingandfillingouttheform.

Required

Required
Itssimpletomarkcertainquestionsasrequiredinyourform.Marking
themasrequiredmeanstheuserwillnotbeabletomoveontothenext
questionorsubmittheformwithoutenteringananswerforthatquestion.
Tomakequestionsrequired,addarequiredcolumntoyoursurvey
worksheet.Underthatcolumn,markquestionsasrequiredbywriting
yes.Seetheexamplebelow:
survey

type

name

label

constraint

required

integer

age

Howoldareyou?

.<=150

yes

Requiredmessage
Ifyouwanttocustomizethemessagedisplayedtouserswhenthey
leavearequiredquestionblank,youcanaddarequired_message
columntoyourform.Seetheexamplebelow.
survey

type

name

label

required

required_message

integer

respondent_age

Respondents
age

yes

Sorry,thisansweris
required.

Groupingquestions
Tocreateagroupofquestionsinyourformtrythefollowing:
survey

type

name

label

begingroup

respondent

Respondent

text

name

Entertherespondentsname

text

position

Entertherespondentspositionwithintheschool.

endgroup

Thisisagoodwaytogrouprelatedquestionsfordataexportand
analysis.Noticehowendgroupdoesntrequireanameorlabel,
becauseitishiddenintheform.
Nestinggroupswithingroups
Groupsofquestionscanbenestedwithinoneanother:
survey

type

name

label

begingroup

hospital

Hospital

text

name

Whatisthenameofthishospital?

begingroup

hiv_medication

HIVMedication

select_one
yes_no

have_hiv_medication

DoesthishospitalhaveHIV
medication?

endgroup

endgroup

Youalwayshavetoendthemostrecentgroupthatwascreatedfirst.
Forinstance,thefirstendgroupyouseeclosestheHIVmedication
group,andthesecondoneclosesthebeginninghospitalgroup.When
workingwithgroupsandyoukeepgettingerrormessageswhentrying
touploadyourform,doublecheckthatforeachbegingroupyouhave
oneendgroup.
Skipping
OneneatfeatureofXLSFormistheabilitytoskipagroupofquestions
bycombiningthegroupfeaturewithrelevantsyntax.Ifyouwanttoskip
agroupofquestionsallatonce,puttherelevantattributeatthe
beginningofagrouplikefollows:

type

name

label

relevant

integer

age

Howoldareyou?

begingroup

child

Child

${age}<=5

integer

muac

Recordthischildsmidupperarmcircumference.

select_oneyes_no

mrdt

Isthechildsrapiddiagnostictestpositive?

endgroup

Inthisexample,thetwochildgroupquestions(muacandmrdt)will
onlyappearifthechildsagefromthefirstquestionislessthanorequal
tofive.

Repeats
Ausercanrepeatagroupofquestionsbyusingthebeginrepeatand
endrepeatconstruct:
survey

type

name

label

beginrepeat

child_repeat

text

name

Childsname

decimal

birthweight

Childsbirthweight

select_onemale_female

sex

Childssex

endrepeat

choices

listname

name

label

survey

male_female

male

Male

male_female

female

Female

Inthisexample,thename,birthweight,andsexfieldsaregrouped
togetherinarepeatgroup,andtheusercanrepeatthisgroupasmany
timesasrequiredbyselectingtheoptionintheformtostartanother
repeat.
Thelabelcolumnisoptionalforbeginrepeat.Assigningalabeltoa
repeatgroupwilladdthelabelasatitletotheblockofrepeatquestions
intheform.
TheDeliveryOutcomeXLSFormillustratesanotherrepeatgroup
example.
Insteadofallowinganinfinitenumberofrepeats,theusercanspecify
anexactnumberofrepeatsbyusingtherepeat_countcolumn:
survey

type

name

label

repeat_count

beginrepeat

child_repeat

text

name

Childsname

decimal

birthweight

Childsbirthweight

select_onemale_female

sex

Childssex

endrepeat

choices

listname

name

label

male_female

male

Male

male_female

female

Female

Intheaboveexample,therepeatgroupisrestrictedto3repeats.
Someplatformsalsosupportdynamicrepeatcounts.Intheexample
below,thenumberthattheuserinputsforthenum_hh_membersfield
dictatesthenumberoftimesthehh_membergrouprepeats:
survey

type

name

label

repeat_count

integer

num_hh_members

Numberof
household
members?

beginrepeat

hh_member

${num_hh_members}

text

name

Name

integer

age

Age

select_one
male_female

gender

Gender

endrepeat

choices

listname

name

label

male_female

male

Male

survey

male_female

female

Female

Multiplelanguagesupport
Itseasytoaddmultiplelanguagestoaform.Yousimplyhavetoname
yourlabel::language1,label::language2,etc.,andyourformswillbe
availableinmultiplelanguages.Seetheexamplebelow.Toselecta
differentlanguageonthephone,presstheMenukey,andtheChange
Languageoption.Fortheformbelow,EnglishandEspaolwillshowup
asthepossibleoptions.
survey

type

name

label::English

label::Espaol

constraint

integer

age

Howoldareyou?

Cuntosaostienes?

.<=150

Note
Youcanalsoaddadifferentlanguagecolumnforhintsandmediafiles
yousimplyusethe::languageconstructagain.SeetheXLSForm
standarddocumenttoseeexactlywhatkindsofcolumnheaderscan
acceptalanguagemodification.

Media
Youcanincludequestionsinyourformthatdisplayimagesorthatplay
videooraudiofiles.IfusingtheODKmobileclientforformsubmission,
youneedtoputthemediafilesthatyouwanttoincludeinthe
/odk/forms/formnamemediafolderonyourphone,andthenreference
theexactfilenameinthemediacolumninyourform.Seebelowforan
exampleofhowtodothis.
survey

type

name

label

media::image

media::video

note

media_example

Mediaexample

example.jpg

example.mp4

CheckouttheBirdsXLSFormwhichillustratestheuseofmediafiles.
YoucanalsoclickonthelinktoseetheBirdswebform.

PreloadingCSVdata
Preloadingdataisdonewhenonewantstoreferencepreexistingdata
inasurveyform.Youcanbeabletoreferencedatainyoursurveyform
(thesurveyyouarenowauthoring),fromapreexistingdataina

specificsurveyformoranyothersource.Forexampleifyouhavepre
existingdatafromahouseholdsurveyandyouwanttocollectfollowup
dataaboutthehouseholdoccupants.Youcanbeabletoreferencethe
householdsurveydatainyoursurveyform.Toreferencepreexisting
datainasurveyform:
Uploadoneormore.csvfilesassupportfileswhenyouuploadyour
formdefinition(thesamewayyouuploadmediasupportfilesas
explainedintheMediasection).Thefirstrowofeach.csvfileshould
beaheaderthatincludesshort:
uniquenamesforeachcolumn
subsequentrowswhichshouldcontainthedataitself
Eachcsvfileshouldcontainatleastonecolumnthatcanbeusedto
uniquelyidentifyeachrow.Suchcolumnswillbeused,atsurveytime,
tolookupwhichrowsdatatopullintothesurvey.Forthecolumnsthat
willbeusedforlookinguprowsadd_keytotheendofthecolumnname
inthefirstrow.Anycolumnswithnamesendingin_keywillbeindexed
forfasterlookupsonyoursurveydevices.Seebelowanexampleof
thecolumnsona.csvfile:
name_key

name

mango

Mango

orange

Orange

HowtopulldatafromCSV
Youcanbeabletopulldatafrom.csvfilebyincludingoneormore.csv
filesinyourformduringthesurveytime.Foreachdatafieldthatyou
wanttopullintoyoursurvey:
Addacalculatefieldtoyoursurvey.
Givethatfieldaname
Theninitscalculationcolumn,callthepulldata()function,indicating
whichfieldtopullfromwhichrowofwhich.csvfile.
Seebelowforanexample:
survey

type

name

label

calculation

calculate

fruit

pulldata(fruits,name,
name_key,mango)

note

note_fruit

Thefruit${fruit}pulled
fromcsv.

Onceyouhaveloaded.csvdataintoasurveyfieldusingthepulldata()
function,youcanreferencethatfieldinlaterrelevanceconditions,

constraints,andlabels,justasyouwouldreferenceanyotherfieldthat
wasfilledinbytheuser.
Clickonthelinktoseeanexampleofapreloadingsampleformandthe
.csvfileusedwithformcanbefoundhere
Importantnotesonusageofpreloadeddata
Compressalarge.csvfileintoa.ziparchivebeforeuploadingit.
Save.csvfileinUTF8formatifpreloadeddatacontainsnon
EnglishfontsorspecialcharactersthisenablesyourAndroiddevice
torenderthetextcorrectly.
Datafieldspulledfroma.csvfileareconsideredtobetextstrings
thereforeusetheint()ornumber()functionstoconvertapreloaded
fieldintonumericform.
Ifthe.csvfilecontainssensitivedatathatyoumaynotwantto
uploadtotheserver,uploadablank.csvfileaspartofyourform,
thenreplaceitwiththereal.csvfilebyhandcopyingthefileonto
eachofyourdevices.

Dynamicselectsfrompreloadeddata
Onceyourformhasoneormorepreloaded.csvfiles,youcan
dynamicallypullthechoicelistsforselect_oneandselect_multiple
fieldsfromthose.csvfiles.Multiplechoicefieldswithdynamicchoice
listsfollowthesamegeneralsyntaxasregular,staticselect_oneand
select_multiplefieldsaspreviouslycoveredintheMultiplechoice
questionssection.
Thefollowingshouldbedone:
specifyselect_onelistnameorselect_multiplelistnameinthe
typecolumn(wherelistnameisthenameofyourchoicelist)
specifyanyspecialappearancestylesintheappearancecolumn
includeoneormorerowsforyourlistnameonthechoices
worksheet.
Belowisanexampleofthesurveyworksheet:
survey

type

name

label

appearance

select_onefruits

fruits

Selectafruit

search(fruits)

Therearethreedifferenceswhenthechoicelistshouldbepulledfrom
oneofyourpreloaded.csvfiles:
Intheappearancecolumn:

Includeasearch()expressionthatspecifieswhich.csvrowsto
includeinthechoicelist.
Ifthefieldshoulduseanondefaultappearancestyle.Thenon
defaultappearancestylegoesintothecolumnfirst,followedbya
space,thenthesearch()expression.[e.g.,quicksearch()]
Onthechoicesworksheet:
arowshouldindicatewhich.csvcolumnstouseforthelabeland
selectedvalue.Asfollows:
list_namecolumn:specifythenameofyourchoicelistasyou
normallywould.
namecolumn:includethenameofthe.csvcolumntousefor
uniquelyidentifyingselectedchoices.
labelcolumn:includethenameofthe.csvcolumntousefor
labelingthechoices.
Note:
Ifyouwishtoincludemultiplecolumnsinthelabels,includea
commaseparatedlistofallcolumnstoinclude.Thenamecolumn
willbedynamicallypopulatedbasedonthecolumnnameyouput
there,andthelabelcolumnwillbedynamicallypopulatedbased
onthecolumnname(s)youputthere.
Inyourchoicesworksheetrow,youmayalsoincludea.csvcolumn
nameintheimagecolumn.Ifyoudo,theimagefilenametousewill
bepulledfromthespecified.csvcolumn.
Note:
Ifyourefertoimagefilesinthisway,youmustalwaysuploadthose
imagefilesasmediafileattachmentswhenyouuploadyourformto
theserver.
Seebelowanexampleofthechoicesworksheet:
choices

listname

name

label

fruits

name_key

name

Clickonthelinktoseeanexampleofasearchandselectsampleform
andthe.csvfileusedwithformcanbefoundhere.
Thereareaseriesofoptionstoindicatewhich.csvrowstoincludein
thechoicelistusingthesearch()expression,seethispostfor
additionalinformationonthesesearch()expressions.

Cascadingselects
Alotofformsstartoutbyaskingthelocationoftherespondent,with
eachlocationselectionspecifyingwhatthesubsequentlocationchoices
willbe(e.g.,statedistrictvillage).Insteadofaddingaselect_one
fieldforeachlocationoption,youcanusecascadeselect.Inorderto
usecascadeselects,youwillneedtocreateachoice_filtercolumnin

yoursurveyworksheetandaddthelocationattributecolumnsinyour
choicesworksheet.CheckoutanexampleXLSFormhere.

Externalselects
Ifaformhasselectswithalargenumberofchoices(e.g.,hundredsor
thousands),thatformcanslowdownformloadingandnavigationin
clientslikeODKCollect.Thebestworkaroundtothisissueistouse
externalselects.
Enablingexternalselectsisstraightforward.Insteadofselect_onefor
theprompttype,useselect_one_external.Insteadofthechoices
sheet,putexternalchoicesintheexternal_choicessheet.
Seeselect_one_externalformforanexamplethatusesnormaland
externalchoices.
WhenanXLSFormwithexternalchoicesisconvertedtoanXForm,two
fileswillbeproduced,theXForm(e.g.,formfilename.xml)withallthe
normalchoices,andanitemsets.csvwiththeexternalchoices.
Theitemsets.csvfilecanbeuploadedtoanyODKcompatibleserver
(e.g.,ODKAggregate)asamediafile.Itwillbedownloadedtoany
ODKcompatible(e.g.,ODKCollect)likeanyothermediafileandsaved
tothe[formfilename]mediafolder.ClientslikeODKCollectloadmedia
filesfromtheSDcardandsoyourformwithalargenumberofchoices
willnowloadveryquickly.

Default
Addingadefaultfieldmeansthataquestionwillbeprepopulatedwith
ananswerwhentheuserfirstseesthequestion.Thiscanhelpsave
timeiftheanswerisonethatiscommonlyselectedoritcanserveto
showtheuserwhattypeofanswerchoiceisexpected.Seethetwo
examplesbelow.
survey

type

name

label

default

today

today

date

survey_date

Surveydate?

20100615

Inthenextexample,theweightisautomaticallysetto51.3kg.Youcan
simplychangetheanswerbytappingintheanswerfieldandinputting
anotheranswer.

survey

type

name

label

default

decimal

weight

Respondentsweight?(inkgs)

51.3

Readonly
Addingareadonlyfieldmeansthataquestioncannotbeedited.Read
onlyfieldscanbecombinedwithdefaultfieldstodeliverinformation
backtoauser.
survey

type

name

label

read_only

default

integer

num

Pleasepatientis:

yes

Appearance
Theappearancecolumnallowsyoutochangetheappearanceof
questionsinyourform.Thefollowingtableliststhepossibleappearance
attributesandhowthequestionappearsintheform.
Appearance
attribute

Question
type

Description

multiline

text

Bestifusedwithwebclients,makesthetextbox
multiplelineslong.

minimal

select_one,
select_multiple

Answerchoicesappearinapulldownmenu.

quick

select_one

Relevantformobileclientsonly,thisattributeauto
advancestheformtothenextquestionafterananswer
isselected.

nocalendar

date

Formobiledevicesonly,usedtosuppressthe
calendar.

monthyear

date

Selectamonthandyearonlyforthedate.

year

date

Selectonlyayearforthedate.

horizontal
compact

select_one,
select_multiple

Forwebclientsonly,thisdisplaystheanswerchoices
horizontally.

horizontal

select_one,
select_multiple

Forwebclientsonly,thisdisplaystheanswerchoices
horizontally,butincolumns.

likert

select_one

Bestifusedwithwebclients,makestheanswer
choicesappearasaLikertscale.

compact

select_one,
select_multiple
[choiceswith
images]

Arrangesimageanswerchoicessidebyside.

quickcompact

select_one
[choiceswith
images]

Sameasprevious,butthisoneautoadvancestothe
nextquestion(inmobileclientsonly).

fieldlist

groups

Entiregroupofquestionsappearononescreen(for
mobileclientsonly).

label

select_one,
select_multiple

Displaysanswerchoicelabels(andnotinputs).

Appearance
attribute

Question
type

Description

listnolabel

select_one,
select_multiple

Usedinconjunctionwithlabelattributeabove,displays
theanswerinputswithoutthelabels(makesuretoput
labelandlistnolabelfieldsinsideagroupwithfield
listattributeifusingmobileclient).

tablelist

groups

Aneasierwaytoachievethesameappearanceas
above,applythisattributetotheentiregroupof
questions(mightslowdowntheformabit).

signature

image

Allowsyoutotraceyoursignatureintoyourform
(mobileclientsonly).

draw

image

Allowsyoutosketchadrawingwithyourfingeronthe
mobiledevicescreen.

AnXLSFormwithalloftheappearanceattributesinthistableis
availablehere.

Settingsworksheet
Thesettingsworksheetisoptional,butitallowsyoutofurther
customizeyourform,includingencryptingyourformorsettingan
overallstylethemetoyourform,amongothers.
Anexamplesettingsworksheetisbelow:
settings

form_title

Example
Title

form_id
example_id

public_key

submission_url

default_language

IIBIjANBg

https://exampleodk
aggregate.appspot.com/submission

English

Thecolumnheadingsinthisexamplesettingsworksheetdothe
following:
form_title:Thetitleoftheformthatisshowntousers.Theformtitle
ispulledfromform_idifform_titleisblankormissing.
form_id:Thenameusedtoidentifytheformsubmission.Theformid
ispulledfromtheXLSfilenameifform_idisblankormissing.
public_key:Forencryptedforms,thisiswherethepublickeyis
copiedandpasted.
submission_url:Forencryptedforms,thisurlspecifiestheserver
wherefinalizedformsaresubmittedto.
default_language:Inlocalizedforms,thissetswhichlanguage
shouldbeusedasthedefault.
Encryptedforms
Encryptedformsprovideamechanismtokeepyourdataprivateusing
httpforcommunication.FormsubmissionssenttotheAggregateserver

areencryptedandcompletelyinaccessibletoanyonenotpossessing
theprivatekey.
ToencryptXLSforms,addtheform_id,submission_urlandthe
public_keyascolumnheadersinthesettingsworksheet.
Theydothefollowing:
form_idnameusedtoidentifytheform
submission_urlisyoursubmissionurl
public_keyisthebase64RsaPublicKey
Formoreinformationonencryptedformsandhowtogeneratethersa
keyshavealookatthetutorialhere.Pleasehavealookatthe
tutorial_encryptedXLSFormexample.
Specifyformsubmissionname
Inthesettingsworksheet,youcanspecifyauniquenameforeach
formsubmissionusingfieldsfilledinbytheuserduringthesurvey.On
thesettingsworksheet,addacolumncalledinstance_name.Writein
theexpressionthatdefinestheuniqueforminstancenameusingfields
fromthesurveyworksheet.
CheckoutthisexampleXLSFormthatcalculatestheinstancenameas
theuserslastandfirstnamescoupledwiththeformsubmissionuuid.
Multiplewebpageforms
Webformscanbesplitintomultiplepagesusingthestylethemepages.
Anexampleofaformdividedintomultiplepagescanbeseenonthe
WidgetsonPageswebform.
Inthesettingstab,createacolumncalledstyleandsetittopages,as
follows:
settings

form_title

form_id

style

exampletitle

example_id

pages

Inyoursurveytab,grouptogetherthequestionsyouwouldliketo
appearoneachpageandthensettheappearanceforthegroupto
fieldlist.Seetheexamplebelow.
survey

type

name

label

appearance

survey

begingroup

group1

fieldlist

text

name

Respondentsname

integer

age

Respondentsage

string

address

Respondentsaddress

endgroup

Seethisblogpostformoreinformationoncreatingmultipageweb
forms.TheXLSFormsourceishere.
Gridthemeforms
Thethemegridstyleallowsyourformtomimicthelookoftraditional
papersurveysbycompactingmultiplequestionsintoonerow.This
styleisbestusedwithlargerscreens(e.g.,computersortablets).It
alsomakesaniceprintout!
PleaseclickonthelinktoseeanexampleofaGridthemewebform.
TocreateaGridform,inthesettingstab,underthestylecolumn,write
themegrid,asfollows:
settings

form_title

form_id

style

exampletitle

example_id

themegrid

Inyoursurveytab,grouptogetherthequestionsyouwouldliketo
appearineachsectionandthensettheappearanceforeachfield
accordingtothedesiredwidth(thedefaultwidthis4).Seetheexample
below.
survey

type

name

label

appearance

begingroup

group1

text

name

Respondentsname

w3

integer

age

Respondentsage

w1

string

address

Respondentsaddress

w4

endgroup

SeethisblogpostformoreinformationoncreatingGridforms.TheGrid
themeXLSFormexampleishere.

Stylingprompts
MarkdownsupportinXLSFormallowsforincreasedemphasisthrough
boldanditalics,differentsizedheaders,variousfontsandcolors,and

clickableweblinksinODKCollect1.4.9andEnketo.
emphasizewordsbywrappingtheminside_or*
stronglyemphasizewordsbywrappingtheminside__or**
addalinkbyusing[nameoflink](url)
addvarioussizedheadersbyprepending#(biggest)to######
(smallest)toheadertext
styletextforcolororfontwithspantags(e.g.,<span
style=color:#f58a1f>orange<span>,<spanstyle=color:redfont
family:cursive>red and cursive<span>)
styletextforcolororfontwithspantags(e.g.,<span
style="color:#f58a1f">orange</span>,<span
style="color:red;fontfamily:cursive">red and
cursive</span>)
addalinebreakwhereyouwantitwithCtrlEnterorCtrlAltEnter
(maybedifferentkeycombinationforsomespreadsheetsoftware)
addyourfavoriteemojis!

Platforms/ToolsthatsupportXLSForms
OpenDataKit(ODK)
Formhub
Ona
SurveyCTO
Enketo
KoboToolBox
CommCare
NafundisXLSFormOffline
NathanBreitsxlsform.exe
DataWinners

Moreresources
TheXLSformstandarddocumentcanguideyouthroughthespecific
inputtypes,columnheaders,andsoonthatarelegitimatesyntaxin
XLSForms.IfyouwanttodigindeepertounderstandXFormsandgo
beyondXLSForms,herearesomeresourcestounderstandthem:
Formguidelines:
http://code.google.com/p/opendatakit/wiki/XFormDesignGuidelines
Formdesigntutorial:
https://bitbucket.org/javarosa/javarosa/wiki/buildxforms
Sampleforms:
http://code.google.com/p/opendatakit/source/browse/?repo=forms
FormhubUniversity
OnaFormGallery

XFormsassupportedbyJavaRosa:
https://bitbucket.org/javarosa/javarosa/wiki/xformjrcompat

Aboutthissite
XLSForm.orgisacommunitysupportedprojectaimingtocreatea
commonreferencepointfortheXLSFormstandard.
Ifyouwanttocontributetoorimprovethisdocumentation,pleasevisit
ourprojectsGitHubrepo.

History
TheXLSFormwasoriginallydevelopedbyAndrewMarderandAlex
DoreyoftheSustainableEngineeringLabatColumbiaUniversity.As
XLSFormsbecameadoptedbytheODKCommunity,SELworkedwith
theODKTeamattheUniversityofWashingtontodevelopthecurrent
specification.PyXForm,thelibraryusedtoconvertXLSFormsto
XForms,isanopensourceprojectsupportedbymembersofODK,
SEL,Ona,SurveyCTO,andKobo.

XLSForm.org
XLSForm.org
info@xlsform.org

ThissitewillhelpyouauthorXLSForms.
XLSFormisatoolusedtosimplifythecreation
offorms.XLSFormwillconvertformsauthored
inExcelintoXFormsthatcanbeusedwitha
numberofwebormobileplatforms.