Form Styling#

Questions can include Media such as images, sound or video. Additionally, labels, hints, and choices in an XLSForm can all be styled using Markdown, fonts and colors, and Emoji.

Media#

You can include questions in your form that display images or that play video or audio files by including a media column in your XLSForm. Files referenced should be included in your form's media folder.

Images#

Adding an image to a question displays the image as part of the question.

A single select widget in Collect. The label text is "Do you want coffee?" The label text is accompanied by a picture of a mug of coffee. The options are "yes", "no", and "I don't know".

XLSForm

survey#

type

name

label

media::image

select_one yesnodk

coffee

Do you want coffee?

mug.jpg

choices#

list_name

name

label

yesnodk

y

yes

yesnodk

n

no

yesnodk

dk

I don't know

Audio#

Adding audio to a question adds a play/stop button that controls the audio clip.

A single text widget in Collect. The label text is "How does this song make you feel?" The label text is accompanied by a button to play audio.

XLSForm

survey#

type

name

label

media::audio

text

feel

How does this song make you feel?

amazing.mp3

Video#

Adding video to a question adds a button that will play the video clip full screen when clicked.

A single integer widget in Collect. The label text is "How many people do you see in the video?" The label text is accompanied by a button to play video.

XLSForm

survey#

type

name

label

media::video

integer

people

How many people do you see in the video?

people.mp4

Autoplaying Media#

Audio and video on questions can also be played automatically when a question is viewed by adding an autoplay column specifying either audio or video.

XLSForm

survey#

type

name

label

media::audio

autoplay

text

feel

How does this song make you feel?

amazing.mp3

audio

Some considerations for autoplaying:

  • Audio/video included in select choices will be autoplayed after the question's media in display order

  • If using a field-list appearance for a group no media will be autoplayed

  • Appearances for selects that hide buttons will disable autoplay for media

Markdown#

XLSForm supports limited used of Markdown.

Headers#

Labels and hints can be styled with one of six header levels.

# Header H1

## Header H2

### Header H3

#### Header H4

##### Header H5

###### Header H6

A comparison of headline sizes. This exact effect cannot be produced using Markdown.

A note widget in Collect. The label is six headlines of decreasing size, with text describing the size as: H1, H2, H3, H4, H5, H6.

Warning

If a Markdown header is used, the label or hint can only be one line of text. Line breaks in the XLSForm cell will break the header styling.

A note widget in Collect. The label text is "## Attempted h2 Label Header (line break) A line below the headline". The hint text is "### Attempted H3 hint headline (line break) Here is some text below the headline."

XLSForm

survey#

type

name

label

hint

note

broken_header

## Attempted H2 Label Header

A line below the headline
### Attempted H3 hint headline,

Here is some text below the headline.

Emphasis#

Collect's Markdown support also includes bold and italic styling.

_italic_

*italic*

__bold__

**bold**

Note

The label of a form widget is already bold, so bolding text within the label has no effect. Similarly, the hint text of a form widget is already in italics, so italicizing text within the hint has no effect.

A note widget in Collect. The label text is "This label has bold and italic text." The hint text is "This hint has bold and italic text." The words "bold" and "italic" are styled to appear bold and italic.

XLSForm

type

name

hint

label

note

emphasis

This label has bold and italic text.

This hint has bold and italic text.

Escaping Markdown#

If you want to include literal asterisks or underscores, escape them with a back-slash (\). If you want to include a literal back-slash, you'll need to escape that too.

XLSForm

type

name

label

hint

note

escape_md

\# This headline is normal sized

An asterisk: \* and an underscore: \_ and one slash: \\\

Inline HTML#

Many Markdown implementations support inline HTML, but Collect only supports a small subset of HTML elements. Support of HTML is further limited because:

  • Your exact Android device, operating system version, and other device-related factors will affect what HTML can be rendered, and how it is rendered.

  • HTML is not supported by other form rendering tools in the XForms ecosystem. For example, HTML elements that work in Collect may not work in Enketo.

For these reasons, we do not recommend using HTML in forms (except the <span> element noted below).

Fonts and colors#

To add custom styling to hint, label, and choice labels, use the style attribute on a span tag. The style attribute accepts CSS-like key-value pairs for setting color and font-family.

  • For color, try one of the named HTML color values or use a hex color.

  • For font-family, it is best to use generic font categories rather than specific fonts:

    • serif

    • sans-serif

    • monospace

    • cursive

    • fantasy

    This will ensure support across most devices. You can also use specific font choices, but you should test these on the actual devices being used.

A note widget in Collect. The label text is "Going red", and the word "red" is colored red. The hint text is the source markup for the label: Going <span style="color:red">red</span> A note widget in Collect. The label text is "Going green", and the word "green" is colored green. This hint text is the source markup for the label: Going <span style="color:#008000">green</span> A note widget in Collect. The label text is "Cursive text", style in a cursive font. The hint text is the source markup for the label: <span style="font-family:cursive">Cursive text</span> A single select widget in Collect. The label text is "Formatting works on labels for choices also." The choices are "Yes" (which is colored green) and "No" (which is colored red). A note widget in Collect. The label text is "Color and font styling can be combined." The label is large, purple, and in cursive.

XLSForm

type

name

label

note

red

Going <span style="color:red">red</span>

note

green

Going <span style="color:#008000">green</span>

note

cursive

<span style="font-family:cursive">Cursive text</span>

select_one yn

colored_choices

Formatting works on labels for Choices also.

note

combo

# <span style="font-family:cursive;color:purple">Color and font styling can be combined.</span>

choices#

list_name

name

label

yn

yes

<span style="color:green">Yes</span>

yn

no

<span style="color:red">No</span>

Text alignment#

To add alignment to hint, label, and choice labels, use the style attribute on a p or div tag.

../_images/text-alignment.png
survey#

type

name

label

hint

select_one options

select_question

<p style="text-align:center">Centered label</p>

<p style="text-align:center">Centered hint</p>

choices#

list_name

name

label

options

a

<p style="text-align:center">a</p>

options

a

<p style="text-align:center">b</p>

options

c

<p style="text-align:center">c</p>

Note

The style will be applied to the list of selected choices and that this might have unexpected results especially if used with a select_multiple question.

Emoji#

Emoji can be used in form labels, hints, and answer choices.

Note

The exact visual representation of each emoji character is controlled by the device operating system, and may vary from device to device. If possible, you should check how your rendered forms look on the devices you are using for data collection.

A single select widget in Collect. The label text is "What is your current pain level?" The options are seven increasingly-unhappy emoji faces.

XLSForm

survey#

type

name

label

select_one pain

pain_level

What is your current pain level?

choices#

list_name

name

label

pain

1

🙂

pain

2

😐

pain

3

🙁

pain

4

😦

pain

5

😧

pain

6

😩

pain

7

😱