DAISY Online Delivery Protocol - Dynamic Menus Primer

Kenny Johar

Vision Australia

2. Retrieving the Main Menu

The Reading System retrieves the Main Menu of the Service by invoking the getQuestions operation with the reserved id "default" by passing in the following parameter:

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

The operation returns the following questions type, which conceptually corresponds to 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>
                    <text>Search the Library</text>
                </label>
            </choice>

            <choice id="c2">
                <label>
                    <text>Update your profile</text>
                </label>
            </choice>

            <choice id="c3">
                <label>
                    <text>Take a Survey</text>
                </label>
            </choice>

            <choice id="c4">
                <label>
                    <text>Buy a book</text>
                </label>
            </choice>

            <choice id="c5">
                <label>
                    <text>Download or Stream content</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
</questions>

Each userResponse element contains the user's response to a particular question. As formally defined in userResponse, there are three reserved ids that have a special meaning:

  • default - returns the question that comprises the Main Menu

  • search - returns the question that comprises the search menu

  • back - returns 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 ).

If the userResponse element is being used to encapsulate the User's response to a multiple choice question, the questionID attribute of the userResponse element contains the same value as the id attribute of the corresponding multipleChoiceQuestion element, and the value attribute of the userResponse element contains the same value as the id attribute of the choice element that the User selected.

If the userResponse element is being used to encapsulate the User's response to a question that receives numeric text, alphanumeric text or an audio response (i.e. an inputQuestion ), then the questionID attribute of the userResponse element contains the same value as the id attribute of the corresponding inputQuestion element, and the value attribute of the userResponse element contains:

  • The numeric or alphanumeric text that the user entered if the question receives a numeric or alphanumeric response.

  • An empty string or omitted altogether if the question receives an audio response.

If the question receives an audio response, the audio response is base 64 encoded and encapsulated in the data child element of the userResponse element. See data for file format requirements.

The values assigned to the id attributes of the inputQuestion, multipleChoiceQuestion and choice elements in all the examples listed in this section are arbitrary. These IDs are defined in WSDL as the XSD ID type (see XSD Datatypes), and thus can take any unique value.

The Reading system renders this type 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 
 * Download or Stream content 

3. Performing a Search of the Service's Content Collection

As Search is envisaged to be a very important part of the Online Distribution of content, and thus the Reading Systems may have specific user interface components to invoke search, a special id is available and can be passed into the getQuestions operation to retrieve the menu specific to search.

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

Using the Main Menu from 2, Retrieving the Main Menu, if the user selects the "Search the Library" option, the following userResponses type could also be used to retrieve the Search menu:

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

The reserved search id thus, is a shortcut provided for those Reading systems that have explicit user interface components for invoking the Search feature.

The operation returns the following questions type:

<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>
                    <text>Title</text>
                </label>
            </choice>
            <choice id="c2">
                <label>
                    <text>Author</text>
                </label>
            </choice>
            <choice id="c3">
                <label>
                    <text>Genre</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
</questions>

The Reading System renders this type to the user as follows:


      What would you like to search by?
       * Title
       * Author
       * Genre
     

Assuming that the user selects "Author," the reading system retrieves the next menu by passing in the following parameter to the getQuestions operation:

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

This operation returns the following type:

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

The Reading System renders this type to the user as follows:

Please enter the name of the author.

Assuming the user entered the name "J.K. Rowling," the Reading System invokes the getQuestions operation with the following parameter:

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

This operation returns the following questions type:

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

The reading system extracts the id of the contentList from the contentListRef element, and invokes the getContentList operation as follows:

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

thus requesting the contentList type with the id "l100," and specifying that the first contentItem returned should be at index 0 and the last contentItem returned should be at index 20 (i.e. the first 21 contentItem elements) in the contentList type. The firstItem and lastItem parameters exist to enable the reading system to request a contentList type with a specified number of contentItem child elements, in situations where memory or bandwidth constraints may not permit the retrieval of an entire contentList.

