DAISY Online Delivery Protocol - Dynamic Menus Primer

1. Introduction

This document contains examples of how to use the Dynamic Menus feature of the DAISY Online Delivery Protocol. This document is not a normative part of the DAISY Online Delivery Protocol, and may change at any time outside the scope of the revision cycle of the DAISY Online Delivery Protocol specification.

There are examples of menu design and User interaction, along with the specific messages passed between the Reading System and the Service.

2. The Main Menu

The Reading System retrieves the main menu of the Service by calling the getQuestions operation as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="default" />
  </userResponses>
</getQuestions>

The operation returns the Service's main menu:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q1">
    <label xml:lang="en">
      <text>What would you like to do?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Search the library</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Update your profile</text>
        </label>
      </choice>
      <choice id="c3">
        <label xml:lang="en">
          <text>Take a survey</text>
        </label>
      </choice>
      <choice id="c4">
        <label xml:lang="en">
          <text>Buy a book</text>
        </label>
      </choice>
      <choice id="c5">
        <label xml:lang="en">
          <text>Go to your bookshelf</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this menu to the User in the following way:

What would you like to do?

Search the library

Update your profile

Take a survey

Buy a book

Go to your bookshelf

Each userResponse element contains the user's response to a particular question. There are three reserved question IDs:

default: the main menu;
search: the search menu;
back: the previous question.

A question can be a multiple choice question (see multipleChoiceQuestion), or a question that can receive a numeric text, alphanumeric text or audio response from the user (see inputQuestion).

To respond to a multipleChoiceQuestion in a userResponse:

the questionID attribute is set to the value of the multipleChoiceQuestion's id attribute;
the value attribute is set to the value of the id of the choice the User has selected.

To respond to an inputQuestion in a userResponse:

the questionID attribute is set to the value of the inputQuestion's id attribute;
if the response is numeric or alphanumeric, the value attribute is set to the text the User has entered;
if the response is in an audio format, the value attribute must be either blank or absent, and a data child element must be included that holds the base-64 encoded audio data (see data for file format requirements).

Question and choice IDs are arbitrary.

3. Search

The search question ID is reserved for requesting the Service's search menu.

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="search" />
  </userResponses>
</getQuestions>

In the example Service, the search menu can also be selected from the main menu:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q1" value="c1" />
  </userResponses>
</getQuestions>

Both methods can be used. Reading Systems can have a "Search" button that jumps straight to the search menu, regardless of where it is in the menus, if the Service supports the search ID.

The operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q2">
    <label xml:lang="en">
      <text>What would you like to search by?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Title</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Author</text>
        </label>
      </choice>
      <choice id="c3">
        <label xml:lang="en">
          <text>Genre</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this to the User as follows:

What would you like to search by?

Title

Author

Genre

If the User selects "Author," the Reading System would retrieve the next menu by calling getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q2" value="c2" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <inputQuestion id="q2-1">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Please enter the name of the author.</text>
    </label>
  </inputQuestion>
</questions>

The Reading System renders this to the User as follows:

Please enter the name of the author.

If the User enters the name "J.K. Rowling," the Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q2-1" value="J.K. Rowling" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <contentListRef>L100</contentListRef>
</questions>

The Reading System reads the ID of the contentList from the contentListRef element, and calls the getContentList operation:

<getContentList xmlns="http://www.daisy.org/ns/daisy-online/">
  <id>L100</id>
  <firstItem>0</firstItem>
  <lastItem>20</lastItem>
</getContentList>

This requests the contentList with ID "L100", and specifies that the first contentItem returned should be at index 0 and the last contentItem should be at index 20 (i.e. the first 21 contentItems). The firstItem and lastItem parameters enable the Reading System to request a contentList with a specified number of contentItems, in situations where memory or bandwidth constraints may not permit the retrieval of an entire contentList.

The operation returns the following contentList:

<contentList xmlns="http://www.daisy.org/ns/daisy-online/"
             id="L100" firstItem="0" lastItem="2" totalItems="3">
  <label xml:lang="en">
    <text>Your Search for "J.K. Rowling" returned the following
    results.</text>
  </label>
  <contentItem id="hp_cos" lastModifiedDate="2009-08-20T11:00:00Z">
    <label xml:lang="en">
      <text>Harry Potter and the Chamber of Secrets</text>
    </label>
  </contentItem>
  <contentItem id="hp_dh" lastModifiedDate="2009-08-22T08:00:00Z">
    <label xml:lang="en">
      <text>Harry Potter and the Deathly Hallows</text>
    </label>
  </contentItem>
  <contentItem id="hp_gof" lastModifiedDate="2009-08-04T14:30:00Z">
    <label xml:lang="en">
      <text>Harry Potter and the Goblet of Fire</text>
    </label>
  </contentItem>
