Sloodle Versions: 2.x (?)

This page is for anybody interested in creating a new SLOODLE object to add to the toolset.

Creating a tool using an existing API

SLOODLE 2 provides a set of API modules providing access to different parts of Moodle. Each API module has its own directory under "mod/" folder in SLOODLE, eg. the quiz API has a folder at "mod/quiz-1.0".

The "1.0" refers to the version of the API module. If we want to change the functionality so that existing tools will no longer work, we'll create a new API module with a new version number, like "quiz-2.0".

Each API module may support a number of different tools that use the same Moodle functionality. We tell Moodle about each tool by giving it a directory under the API module that it uses in the "objects/" folder. The original tool created with the API module is often called "default/", so resources for the original quiz chair are in "mod/quiz-1.0/objects/default/".

The directory for each tool contains a PHP file called "definition.php".

<?php
$sloodleconfig = new SloodleObjectConfig();
$sloodleconfig->primname   = 'SLOODLE Quiz Chair'; // The name of the object in the rezzer.
$sloodleconfig->module     = 'quiz'; // The Moodle module the object uses.
$sloodleconfig->module_choice_message = 'selectquiz'; // The message shown when people select the module to use.
$sloodleconfig->module_no_choices_message = 'noquizzes'; // The message displayed if there is no module to use.
$sloodleconfig->group      = 'activity'; // The group the object should be displayed in in the rezzer
$sloodleconfig->collections= array('SLOODLE 2.0'); // The set of objects this tool belongs to. This allows you to hide objects that won't be in your rezzer.
$sloodleconfig->aliases    = array('SLOODLE 1.2 Quiz Chair', 'SLOODLE 1.1 Quiz Chair'); // Any other names the object may have in the rezzer.
$sloodleconfig->field_sets = array(
        'generalconfiguration' => array(
                'sloodlerepeat' => new SloodleConfigurationOptionYesNo( 'sloodlerepeat', 'repeatquiz', null, 0 ), // An option for whether the quiz should be repeated.
        ),
        'accesslevel' => array(
                'sloodleobjectaccessleveluse'  => $sloodleconfig->access_level_object_use_option(), // A choice about who can use the object.
                'sloodleserveraccesslevel'     => $sloodleconfig->access_level_server_option(), // A different kind of choice about who can use the object.
        ),
);

The directory for each tool should also contain a sub-directory called "assets/". This is for you to put copies of your LSL scripts, textures and sounds. Moodle doesn't use them directly - it's just handier to store them with the definition for the tool.

You can usually start by duplicating the definition for an existing tool. Use lowercaseletterswithoutspaces for the name of the directory, and make your primname "SLOODLE Something With Capital Letters And Spaces".

Once you have an object definition, your object will show up in the list of tools available in your rezzer. But that won't help unless there's actually a tool there to rez. Which brings us to:

Creating a tool inside the rezzer

All tools in the rezzer need to contain a copy of the script sloodle_rezzer_object. This will allow the rezzer to make them go to the appropriate position. It will also set up communication in both directions between the object and the server, as we'll explain later.

It is normally important to make your object capable of receiving configuration information, e.g. from web or notecard configuration methods. The standard way to do this is make your "default" state almost completely idle. The only thing it will do is receive link messages on the SLOODLE_CHANNEL_OBJECT_DIALOG channel, which contain configuration commands. You can usually copy the default state from other objects, and be sure to copy the "sloodle_handle_command(..)" function too, and customize it to suit your needs. You will need to add/remove configuration settings, and make sure the function returns TRUE when it has got all the configuration data it needs, or false if it does not.

Your other states may behave as you like. If you want to completely reset your object and fetch a new configuration, send a "do:reset" link message on the SLOODLE_CHANNEL_OBJECT_DIALOG channel, and the configuration scripts will reset as well.

The scripts, images and sound files specific to that tool should be stored in a directory called "assets/" alongside that tool's definition.php.