The operation returns the following contentList type:

<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>
            <text>Harry Potter and the Chamber of Secrets</text>
        </label>
    </contentItem>
    <contentItem id="hp_dh" lastModifiedDate="2009-08-22T08:00:00Z">
        <label>
            <text>Harry Potter and the Deathly Hallows</text>
        </label>
    </contentItem>
    <contentItem id="hp_gof" lastModifiedDate="2009-08-04T14:30:00Z">
        <label>
            <text>Harry Potter and the Goblet of Fire</text>
        </label>
    </contentItem>

</contentList>

The Reading System renders this type as follows:


Your Search for "J.K. Rawling" returned the following results: 
* harry potter and chamber of secrets
* harry potter and deathly hallows
* harry potter and goblet of fire

When a Service returns a contentListRef child element within a questions type, the Reading system is logically at the end of the Service's dynamic menu. The reading system extracts the id of the contentList from the contentListRef element as illustrated above, and invokes the getContentList operation to retrieve the contentList.

The Reading System may then retrieve information about the specific contentItems in the contentList type by invoking the getContentMetadata operation, passing in the id of the particular content item. At this stage, the Reading system may ask the user whether he/she wishes to Download or Stream content. If the user wishes to download/stream content, the Reading system calls the issueContent operation passing in the id of the particular content item, followed by a call to the getContentResources operation, to request issuance and retrieve the uris of the resources that constitute the particular content item respectively.

4. Updating the User Profile

Using the Main Menu from 2, Retrieving the Main Menu, if the user selects the "Update your profile" option, the Reading System invokes the getQuestions operation with the following parameter:

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

This operation returns the following type:

<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>
                    <text>Male</text>
                </label>
            </choice>
            <choice id="c2">
                <label>
                    <text>Female</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
</questions>

The Reading system renders this type as follows:


Your name:
Your Address: 
Your Gender
* Male
* Female

After the user responds to the questions, the Reading System invokes the getQuestions operation passing in the following parameter:

<userResponses xmlns="http://www.daisy.org/ns/daisy-online/">
    <userResponse questionID="q3-1" value="firstname lastname"/>
    <userResponse questionID="q3-2" value="street number, suburb, city, state postal code, country"/>
    <userResponse questionID="q3-3" value="c2"/>
</userResponses>

This operation returns the following type:

<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 type to the user as follows:


Your profile has been updated successfully!

As in the case of the Service returning a contentListRef child element within a questions type, if the Service returns a label child element in the questions type, the Reading System is logically at the end of the Service's dynamic menu.

If the Service intends to take the user back to a previous menu after a message such as "your profile has been updated successfully," the Service returns a multipleChoiceQuestion element within the questions type 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>
<text>Reenter your profile information</text>
</label>
</choice>

<choice id="c2">
<label>
<text>Go back to the previous menu</text>
</label>
</choice>

</choices>
</multipleChoiceQuestion> 
</questions>

5. Taking a Survey (with audio responses)

Using the Main Menu from 2, Retrieving the Main Menu, if the user selects the "Take a Survey" option, the Reading System invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
    <inputQuestion id="q4-1">
        <inputTypes>
            <input type="TEXT_NUMERIC"/>
        </inputTypes>
        <label xml:lang="en">
            <text>What is your favourite 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>
                    <text>1</text>
                </label>
            </choice>
            <choice id="c2">
                <label>
                    <text>2</text>
                </label>
            </choice>
            <choice id="c3">
                <label>
                    <text>3</text>
                </label>
            </choice>
            <choice id="c4">
                <label>
                    <text>4</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
    <inputQuestion id="q4-3">
        <inputTypes>
            <input type="AUDIO"/>
        </inputTypes>
        <label xml:lang="en">
            <text>Please provide feedback on the Service.</text>
        </label>
    </inputQuestion>
</questions>

The Reading system renders this type 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 invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