</contentList>

The Reading System renders it as follows:

Your search for "J.K. Rowling" returned the following results:

Harry Potter and the Chamber of Secrets

Harry Potter and the Deathly Hallows

Harry Potter and the Goblet of Fire

When a Service returns a questions element with a contentListRef child, the Reading System is at an endpoint of the Service's dynamic menus. The Reading System gets the ID of the contentList from the contentListRef element as illustrated above, and calls getContentList to retrieve it.

The Reading System may retrieve information about the specific contentItems in the contentList by calling the getContentMetadata operation, passing the ID of the particular Content item. At this stage, the Reading System may ask the User whether he or she wishes to download or stream the Content. If the User wishes to do so, the Reading System calls the issueContent operation passing the ID of the Content item, then calls the getContentResources operation, to request issuance and retrieve the URIs of the Content's resources, respectively.

4. Updating the User Profile

The User selects the "Update your profile" option from the main menu. The Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q1" value="c2" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <inputQuestion id="q3-1">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Your name:</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q3-2">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Your address:</text>
    </label>
  </inputQuestion>
  <multipleChoiceQuestion id="q3-3">
    <label xml:lang="en">
      <text>Your gender:</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Male</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Female</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this as follows:

Your name:

Your address:

Your gender:

Male

Female

After the User responds to the questions, the Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q3-1" value="Margaret Asterales" />
    <userResponse questionID="q3-2"
                  value="Grubenstrasse 12, 8045 Zurich, Switzerland" />
    <userResponse questionID="q3-3" value="c2" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <label xml:lang="en">
    <text>Your profile has been updated successfully!</text>
  </label>
</questions>

The Reading System renders this as follows:

Your profile has been updated successfully!

If the Service returns a questions element with a label child element, the Reading System is at an endpoint of the Service's dynamic menus.

The Service could offer to take the User back to a previous menu by returning a multipleChoiceQuestion within the questions as follows:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q3-4">
    <label xml:lang="en">
      <text>Your profile has been updated successfully! What would
      you like to do next?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Reenter your profile information</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Go back to the previous menu</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this as follows:

Your profile has been updated successfully! What would you like to do next?

Reenter your profile information

Go back to the previous menu

5. Taking a Survey (with audio responses)

The User selects the "Take a survey" option from the main menu. The Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q1" value="c3" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <inputQuestion id="q4-1">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>What is your favorite feature in the Service?</text>
    </label>
  </inputQuestion>
  <multipleChoiceQuestion id="q4-2">
    <label xml:lang="en">
      <text>On a scale of one to four, where four is very satisfied
      and 1 is not satisfied, how would you rate the
      Service?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>1</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>2</text>
        </label>
      </choice>
      <choice id="c3">
        <label xml:lang="en">
          <text>3</text>
        </label>
      </choice>
      <choice id="c4">
        <label xml:lang="en">
          <text>4</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
  <inputQuestion id="q4-3">
    <inputTypes>
      <input type="AUDIO" />
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Please provide feedback on the Service.</text>
    </label>
  </inputQuestion>
</questions>

The Reading System renders this as follows:

What is your favorite feature in the Service?

On a scale of one to four, where four is very satisfied and 1 is not satisfied, how would you rate the Service?

1

2

3

4

Please provide feedback on the Service.

After the User responds to the questions, the Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q4-1" value="Searching for books." />
    <userResponse questionID="q4-2" value="c3" />
    <userResponse questionID="q4-3">
      <data>
        <!-- base64 binary data -->
      </data>
    </userResponse>
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q4-4">
    <label xml:lang="en">
      <text>Thank you for taking the Survey. What would you like to
      do next?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Take another survey</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Go back to the previous menu</text>
        </label>
      </choice>
      <choice id="default">
        <label xml:lang="en">
          <text>Go back to the main menu</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this as follows:

Thank you for taking the survey! What would you like to do next?

Take another survey

Go back to the previous menu

Go back to the main menu

6. Content Purchase

The User selects the "Buy a book" option from the main menu. The Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q1" value="c4" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q5" allowMultipleSelections="true">
    <label xml:lang="en">
      <text>Which of the following book(s) would you like to
      buy?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Harry Potter and the Chamber of Secrets</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Harry Potter and the Deathly Hallows</text>
        </label>
      </choice>
      <choice id="c3">
        <label xml:lang="en">
          <text>Harry Potter and the Goblet of Fire</text>
        </label>
      </choice>
      <choice id="c4">
        <label xml:lang="en">
          <text>Harry Potter and the Half-Blood Prince</text>
        </label>
      </choice>
      <choice id="c5">
        <label xml:lang="en">
          <text>Harry Potter and the Order of the Phoenix</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading System renders this as follows:

