The appearance column in rtSurvey allows you to customize the visual presentation and behavior of questions in your surveys. This feature enhances user experience and can significantly improve data collection efficiency. rtSurvey supports standard XLSForm appearance attributes and extends them with additional options.

Standard XLSForm Appearance Attributes

rtSurvey supports the following standard XLSForm appearance attributes:

Appearance AttributeQuestion TypesDescription
multilinetextCreates a multi-line text box (best for web clients)
minimalselect_one, select_multipleDisplays choices in a dropdown menu
quickselect_oneAuto-advances to next question after selection (mobile only)
no-calendardateSuppresses the calendar display (mobile only)
month-yeardateAllows selection of month and year only
yeardateAllows selection of year only
horizontal-compactselect_one, select_multipleDisplays choices horizontally (web only)
horizontalselect_one, select_multipleDisplays choices horizontally in columns (web only)
likertselect_onePresents choices as a Likert scale
compactselect_one, select_multipleDisplays choices side by side with minimal padding
quickcompactselect_oneCombines compact display with auto-advance (mobile only)
field-listgroupsDisplays entire group on one screen (mobile only)
labelselect_one, select_multipleShows choice labels without inputs
list-nolabelselect_one, select_multipleShows inputs without labels (use with label)
table-listgroupsDisplays questions in a table format
signatureimageEnables signature capture (mobile only)
drawimageAllows freehand drawing (mobile only)
map, quick mapselect_one, select_one_from_fileEnables selection from map features

Best Practices for Using Appearance

  1. Consistency: Use appearance attributes consistently across your survey for a uniform look.
  2. Mobile vs. Web: Consider how appearances will render on different devices and platforms.
  3. Performance: Be cautious with appearance attributes that might slow down form loading (e.g., table-list for large groups).
  4. User Experience: Choose appearances that make data entry easier and more intuitive for respondents.
  5. Testing: Always test your form on target devices to ensure appearances work as expected.

Advanced Techniques

Combining Appearances

Some appearance attributes can be combined for more complex layouts:

  | type | name | label | appearance |
|------|------|-------|------------|
| select_one options | choice | Select one: | minimal compact |

Dynamic Appearances

rtSurvey allows for dynamic appearance changes based on form logic:

  | type | name | label | appearance | relevant |
|------|------|-------|------------|----------|
| text | time | Enter time: | inline-[%H:%M] | ${show_time} = 'yes' |

Mobile App Considerations

  • Some appearances (e.g., quick, signature) are specific to mobile devices.
  • Test thoroughly on both Android and iOS to ensure consistent behavior.

rtSurvey Extended Appearance Attributes

In addition to standard XLSForm appearances, rtSurvey supports the following platform-specific options:

Data and display control

Appearance AttributeQuestion TypesDescription
invisibleanyHides the field from view while still collecting or calculating its value. Different from hidden type — the field still participates in logic.
displaytitleanyForces display of the field’s label/title even when it would otherwise be suppressed.
autopullselect_one, select_multipleAutomatically fetches external data to populate choices when the form loads or a trigger field changes.
floating_hinttext, integer, decimalShows the hint text as a floating label above the input field rather than below it.
calculate-buttoncalculateAdds a visible button that triggers recalculation of the field on demand, rather than computing automatically.

Layout

Appearance AttributeQuestion TypesDescription
1screengroupForces the entire group to display on a single screen regardless of group size.
columns(n)select_one, select_multipleDisplays choices in n columns. Example: columns(3) shows three columns of radio buttons.
gridformat<row=R col=C colspan=S align=center>anyPositions the field in a CSS-grid layout at row R, column C, spanning S columns. Used with advanced-extension/grid-layout.
ignore-simplifyanyInstructs the form renderer to skip automatic simplification or condensing of this field’s layout.

Widgets

Appearance AttributeQuestion TypesDescription
likertselect_onePresents choices as a Likert scale row (already in standard table above; confirmed supported).
distressselect_oneRenders choices as the Kessler Psychological Distress Scale (K10) visual widget with emotional icons.

API integration

Appearance AttributeQuestion TypesDescription
callapitext, integer, decimal, select_oneEnables API call integration for this field. The calculation column should contain a callapi() expression. See Call API.
callapi-verify(params)text, integer, decimalTriggers an API verification call using static parameters. The form blocks progress until the API confirms the value.
callapi-verify(dynamicParams)text, integer, decimalSame as callapi-verify but with parameters derived from other field values at runtime.

Inline date/time format

For date, time, and datetime fields, you can specify a custom display format using a format string appended to the appearance:

  inline-[%d/%m/%Y]
inline-1line-[%d/%m/%Y %H:%M]

Format tokens are the same as format-date() and format-date-time(). See Functions — Date and time functions.

Example:

typenamelabelappearance
datetimeevent_timeEvent date and timeinline-[%d/%m/%Y %I:%M %p]
datebirth_dateDate of birthinline-[%d/%m/%Y]

Known Limitations

  • Complex appearances may not render identically across all platforms.
  • Some advanced rtSurvey appearances may not be supported in offline mode.

Troubleshooting Appearance Issues

  1. Appearance Not Applied: Check for typos in the appearance column.
  2. Inconsistent Rendering: Verify compatibility with the question type and platform.
  3. Performance Issues: Consider simplifying complex appearances, especially for large surveys.
Was this page helpful?