<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>
                    <text>Take another survey</text>
                </label>
            </choice>
            <choice id="c2">
                <label>
                    <text>Go back to the previous menu</text>
                </label>
            </choice>
            <choice id="default">
                <label>
                    <text>Go back to the Main Menu</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
</questions>

The Reading System renders this type 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

Using the Main Menu from 2, Retrieving the Main Menu, if the user selects the "Buy a Book" option, the Reading System invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

<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>
<text>Harry Potter and the chamber of secrets</text>
</label>
</choice>

<choice id="c2">
<label>
<text>Harry Potter and the deathly hallows</text>
</label>
</choice>

<choice id="c3">
<label>
<text>Harry Potter and the goblet of fire</text>
</label>
</choice>

<choice id="c4">
<label>
<text>Harry Potter and the half-blood Prince</text>
</label>
</choice>

<choice id="c5">
<label>
<text>Harry Potter and the Order of the Phoenix</text>
</label>
</choice>
</choices>
</multipleChoiceQuestion>
</questions>

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

When the User's answers are encapsulated in a userResponses type by the Reading System for a multiple choice question that allows multiple selections, each userResponse element holds information about a single selection. So if the user selected three choices out of a list of five choices, the userResponses type would contain three distinct userResponse child elements that hold information about the three choices that the user selected. This is illustrated in the userResponses type below.

The Reading System renders this type 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

(Assuming that the user selects choices 2, 3 and 5)

The Reading system invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

<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>
                    <text>Buy more Books</text>
                </label>
            </choice>
            <choice id="c2">
                <label>
                    <text>Add these books to my download/streaming list</text>
                </label>
            </choice>
            <choice id="c3">
                <label>
                    <text>Download/Stream these books now</text>
                </label>
            </choice>
        </choices>
    </multipleChoiceQuestion>
</questions>

The Reading system renders this type 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 download/streaming list
* Download/Stream these books now

This example presumes that a user's billing information is supplied to the Service Provider through an out-of-band channel (i.e. website, phone ...). However, extra steps could be added to this example to collect the user's billing information if such out-of-band mechanisms were not an option.

If the user selects "Download/Stream these books now, the Service returns a contentListRef child element inside a questions type that contains the id of a contentList, that can be retrieved through a call to the getContentList operation, and that contains the three selected books.

Assuming that the user selects "Add these books to my downloading/streaming list, the Reading System invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

<questions xmlns="http://www.daisy.org/ns/daisy-online/">
	<label xml:lang="en">
		<text>Your books have been added to your downloading/streaming list. 
		Please select the "Download or Stream content" option in the Main menu to 
		download/stream these books.</text> 
	</label>
</questions>

The Reading System renders this type as follows:


Your books have been added to your downloading/streaming list. Please select the "Download or Stream content" option in the Main menu to download/stream these books.

7. Retrieving a Content list

Using the Main Menu from 2, Retrieving the Main Menu, if the user selects the "Download or Stream content" option, the Reading System invokes the getQuestions operation passing in the following parameter:

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

This operation returns the following type:

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

The reading system extracts the id of the contentList from the contentListRef element, and invokes the getContentList operation 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 type:

<contentList xmlns="http://www.daisy.org/ns/daisy-online/" 
    id="l200" totalItems="3">
    <label xml:lang="en">
        <text>You have the following content waiting to be Downloaded/Streamed</text>
    </label>
    <contentItem id="hp_dh">
        <label>
            <text>Harry Potter and the Deathly Hallows</text>
        </label>
    </contentItem>
    <contentItem id="hp_gof">
        <label>
            <text>Harry Potter and the Goblet of fire</text>
        </label>
    </contentItem>
    <contentItem id="hp_oop">
        <label>
            <text>Harry Potter and the Order of the Phoenix</text>
        </label>
    </contentItem>
</contentList>

The Reading System renders this type as follows:


You have the following content waiting to be Downloaded/Streamed
* Harry Potter and the deathly hallows
* Harry Potter and the goblet of fire
* Harry Potter and the Order of the Phoenix