Which of the following book(s) would you like to buy?

Harry Potter and the Chamber of Secrets

Harry Potter and the Deathly Hallows

Harry Potter and the Goblet of Fire

Harry Potter and the Half-Blood Prince

Harry Potter and the Order of the Phoenix

The allowMultipleSelections attribute of the multipleChoiceQuestion element tells the Reading System whether a User is allowed to select multiple answers from the list of choices.

To select multiple answers at once, a Reading System can put multiple userResponse child elements in a userResponses parameter, as illustrated below. Here, the User selects choices 2, 3 and 5.

The Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q5" value="c2" />
    <userResponse questionID="q5" value="c3" />
    <userResponse questionID="q5" value="c5" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <multipleChoiceQuestion id="q5-1">
    <label xml:lang="en">
      <text>Thank you for purchasing "Harry Potter and the Deathly
      Hallows", "Harry Potter and the Goblet of Fire" and "Harry
      Potter and the Order of the Phoenix". These books have been
      billed to your credit card. What would you like to do
      next?</text>
    </label>
    <choices>
      <choice id="c1">
        <label xml:lang="en">
          <text>Buy more books</text>
        </label>
      </choice>
      <choice id="c2">
        <label xml:lang="en">
          <text>Add these books to my bookshelf</text>
        </label>
      </choice>
      <choice id="c3">
        <label xml:lang="en">
          <text>Read these books now</text>
        </label>
      </choice>
    </choices>
  </multipleChoiceQuestion>
</questions>

The Reading system renders this as follows:

Thank you for purchasing "Harry Potter and the Deathly Hallows", "Harry Potter and the Goblet of Fire" and "Harry Potter and the Order of the Phoenix". These books have been billed to your credit card. What would you like to do next?

Buy more books

Add these books to my bookshelf

Read these books now

This example assumes that a User's billing information is supplied to the Service Provider through an out-of-band channel (website, phone, etc.). However, extra steps could be added to this example to collect the User's billing information.

If the User selects "Read these books now", the Service returns a questions element with a contentListRef child that contains the ID of a contentList that contains the three selected books, which can be retrieved through a call to getContentList.

If the User selects "Add these books to my bookshelf", the Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q5-1" value="c2" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <label xml:lang="en">
    <text>Your books have been added to your bookshelf. Please
    select the "Go to your bookshelf" option in the main menu to
    read these books.</text>
  </label>
</questions>

The Reading System renders this as follows:

Your books have been added to your bookshelf. Please select the "Go to your bookshelf" option in the main menu to read these books.

7. Retrieving a Content list

The User selects the "Go to your bookshelf" option from the main menu. The Reading System calls getQuestions as follows:

<getQuestions xmlns="http://www.daisy.org/ns/daisy-online/">
  <userResponses>
    <userResponse questionID="q1" value="c5" />
  </userResponses>
</getQuestions>

This operation returns the following:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
  <contentListRef>L200</contentListRef>
</questions>

The reading system reads the ID of the contentList from the contentListRef element, and calls getContentList as follows:

<getContentList xmlns="http://www.daisy.org/ns/daisy-online/">
  <id>L200</id>
  <firstItem>0</firstItem>
  <lastItem>19</lastItem>
</getContentList>

The operation returns the following contentList:

<contentList xmlns="http://www.daisy.org/ns/daisy-online/" id="L200" totalItems="3">
  <label xml:lang="en">
    <text>You have the following books available to read:</text>
  </label>
  <contentItem id="hp_dh">
    <label xml:lang="en">
      <text>Harry Potter and the Deathly Hallows</text>
    </label>
  </contentItem>
  <contentItem id="hp_gof">
    <label xml:lang="en">
      <text>Harry Potter and the Goblet of Fire</text>
    </label>
  </contentItem>
  <contentItem id="hp_oop">
    <label xml:lang="en">
      <text>Harry Potter and the Order of the Phoenix</text>
    </label>
  </contentItem>
</contentList>

The Reading System renders this as follows:

You have the following books available to read:

Harry Potter and the Deathly Hallows

Harry Potter and the Goblet of Fire

Harry Potter and the Order of the Phoenix

DAISY Online Delivery Protocol - Dynamic Menus Primer

Kenny Johar

Geoff Gilmour-Taylor

Nick Williamson

1. Introduction

2. The Main Menu

3. Search

4. Updating the User Profile

5. Taking a Survey (with audio responses)

6. Content Purchase

7. Retrieving a Content list