DAISY Online Delivery Protocol - Dynamic Menus Primer

Kenny Johar

Vision Australia

Geoff Gilmour-Taylor

CNIB

Nick Williamson

RNIB

Johan Abbors

PratSam

Abstract

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.

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:

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.

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.

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/">
  <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:

  • Full text search:

  • Title keyword(s):

  • Author keyword(s):

  • Subject keyword(s):

  • Narrator keyword(s):

  • Call number:

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:

Search for Author: asimoff AND Subject: myst* returned no results. Did you mean "Asimov"? Showing results 1 to 3 of 3.

  • Tales of the Black Widowers by Isaac Asimov

  • More Tales of the Black Widowers by Isaac Asimov

  • The Caves of Steel by Isaac Asimov

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