DAISY Online Delivery Protocol - Dynamic Menus Primer

1. Overview

Reading Systems can access a Service's dynamic menus using the getQuestions operation. getQuestions takes one parameter, userResponses, which itself contains one or more userResponse elements. Each userResponse element contains the user's response to a particular question or a reserved question ID.

There are three reserved question IDs:

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:

To respond to an inputQuestion in a userResponse:

Question and choice IDs are arbitrary.

The following examples of User-Service interaction are meant to show some of the purposes the Dynamic Menus feature of the protocol may be used for. The menus themselves, the User's responses and the rendering of the menus are illustrative, not compulsory.

2. The Main Menu

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

3. Search

<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/">
  <inputQuestion id="q2-1">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Full text search:</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q2-2">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Title keyword(s):</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q2-3">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Author keyword(s):</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q2-4">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Subject keyword(s):</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q2-5">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Narrator keyword(s):</text>
    </label>
  </inputQuestion>
  <inputQuestion id="q2-6">
    <inputTypes>
      <input type="TEXT_ALPHANUMERIC" />
    </inputTypes>
    <label xml:lang="en">
      <text>Call number:</text>
    </label>
  </inputQuestion>
</questions>

The Reading System renders this to the User as follows:

If the User specifies the author keyword "asimoff" and the subject keyword "myst*", 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-3" value="asimoff" />
    <userResponse questionID="q2-4" value="myst*" />
  </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>19</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 19 (i.e. the first 20 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>Search for Author: asimoff AND Subject: myst* returned no results.
    Did you mean "Asimov"? Showing results 1 to 3 of 3.</text>
  </label>
  <contentItem id="dtb49589" lastModifiedDate="2009-08-20T11:00:00Z">
    <label xml:lang="en">
      <text>Tales of the Black Widowers by Isaac Asimov</text>
    </label>
  </contentItem>
  <contentItem id="dtb51992" lastModifiedDate="2009-08-22T08:00:00Z">
    <label xml:lang="en">
      <text>More Tales of the Black Widowers by Isaac Asimov</text>
    </label>
  </contentItem>
  <contentItem id="dtb66185" lastModifiedDate="2009-08-04T14:30:00Z">
    <label xml:lang="en">
      <text>The Caves of Steel by Isaac Asimov</text>
    </label>
  </contentItem>
</contentList>

The Reading System renders it as follows:

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:

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:

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:

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:

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:

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:

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:

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:

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: