This Sloodle article is deprecated. It is probably out of date and will not be updated. It continues to exist only for reference purposes.

The Sloodle choice is designed to tie-in directly with the Moodle choice, allowing simultaneous use through Moodle and through Second Life.

  • NOTE: this specification changed on 2008-02-06. Minor modification to HTTP communications format, and the addition of the in-world structure.

Targets

  • Respect visibility of choice instance in Moodle
  • Display choice name in-world
  • Display choice text (i.e. question) in-world
  • Display range of options in-world
  • Display results
    • Only display results if Moodle would also display them for *all* users
  • Respect open/closed status of choice
  • Respect limitation on number of selections per option
  • If open and available, allow user to click their option in-world and send update request to server
  • Allow user to update their if they would be allowed to on Moodle as well
  • Show number of students who have not answered (only if Moodle would also display it)

Data

In-World

Constants:

  • SLOODLE_OBJECT_DIALOG_CHANNEL = the channel used for configuration commands
  • SLOODLE_CHOICE_LINKER_SCRIPT = the relative path of the choice linker script from the server www root

Configuration variables:

  • sloodleserverroot = the root address of the Sloodle installation
  • sloodlepwd = prim password for the Moodle site
  • sloodlecourseid = ID of the course which the is part of
  • sloodlemoduleid = ID of the relevant module instance in Moodle database (in this case, should refer to a choice module)

{TODO: write-up details of data in LSL implementation}


In-World Structure

The object in-world will divided into two parts: the back-end, and the front-end. They will always be linked together, meaning that the scripts can communication via link message. (Note: the scripts cannot all go in the same prim, as the link messages will be sent to all other prims, to prevent excess filter processing).

There are several advantages to this structure:

  • Allows easy 'modding' -- users can create their own interfaces without having to re-code the basic choice processing part
  • Allows easy localization -- users can create different language versions of the front-ends
  • Easier to debug than having everything in a single script


