SLOODLE 0.

4 Object Scripting 13/01/2009 11:28:12

SLOODLE 0.4 Object Scripting

When coding a new object, you need to establish the name of the object. It should
consist entirely of lower-case alphabetic characters, such as “chat” or “glossary”. The
main LSL script for the object will then be called:

“sloodle_mod_NAME-1.0”

The “1.0” is the version number, and should only be incremented when the method of
interacting with the server changes... e.g. the name or number of parameters in the
HTTP request is different.

Core LSL Scripts

The following scripts are common to any SLOODLE tool, and do not usually require
modification:

sloodle_setup_web
This script handles the basic authorisation and configuration of objects over the web,
and must be included, except for user-centred objects such as the Toolbar. When
running, it will respond to a touch event to start the configuration process, and then
download the configuration, sending it to other scripts in the object via link message.
When the object has been rezzed by a SLOODLE Set, it will attempt to determine the
key identifying the Set which rezzed it. After it has been configured, it will only
respond to specific link and chat messages on the standard channel,
SLOODLE_CHANNEL_OBJECT_DIALOG (see wiki for details).

The following link message is valid at any time:

“do:reset” – causes the script to completely reset (will always respond to this).

The following link messages are only effective after the object has been configured:

“do:requestconfig” – re-download the configuration and re-send it via link

message
“do:reconfigure” – start the configuration process again from the beginning

The following chat messages are valid any time after authorisation:

“do:cleanup” – deletes the object if it was rezzed by a SLOODLE Set, and if the
chat message came from the rezzing Set.

Note: this script requires script “sloodle_translation_XX” for text output.

sloodle_setup_notecard
This script is the counterpart for sloodle_setup_web, except it reads a
“sloodle_config” notecard to obtain the tool configuration, and then sends it via link

Page 1 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

message to other scripts in the object. It must be included in all tools, except user-
centred tools such as the Toolbar. When it first starts running, and any time it detects
an inventory change, it will look for a “sloodle_config” notecard, and read it if the
object has not already been configured.

It will respond to the following link messages at any time:

“do:reset” – causes the script to completely reset (will always respond to this).
“do:requestconfig” – re-download the configuration and re-send it via link
message

Note: this script requires script “sloodle_translation_XX” for text output.

sloodle_layout_object
This script is used by the layout manager in the SLOODLE Set in order to allow an
existing layout of objects to be restored. It is unclear whether or not this feature will
be included in future versions, but for the time being, it the script must be included in
all objects which can be rezzed by the SLOODLE Set.

Configuration values are received by link message from one of the setup scripts, and
it interacts with the rezzing SLOODLE Set by chat on channel
SLOODLE_CHANNEL_OBJECT_DIALOG.

sloodle_translation_XX, sloodle_translation_BATCH_XX
The first is the core localization script for all SLOODLE tools, and must be included
in all SLOODLE objects. The second is a generic name – replace BATCH with the
name of a particular tool for any tool-specific translation scripts. Replace XX with a
language code, such as “en” for English, or “fr” for French. For example, the Choice
tool in English would include the following scripts:

sloodle_translation_en
sloodle_translation_choice_en

The contents of each script must be translated for the appropriate language, and it will
support output in several formats, including IM, chat, and dialogs. The scripts require
no configuration, and should always be ready to use immediately.

Requests to output a translation string should be sent by link message on channel

SLOODLE_CHANNEL_TRANSLATION_REQUEST. The string takes the
following format:

“output_method|output_params|string_name|string_params|batch_name”

• output_method – the name of a particular output method. These are all

defined near the top of any translation script, including things like “say”,
“dialog”, “whisper”. Note that each output method requires different
output_params.

Page 2 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

• output_params – a comma-separated list of values required by the output

method. E.g. for chat messages, this must be the channel number for the
output chat message, and for dialogs it must be a channel number followed by
the names of one or more buttons.
• string_name – the name of a particular string you want to output. You can
find the strided list of strings/translations at the top of any translation script.
• batch_name – this identifies which translation script you are requested. The
batch name is defined inside each translation script, but should match the
batch in the script name (e.g. “choice” or “chat”). For the core SLOODLE
translations, leave batch blank.

Some output methods also require that a key is sent with the link message. For
example, a dialog needs to know which avatar to show the dialog to.

Note: most scripts which require translation use a shortcut function called
“sloodle_translation_request” to simplify the construction and sending of link
messages. This can be copied from many existing scripts, and appears as follows:

sloodle_translation_request(
string output_method,
list output_params,
string string_name,
list string_params,
key keyval,
string batch)

Other LSL Scripts