If you create scripts that will be shared by other objects using the same API module (eg you might make a shared script used by both your Quiz Rocket and your Quiz Balloon) it should go in an assets/ folder at the top level of that API module, eg. "mod/sloodle/mod/quiz-1.0/assets".

Shared scripts that may be used by multiple tools (see below) should go in the assets/ folder at the top level of mod/sloodle.

As the assets will be included in the in-world objects, in theory it should be possible to delete all the assets/ folders from your server-side module to save disk space.

If you use a shared script in your object, you may find it useful to include a file telling people what shared script they need to add. Use the script name + ".shared.txt", eg: attach_to_avatar.lslp.shared.txt This should be a text file containing a line saying where to get the script, eg:

// SLOODLE LSL Script Shared Location: assets/attachments/attach_to_avatar.lslp

All scripts should have a line at the bottom showing where they are stored in Git, eg:

// Please leave the following line intact to show where the script lives in Git: // SLOODLE LSL Script Git Location: assets/sloodle_email_login_details.lslp

This can be used by automated tools to update shared scripts in the OpenSim oar directly from Git, and vice versa.

Localization Script

If your object outputs any text, then you will need to create a new LSL localization script. The naming convention is as follows: "sloodle_translation_NAME_LANG". The NAME part should probably be very similar to your object identifier, but it is sometimes different, especially if multiple similar objects share the same script. The LANG part should be a language code, such as "en" for English, or "fr" for French.

It is best to copy an existing script, rename it, and change the contents to suit your needs. You will also need to copy some code into your main script so that you can access the localization script. Read the Sloodle LSL Localization Script page for more details.

Standard Scripts

There are many standard Sloodle scripts which are re-used throughout many objects. It is often best to use these wherever possible, so that everything is consistent, and to save you programming time. Some of the common scripts are shown below:

• sloodle_translation_en - the code Sloodle localization script (normally used by all objects)
• sloodle_email_login_details - receives emails and notifies users of their auto-registered account details via Instant Message (has bugs!)
• sloodle_multi_url_loader, sloodle_parallel_url_loader_x - allows parallel loading of multiple URLs to avoid script delays

Any script which is likely to be shared by objects across different API modules should be stored under assets/ in the top directory.

Creating a new API modules

Each API module should have a 'type identifier'. This should consist of two parts: a short name (lower-case letters only), followed by a dash, and a version number (start at version 1.0).

The PHP code that the in-world tool talks to should be contained in a script called "linker.php".

See the Sloodle communications specification for information about how your object will talk to it.

Changes in Moodle

Module Class

If your object adds new web pages to Moodle or adds new kind of data to Moodle, you will probably want to create a Sloodle module class for it. These are classes which effectively 'wrap' all the necessary functionality, such as database queries, with a fairly standard interface. This helps maintain consistency across different parts of Sloodle, and will hopefully make it easier for Sloodle to 'migrate' to other VLE platforms in the future. Additionally, it makes it possible for the Sloodle framework to automatically find and load your module.

Note: the module class should generally not output any information -- it should only be used to fetch and manipulate data.

You will find the module classes in "sloodle/lib/modules". Each module class should be derived from the base class defined in "module_base.php". It is often best to copy an existing module class file, to see how things are done, and customize the functionality to suit your needs. Don't forget to check the base module class to see if there are any standard functions already there, or which you could override.

If your module class filename starts with "module_" and ends with ".php" then Sloodle will find it automatically.

Above all else, it is very important to specify the type name in the "get_type()" function. This should usually match the type identifier you created above, and will allow the system to automatically find the module later on. See the Sloodle Module Class page for more information on this.

Help!

I know this is an awful lot of information to get to grips with! The best thing to do is to start out creating just the Linker Script in Moodle and your main LSL script in Second Life, and don't worry about everything else. When your idea is more fully established, you can start to introduce the rest of the concepts. And if you get stuck, please ask on our development forums.