Building: Course preferences

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.

1. Syntax for preferences
2. Defining preferences
3. Using a learner's preferences

Syntax for preferences

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

Defining preferences

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 item in the preferences list depends on the type of preference. In this case, options represents the choices in a list of radio buttons.

The supported types include:

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 for 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.

Using a learner's preferences

This JSON object is added to the context class, so its available in the YAML system's template variables:

- type: gate
  left: '%preferences.gitTool%'
  operator: ===
  right: cli

Preferences can also be used in template responses:

{% if preferences.gitTool == 'cli' %}
  Here's how you pull from your terminal!
{% else %}
  Here's how you use GitHub Desktop!
{% endif %}