These are various other core scripts which can be useful, but are not always required.

sloodle_debug
Most SLOODLE objects will output debug information all the time, via link message,
on SL’s DEBUG_CHANNEL. Drop this script into an object to be able to see those
debug messages. The script can be customized to output messages as ownersay, public
chat, or IM.

sloodle_multi_url_loader, sloodle_parallel_url_loader_X
The first script manages the loading of multiple URLs in quick succession, without
script delays. The second is a generic name, where X should be replaced by a number
(each of these scripts also needs to have the number coded into the script itself). The
sloodle_multi_url_loader script will be given a specific number of “parallel” scripts
available, and will cycle through each of them, sending the request to load a URL via
link message.

It is recommended to use this via the translation scripts, with output method set to
SLOODLE_TRANSLATE_LOAD_URL_PARALLEL (the actual value is

Page 3 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

“loadurlpar”). You can copy the appropriate scripts from a tool such as the
Registration Booth.

sloodle_manual_reg_enrol
Any objects which need to initiate manual registration and/or enrolment of avatars can
use this script. (Note: it also requires the “sloodle_translation_regenrol_XX” script for
language output.) You can initiate registration and enrolment by sending a link
message in this form:

llMessageLinked(LINK_THIS, SLOODLE_CHANNEL_OBJECT_DIALOG,
"do:regenrol|" + sloodleserverroot + "|" +
(string)sloodlecontrollerid + "|" + sloodlepwd, id)

You can replace “do:regenrol” with “do:reg” or “do:enrol” if you only want to
perform registration or enrolment respectively. Other parameters come directly from
the configuration of the object:

• sloodleserverroot – URL of the Moodle site

• sloodlecontrollerid – ID of the controller to connect through
• sloodlepwd – the password used to authenticate this object

sloodle_email_login_details
If an avatar attempts to use a tool, but they are not registered on the Moodle site, the
system can automatically attempt to register a new Moodle account for them, linked
to their avatar. (This is governed by a global admin configuration setting for
SLOODLE, and by course-specific settings accessible via the SLOODLE Controller.)

If a Moodle account is registered automatically for an avatar, then the new login
details are emailed back to the original object. This script simply polls for new emails
periodically, and will IM the user with their new login details. It needs not
configuration or interaction... simply drop it in.

Server-side
Several things need to be done to setup the system on the server-side. First, in the
“sloodle/mod” folder, create a folder with the name and version number of your
object. Typically, it should contain the following scripts:

• linker.php – the main script used to interact with the Moodle system
• object_config.php – defines the form used to configure the object in Moodle.
You can copy lots of this from other objects.

The folder should also contain the LSL scripts which are specific to your new tool, so
that they can be version-managed.

Page 4 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

Note: there is an explicit communications method used by SLOODLE tools, defining

common names for parameters, and format for messages. Information about this is
available in the developers section of the SLOODLE wiki.

Module Classes
If your tool connects to an existing Moodle feature, then you may be able to code
everything into the linker.php script. However, it is recommended that you create a
new module class which ‘wraps’ the Moodle functionality. You can find existing
module classes in the “sloodle/lib/modules” folder – note that each filename is
specific, e.g. “module_chat.php”. The name of the file should correspond to the name
of the class inside, and each class should be derived from the “SloodleModule” class.

These module classes can largely be copied and tweaked as necessary – but be sure to
create the “load” function correctly if you need to load data from the database. When
it is in place, you can load the module from your linker script like this (assuming you
have created a SloodleSession called $sloodle):

$sloodle->load_module(‘name’, true);

The ‘name’ part specifies the name of the module to load, corresponding to the
file/class name. The ‘true’ parameter indicates that you are loading something from
the database – if you do not need to do this, then make the parameter false. The
system will attempt to load the module you have specified from the incoming HTTP
parameter “sloodlemoduleid”. This should be a Moodle course module instance ID
(corresponds to the ‘id’ field of the Moodle “course_modules” table).

SLOODLE Sub-Types
If you are creating an entirely new feature, e.g. in the way that the SLOODLE
Presenter doesn’t tie-in to an existing Moodle feature, then you also need to add a
‘sub-type’ to the SLOODLE module. This is a rather involved process, requiring
several steps:

First, open the “sloodle/sl_config.php” script, and scroll down to the “Types of
Sloodle module” section. Add a PHP constant to identify your module, for example:

define('SLOODLE_TYPE_MAP', ‘map');

The string on the right should match the object name you decided above – it will be
stored in the database to identify the different types. Below that, make sure to add
your new type to the list of all types, like this:

$SLOODLE_TYPES[] = SLOODLE_TYPE_MAP;

The list just makes it possible to add your new module to the “Add an activity” menu
on Moodle courses.

Language Pack
You need to add an entry for your module name to the language pack. For the basic
English language file, open up “sloodle/lang/en_utf8/sloodle.php”. Look for a line
like this:

Page 5 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

$string['moduletype:controller'] = 'Sloodle Controller';

Replace the ‘controller’ part on the left with the name of your module, e.g. ‘map’, and
replace the string on the right with a plain English name for your module, such as
‘Second Life Map’. If you attempt to edit a Moodle course and add an activity, you
will now see your Module added to the SLOODLE section of the list of activities.

Module Form
Next, you need to add some custom content to the “add module” form. You will find
this in “sloodle/mod_form.php”. The classes and functions used to build the form are
peculiar at first – I haven’t ever found documentation for it, but you can get the
general idea by looking at existing SLOODLE form elements, or the same file in
other Moodle modules. If you scroll down a short way in SLOODLE’s mod_form.php
file, you will see a switch statement which has a “case” for each different sub-type of
the SLOODLE module, including the Controller and Distributor. Add a new “case”
for your new module type, and add whatever form elements you are likely to need.

You will probably want to start with this:

$mform->addElement('header', 'typeheader',
$sloodletypefull);

You can add other form elements easily. Make sure you name each element starting
“NAME_”, where NAME is the name of your module, such as ‘map’. Append the
name of the element, e.g. “map_initialx”.

Database
Every time a new SLOODLE module instance (of any type) is created in a course, a
new entry is added to the Moodle “sloodle” table. Unfortunately, this doesn’t store
much information, so each sub-type generally needs its own secondary table. Look at
the “sloodle_controller” table for an example. The first two columns are very
important: id, and sloodleid. The “id” is just the unique identifier within the table, and
“sloodleid” corresponds to the “id” field of the “sloodle” table. Everything else is up
to you.

The secondary table should be named starting with the Moodle prefix (typically
“mdl_”), followed by “sloodle_”, and then the name of your module. You can create
as many additional tables as you need – for example, the Distributor requires one
table to remember each Vending Machine, and another to remember all the items
inside them.

During development, you will probably want to just create the new tables using
phpMyAdmin or similar. Later on, when you have established the structure of the
database fully, you will need to customize the “install.xml” and “upgrade.php” scripts
in the “sloodle/db” folder. These are very important scripts! Never, under any
circumstance, modify them on the main trunk version of SLOODLE... only modify
them in branches, otherwise upgrades are likely to fail.

Page 6 of 7
 SLOODLE 0.4 Object Scripting 13/01/2009 11:28:12

Add / Update / Delete code

Moodle needs to know how to make necessary modifications when somebody adds,
updates or deletes your module. This is defined in the “sloodle/lib.php” file. When
you open it, you will see several functions; the important ones are
“sloodle_add_instance”, “sloodle_update_instance”, and “sloodle_delete_instance”.

In the add and update functions is a switch statement to handle different types of
SLOODLE module, so add your own case to each. You can see other module types
adding and updating information in their secondary tables, creating instances as
required. All the data provided from the module form (“mod_form.php”) is available
in the $sloodle parameter. For example, if you created a form element called
“map_initialx”, then you can access it like this:

$x = $sloodle->map_initialx;

The add and update code is likely to be very similar. The delete code is often
different, but very simple. Just make sure to delete any entries from the database
which correspond to the instance being deleted. Note: the $id parameter should
correspond to the ‘sloodleid’ field in your secondary tables.

Viewing the module

The last thing to do is make the module viewable in Moodle. The process for doing
this changed in SLOODLE 0.4 (it was very different in 0.3!). Open up the
“sloodle/view” folder, and you will see several files. Open “controller.php” as an
example, and you will see a class inside derived from “sloodle_base_view_module”.

The concept is that you create a class with all the different stages of viewing
functionality. The SLOODLE framework will then launch that code and call the
various functions at the appropriate times. The functions are as follows:

• process_request – fetch any data from the request parameters, to load the
module from the database
• process_form – if you have a form on your module, you can process it here
• print_header – display the header of the page. If you omit this function,
Moodle will display a standard header
• render – display the main content
• print_footer – display the footer of the page. If you omit this function,
Moodle will display a standard footer.

It is worth looking at the standard “sloodle_base_view_module” class to see the items

of data which already exist in the class. In order to populate those items, you need to
call the parent’s “process_request” function. You can do that at the top of your own
process_request function like this:

parent::process_request();

When somebody tries to view your Module in Moodle, the framework automatically
determines what kind of module it is, and loads your class.

Page 7 of 7