Source for file linker.php

Documentation is available at linker.php

  1. <?php
  2.     /**
  3.     * Sloodle demo linker (for Sloodle 0.4).
  4.     * Allows a demo object to link to Moodle.
  5.     *
  6.     * @package sloodle
  7.     * @copyright Copyright (c) 2009 Sloodle (various contributors)
  8.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  9.     *
  10.     * @contributor Peter R. Bloomfield
  11.     */
  12.     
  13.     // Common parameters for linker scripts
  14.     //  sloodlecontrollerid = ID of a Sloodle Controller through which to access Moodle
  15.     //  sloodlepwd = the prim password or object-specific session key to authenticate the request
  16.     //  sloodlemoduleid = ID of a module to load (corresponds to a course module instance ID, i.e. the 'id' field of the 'course_modules' db table).
  17.     //  sloodleuuid = UUID of the avatar
  18.     //  sloodleavname = name of the avatar
  19.     //
  20.     // Less common parameters:
  21.     //  sloodleserveraccesslevel = how strict should access be? Handled entirely by the SloodleSession object
  22.     //
  23.     //
  24.     // The following parameter is optional:
  25.     //  sloodledebug = if 'true', then Sloodle debugging mode is activated -- should only be used from a web-browser as it outputs lots of extra info
  26.     
  27.  
  28.     /** Lets Sloodle know we are in a linker script. */
  29.     define('SLOODLE_LINKER_SCRIPT', true);
  30.     
  31.     /** Grab the Sloodle/Moodle configuration. */
  32.     require_once('../../sl_config.php');
  33.     /** Include the Sloodle PHP API. */
  34.     require_once(SLOODLE_LIBROOT.'/sloodle_session.php');
  35.     
  36. ///// SETTING UP THE SESSION //////
  37.     
  38.     // Construct a SloodleSession to handle this request.
  39.     // This provides a framework to handle all the common SLOODLE-related things.
  40.     // By default, this immediately processes important incoming data, but you can suppress that with optional parameters. (See API documentation.)
  41.     $sloodle = new SloodleSession();
  42.     
  43.     // Check that the object is allowed to access Moodle.
  44.     // This checks that a SLOODLE Controller has been identified, and that a password has been given too.
  45.     // If it fails, it will normally terminate the script with an error, but you can suppress that using optional parameters.
  46.     $sloodle->authenticate_request();
  47.     
  48.     // At this stage, you are guaranteed that the request is secure... or at least as secure as we can make it. :-)
  49.     
  50.     // Note:
  51.     // There are two types of authentication - prim password, and object-specific password.
  52.     // In both cases, a SLOODLE Controller must be identified in the "sloodlecontrollerid" HTTP parameter, and the password in the "sloodlepwd" HTTP parameter.
  53.     // A prim-password is just a 5 to 9 digit number, and it is the same for any object using the Controller.
  54.     // An object-specific password is a 9-digit number PLUS the object's UUID, and it is unique for every object.
  55.     
  56.     // * See the SLOODLE PHP API documentation for more information about the "SloodleSession" class *
  57.     
  58.     
  59. ///// HANDLING THE USER /////
  60.  
  61.     // Many requests either deal with or are originated by a particular avatar.
  62.     // For example, the WebIntercom needs to know who is chatting a message.
  63.     // This information is passed-in using two parameters: sloodleavname, sloodleuuid.
  64.     // It is good practice to provide both in your script, but just one will usually suffice (unless you want to auto-register a new avatar).
  65.     
  66.     // You can use the following method to check that an avatar has been specified.
  67.     // This will also check to see if they are registered in Moodle, and enrolled on the course.
  68.     // If it fails, it will normally terminate the script with an error, but you can suppress that using optional parameters.
  69.     // Note that this function will auto-register and/or auto-enrol avatars if necessary and if the Moodle site/course allow it.
  70.     // An important side-effect of this function is that it forces Moodle to think the registered Moodle user is actually logged-in for the duration of this script.
  71.     $sloodle->validate_user();
  72.     
  73.     // At this stage, you are guaranteed to have a valid avatar AND Moodle user.
  74.     // You can now access the user information like this: $sloodle->user->...
  75.     // For example, let's get the names of the avatar and Moodle user.
  76.     $avatarname = $sloodle->user->get_avatar_name();
  77.     $moodlename = $sloodle->user->get_user_firstname() .' '. $sloodle->user->get_user_lastname();
  78.     
  79.     // * See the SLOODLE PHP API documentation for more information about the SloodleUser class. *
  80.     // SloodleUser is defined in: sloodle/lib/user.php
  81.     
  82.     
  83. ///// LOADING MODULES /////
  84.     
  85.     // In order to improve portability and code-reusability, a modules system was created.
  86.     // It is not essential, but can help keep linker scripts clean and free of Moodle-specific database code.
  87.     // The SloodleModule base class provides a common base for any SLOODLE code which 'wraps' a Moodle module.
  88.     // For example, the SloodleModuleChat class provides simple functions to handle a Moodle chatroom.
  89.     // Similarly, the SloodleModuleBlog class provides simple functions to handle the Moodle blog.
  90.     
  91.     // Note that these will NOT necessarily correspond to actual Moodle modules (although they usually do).
  92.  
  93.     // The following method can be used to load a module wrapper for a chatroom.
  94.     // The first argument names the module, and the second indicates whether or not there is database data to be loaded.
  95.     // Note that this will load the module identified by HTTP parameter 'sloodlemoduleid'.
  96.     // If that parameter is not provided in the request, then this method will terminate the script with an error message.
  97.     // If the module loading fails (e.g. due to a database error) then the script will also be terminated, although that behaviour can be suppressed by addition optional arguments.
  98.     $sloodle->load_module('chat', true);
  99.     
  100.     // You can now access the module like this: $sloodle->module->...
  101.     // There are some common functions, such as getting the name of the module, and various functions specific to the module class that was loaded.
  102.     $modulename = $sloodle->module->get_name();
  103.     $chatmessages = $sloodle->module->get_chat_history();
  104.     
  105.     
  106.     // * See the SLOODLE PHP API documentation for more information about the "SloodleModule" class *
  107.     
  108.     // SloodleModule is defined in: sloodle/lib/modules/module_base.php
  109.     // The sub-classes are defined in: sloodle/lib/modules
  110.     // The module loading code is define in: sloodle/lib/modules.php
  111.     
  112.     
  113.     
  114. ///// GETTING INPUT /////
  115.  
  116.     // You will often want to pass data from SL to Moodle as HTTP parameters. This can be done using GET or POST parameters.
  117.     // You can fetch either type of data easily using the "SloodleRequest" object within the SloodleSession.
  118.     // You access it using: $sloodle->request->...
  119.     
  120.     // If there is a parameter called 'message' that you absolutely MUST receive for the script to work properly, you can fetch it like this:
  121.     $requiredmessage = $sloodle->request->required_param('message');
  122.     
  123.     // If the parameter was not given in the HTTP request, then the script is immediately terminate with an error message.
  124.     // The argument gives the name of the parameter to fetch.
  125.     // If the parameter was specified, then it is returned as a raw string (you MUST do proper data cleanup before putting it into a database query, otherwise you'll be vulnerable to SQL injections).
  126.     
  127.     
  128.     
  129.     // If a particular parameter is optional (i.e. you may or may not receive it), then you can use the following method:
  130.     $optionalmessage = $sloodle->request->optional_param('anothermessage', '');
  131.     
  132.     // The first argument gave the name of the paramter.
  133.     // The second argument gave the default value that would be returned if that parameter was not passed to this script.
  134.     // If the parameter *was* provided for this script, then the raw string value is returned.
  135.     
  136.     
  137.     // * See the SLOODLE PHP API documentation for more information about the "SloodleRequest" class *
  138.     // SloodleRequest is defined in: sloodle/lib/io.php
  139.     
  140.     
  141. ///// RETURNING A RESPONSE /////
  142.  
  143.     // After you have done some processing, you have to provide a response.
  144.     // There is information in the developer documentation on the SLOODLE wiki about the appropriate communications specification.
  145.     // Note that *anything* you output, e.g. using "echo" or "print" becomes part of the response.
  146.     // The SloodleResponse object within SloodleSession provides some assistance.
  147.     // You can access the response object like this: $sloodle->response->...
  148.     
  149.     // You must always provide a status code (see the wiki for a list of these):
  150.     $sloodle->response->set_status_code(1); // Positive means OK, negative means an error
  151.     
  152.     // You must also provide a simple, generic, status 'descriptor' (a short human-readable string):
  153.     $sloodle->response->set_status_descriptor('OK');
  154.     
  155.     // You can optionally add data, line by line. Each line can have several fields, usually separated by | characters.
  156.     // There are several ways to add the data.
  157.     $sloodle->response->add_data_line("Avatar name is: {$avatarname}"); // Just add a string on each line
  158.     $sloodle->response->add_data_line(array('Moodle name', $moodlename)); // Add several fields on a single line
  159.     $sloodle->response->add_data_line(array('module', 'name', $modulename));
  160.     
  161.     // Just some more usage of input data
  162.     $sloodle->response->add_data_line("Required message: {$requiredmessage}");
  163.     if (empty($optionalmessage)) $sloodle->response->add_data_line("No optional message provided");
  164.     else $sloodle->response->add_data_line("Optional message: {$optionalmessage}");
  165.  
  166.     
  167.     // Finally, you MUST remember to render the response!
  168.     $sloodle->response->render_to_output();
  169.     
  170.     // Alternatively, you can render the output to a string, like this:
  171.     $output = '';
  172.     //$sloodle->response->render_to_output($output); // Passed in by reference
  173.     // You can then output that string yourself, or send it by XMLRPC or similar.
  174.     // NOTE: for XMLRPC into SL, you need to replace newlines (\n) with \\n before sending.
  175.     
  176.     
  177.     // * See the SLOODLE PHP API documentation for more information about the "SloodleResponse" class *
  178.     // SloodleResponse is defined in: sloodle/lib/io.php
  179.     
  180.     
  181. ?>

Documentation generated on Fri, 17 Jul 2009 11:01:47 +0100 by phpDocumentor 1.4.0