The back-end is the part which performs all of the communications with Moodle, and which organising all the choice data. It will send an HTTP status request to Moodle (see the "SL-Moodle Communications Format below), store all the choice data, and send information to the front-end object(s) via link message. It will receive link messages giving user interactions with the front-end, send these as additional HTTP requests, and respond via link-message again with the results.

The front-end provides the complete interface, such as selection buttons, results displays, and chat messages to inform the user of what is happening.


Back-end to Front-end Communications

All link messages will take place over the "SLOODLE_OBJECT_DIALOG_CHANNEL" (that is, the integer value in link messages). The string will provide the main item of data, and the key will be used to identify the relevant avatar where appropriate.

Reset Command

This command is used to completely reset the choice. The front-end script(s) should be completely reset in response to this message. The string part of the link message will contain the following

reset

Update Question

This command sends the question associated with the choice, and it should somehow be presented to the user. It will start with "question|" followed by the test of the question, like this:

question|Which operating system do you prefer?

Number Unanswered

This command notifies the front-end of how many people have yet to answer the choice in the Moodle course. If it is 0 or greater, then the value can be displayed. If it is negative or not-specified at all, then it should not be displayed. It will consist of "num_answered|" followed by the number, e.g.:

num_unanswered|32

Accepting Answers

This command will notify the front-end of whether or not the choice is accepting answers. It will consist of "accepting_answers|" followed by "true" or "false". If it is not specified at all, the frontend should assume that answers are being accepted. (The linker script will ensure no answers are sent to a closed choice).

accepting_answers|false

Update Option

When the back-end receives a list of options from Moodle, it will go through them, and send out an "update" command for each one. The front-end should always store a list of current options, so that it knows if the update refers to an existing option, or if it should create another. The string of the link message will start with "option|", followed by the data:

option|<id>|<text>|<numselected>

The <id> is the ID number of that option in Moodle, and the front-end must send it back to the back-end whenever an option is being selected. The <text> part is the text which should be displayed with the option -- this ought to be fairly brief. The <numselected> part is an integer saying how many people have selected that option so far. (NOTE: this value will be negative if the results are not to be displayed).

  • Remember, there will be one option update message for every option.

Selection Response

When the back-end has received a selection from the front-end (i.e. a user has selected an option), it will send a request to Moodle containing the selection. When it has received a response from Moodle, it will send a response back to the front-end. The key will contain the UUID of the avatar who selected something, while the string will contain the following:

selection_response|<status>

The <status> part will be a status code, as follows (note: positive means success, negative means error!):

  • 10011 = made new selection for user
  • 10012 = update user's selection
  • -10011 = The user has already selected a choice, and choices cannot be updated
  • -10012 = Maximum number of selections for this choice already made
  • -10013 = Choice is not yet open for selections
  • -10014 = Choice has been closed
  • -10015 = Specified option not found in choice
  • -10016 = Unable to make choice selection for unknown reason

It is up to the front-end to make appropriate messages to report the situation to the user.

Front-end to Back-end Communications

As with back-end to front-end communcations, all link messages will take place over the "SLOODLE_OBJECT_DIALOG_CHANNEL" (that is, the integer value in link messages). The string will provide the main item of data, and the key will be used to identify the relevant avatar where appropriate.

Selection Request

When a user selects an option in the choice (e.g. clicks on an object), the front-end needs to report this to the back-end. This is done using a link message, where the key contains the UUID of the avatar who selected something, and the the string contains the following:

selection_request|<id>

The <id> part is an integer giving the ID of an option, as was provided in the "Option Update" message (see above).


SL-Moodle Communications Format

An LSL script in-world will make an HTTP request to the choice linker PHP script on the Moodle site. A response will be returned according to the new communications format (see Communicating between server and client and Sloodle status codes). The linker script will reside within the Sloodle module, at this address relative to the WWW root of the Moodle site (so this is what would be stored in "SLOODLE_CHOICE_LINKER_SCRIPT"):

mod/sloodle/mod/choice/sl_choice_linker.php

So for example, this would be at the following address on Sloodle.org:

http://www.sloodle.org/mod/sloodle/mod/choice/sl_choice_linker.php

Everything up to (but not including) the first "/mod" will be defined by the "sloodleserverroot" variable, as provided by the object configuration.


HTTP Requests

All requests must include the following basic parameters (GET or POST):

  • sloodlepwd = prim password for site
  • sloodlecourseid = ID of course in Moodle database


The linker script will adopt 1 of 3 modes, depending on the parameters specified.


Error Response

The error and success responses will follow the same basic layout, as according to the page on Communicating between server and client. If you first divide by newlines (\n), then divide by pipes (|), the very first item you get back indicates the status of the response. If it is negative, then you have an error... otherwise it appears to have been successful.

Basic format for errors:

error_code|descriptor
long_description

The usual object/user authentication error codes may be returned, such as the following if the prim password is invalid:

-123|OBJECT_AUTH
The specified prim password was invalid.

Module error codes may also be returned, such as:

-713|MODULE_INSTANCE
The choice instance you were trying to use is inactive.

Other error codes may also be given, as according to the Sloodle status codes page.

Success Response

The status line returned for each successful request will be very similar in most cases. The difference is the data following it, and this will depend on which mode the linker script has adopted.


Choice List Query Mode

This is the most basic mode, and provides a list of all choices available (i.e. visible) in the specified course.

HTTP Request

Only the required parameters, "sloodlepwd" and "sloodlecourseid", should be specified.


Error Response

There are two error codes specific to this kind of query:

-10021|CHOICE_LIST_QUERY
Failed to query list of choices for unknown reason
-10022|CHOICE_LIST_QUERY
No choice instances availabe in course


Success Response

The success response will a list of each choice available:

10021|CHOICE_LIST_QUERY
{integer: id number of instance}|{string: name of instance}

So for example, for a course which contains 3 available choice instances, the linker script might return the following:

10021|CHOICE_LIST_QUERY
18|Operating system survey
23|Favourite programming language
24|Number of computers owned

The ID number specified for each instance corresponds to the "sloodlemoduleid" parameter which must be specified when accessing the choice linker script in other modes.


Choice Status Query Mode

This mode is used to obtain details about a specific choice (name/text of choice, number of options etc.).


HTTP Request

The only additional parameter required for this mode is the choice instance ID, as obtained either manually from the Moodle site, or using the "Choice List Query" mode above.

  • sloodlemoduleid = ID of the relevant module instance in Moodle database (in this case, should refer to a choice module)


Error Response

There is a choice query error code, although this is unlikely to be used:

-10001|CHOICE_QUERY
Unable to query choice status for unknown reason

All other errors are likely to be standard errors.


Success Response

There will generally only be one success code for a choice query, which will be 10001. This will also return data about the choice in the subsequent data lines:

10001|CHOICE_QUERY
choice_name|{string:name of choice}
choice_text|{string:text of choice (i.e. question)}
option|{integer:option id}|{string:option text}|{integer:number selected so far}
num_unanswered|{integer:number of students not yet answered}
accepting_answers|{true/false:is the choice currently open?}

There will be as many "option|..." lines as there are options in the choice. The number selected so far of each option (and the number not yet answered) will be -1 if the information is not to be displayed.

Here is an example of a choice which has been closed, and for which the results are visible, but the number of people who didn't choose is not visible:

10001|CHOICE_QUERY
choice_name|Cheese Survey
choice_text|Which of these cheeses do you like best?
option|1|Stilton|2
option|2|Wensleydale|7
option|3|Parmesan|4
option|4|None of them|1
num_unanswered|-1
accepting_answers|false


Selection Request Mode

The selection requests are used when a user in Second Life clicks on an option. The object does not immediately update its own data, but send the request to Moodle to find out if the choice is valid.

HTTP Request

This mode requires the same "sloodemoduleid" parameter as for the choice status query mode. However, there are two or three additional parameters required as well:

  • sloodlemoduleid = ID of the relevant module instance in Moodle database (in this case, should refer to a choice module)
  • sloodleoptionid = ID number of the option being selected
  • sloodleuuid = UUID (key) of the avatar who made the selection
  • sloodleavname (optional) = name of the avatar who made the selection

Note that if the UUID is specified without the optionid, then the script will assume it is just a choice status query. However, if the optionid is specified without the UUID, then a -311 error (USER_AUTH) will be returned. (The avatar name can be used instead of the UUID, although the UUID is definitely preferable).

Error Response

Once again, the responses will follow the standard format, with the possibility of various general error messages. There are additional error codes which are specific to the choice selections, and they are visible on the Sloodle status codes page.

One difference is that the UUID which was passed to the script (if any) will be specified in the status line of the response, e.g. as follows:

-10014|CHOICE_SELECT|||||{string:uuid}
Choice has been closed.

Notice the large number of empty pipes. The number is important, as those may be used for other purposes in the future.


Success Response

There is very little different between a success and an error response for the choice selections. The status codes will be positive for success, and there will not be any long description. Additionally however, the "side-effect" section of the status line may be used, typically to indicate that the user was auto-registered and auto-enrolled. E.g. the following:

10011|CHOICE_SELECT|322,422||||{string:uuid}


This page is part of the SLOODLE documentation
Docs: Users | Administrators | Developers
Document Top Sloodle.org