Courses are able to provide certain preferences to users when taking a course. For example, you might design a course teaching people how to use Git, and provide a choice to take the course from the terminal or from GitHub Desktop.
If you are planning to translate your course, refer to the translation instructions.
Preferences are defined in config.yml
.
preferences:
- type: radio
name: gitTool
label: Preferred Git tool
description: You can follow this course's instructions using whichever Git tool you prefer.
options:
- label: GitHub.com
value: dotcom
- label: Command line
value: cli
- label: GitHub Desktop
value: desktop
Let's unpack that for a second: type
is the kind of UI that will show up for learners when they register for a course. The rest of the items in the preferences list depend on the type
of preference. In this case of the example above, options
represents the choices in a list of radio buttons.
The supported type
s include checkbox
, radio
, and dropdown
:
checkbox
- type: checkbox
name: my_checkbox
label: My Single Checkbox
description: Optional description for more information
selected: true
A preference of type checkbox
renders as a single checkbox. Authors typically use a checkbox to represents a single boolean value (true/false, yes/no, on/off).
Its default value will be false
(unchecked), unless a preference-level selected
property is true
(checked).
radio
- type: radio
name: my_radio
label: My Radio Buttons
description: Optional description for more information
options:
- label: Option A
value: opt_a
- label: Option B
value: opt_b
selected: true
A preference of type radio
renders as a group of vertically aligned radio buttons.
Its default value will be the value
of the first item in options
, unless an option-level selected
property is true
on a different item.
It must contain at least 2 items in options
to be valid. Radio buttons can take up quite a bit of space on the UI, so we do not recommend using this preference type when there are many possible values (options
) to choose from.
Other than their UI rendering style, they are functionally equivalent to the dropdown
preference type.
dropdown
- type: dropdown
name: my_dropdown
label: My Dropdown List
description: Optional description for more information
options:
- label: Item 1
value: item1
- label: Item 2
value: item2
selected: true
A preference of type dropdown
renders as a collapsed dropdown list.
Its default value will be the value
of the first item in options
, unless an option-level selected
property is true
on a different item.
It must contain at least 2 items in options
to be valid. Dropdown lists are a great choice when there are many possible values (options
) to choose from as they do not take up much space on the UI.
Other than their UI rendering style, they are functionally equivalent to the radio
preference type.
This JSON object is added to the context
class, so it's available in the YAML system's template variables:
- type: gate
left: '{{ preferences.gitTool }}'
operator: ===
right: cli
You can also customize the bot responses to show different text based on the user's preferences:
{% if preferences.gitTool == 'cli' %}
Here's how you pull from your terminal!
{% else %}
Here's how you use GitHub Desktop!
{% endif %}