zen and the art of claroline module development

1. Zen and the Art ofClaroline Module Development

Or: How I Learned to Stop Worrying and Love CreatingClaroline Modules

Take a look at the module architecture of Claroline

Explain how to create a Module using the Claroline Module API

See how module development can be made simpler using the embed.lib

Take a look at the future and improvements of Claroline modules

Modules mean modularity

To enhance Claroline modularity

To decouple the kernel and the tools (development and release)

To allow building la carte Claroline distributions

To make upgrade simpler

To help the distribution of home-made tools

To help developers to create new tools

A business unit that could be

An applet

Adds some functionnalities to existing pages

Displays output in reserved zone called docks

A (course) tool

A bigger piece of script that adds a new tool to Claroline

Could be accessed through the tool list of a course

A package containing a set of files

Some are mandatory

manifest.xml , describes the module

entry.php , the entry point of the module

Other are optional

Setup files

Configurations

Libraries

Icons and Style sheets

A (not so) short tutorial

Content of entry.php :

First the script initialises and call the Claroline Kernel to set session variables, check access rights, load libraries, load lang and config...

Then the script executes its business logic to produce the data that will be used in display

The Kernel is called to display Claroline header and banner

The script displays its output

The Kernel is called to display Claroline footer

The module manifest contains the data needed to install and run the module

Mandatory data are :

Module Label, module unique identifier

HELLO here (Upper case)

Module Type, applet or tool

tool here

Module Name,

Hello World

Other optional data could be added

Module description

Module author data (website, email,...)

Module version

Module dependencies

Module license

The manifest is written in XML

The content of manifest.xml :

< label > HELLO label >

< name > Hello World name >

< type > tool type >

< description > a really useful tool description >

< version > 0.1 version >

< author >

< name > Me name >

< email > [email_address] email >

< web > http://me.mydomain.net/HELLO web >

author >

Create a zip archive hello_tool.zip containing

entry.php

manifest.xml

Go to Administration > Platform > Modules

Click the 'Install module' link and choose the hello_tool.zip package

Activate the module

Test the module in a course

An applet is a small piece of code

But some applets could have an associated tool-like script

Applets can output some data in reserved zones called docks

the manifest SHOULD include the definition of a default dock

Applets use a buffer to generate their output

Content of entry.php:

Content of manifest.xml:

< label > ALOHA label >

< name > Hello World name >

< description > Hello Applet description >

< type > applet type >

< default_dock > userBannerRight default_dock >

Create a zip archive hello_applet.zip containing

entry.php

manifest.xml

Go to Administration > Platform > Modules

Click the 'Install module' link and choose the hello_tool.zip package

Activate the module

The text Hello World ! appears in user banner

We want to personalize the message for each user

We will use Claroline API functions to

Control the tool workflow

l10n / i18n messages using get_lang

Retrieve user data

New version of the business logic in entry.php:

// Business logic

if(claro_is_user_authenticated () )

$sayhello=

get_lang ( " Hello %firstName% %lastName% ! "

,array ( ' %firstName% '=>

claro_get_current_user_data ('firstName'),' %lastName% '=>

claro_get_current_user_data ('lastName') )

$sayhello=get_lang ( " Hello dear visitor ! " );

Display the last date a user access to our module

Need to

Create the database using the module setup scripts

Use the module API to access the database tables

Store and retrieve the data using Claroline SQL functions to show the last script access date to a registered user

The module setup contains :

Main database SQL setup scripts :

install.sql : sql script run at module install, typically for database tables creation

uninstall.sql : sql script run at module uninstall, typically for tables deletion

Course database SQL setup scripts run :

course_install.sql : to install the module in a course

course_uninstall.sql : run at course deletion

Create a table using install.sql :

CREATE TABLEIF NOT EXISTS

` __CL_MAIN__ hello_user_access`(

userIdint(11) unsigned not null,

accessDatetimestamp not null default now(),

primary key (userId)

Drop the table with uninstall.sql:

DROP TABLEIF EXISTS

` __CL_MAIN__ hello_user_access` ;

Use get_module_main_tbl to get the module table names

Use claro_sql_query to create or update the last access date associated with the current user

Use claro_sql_query to get the last access date associated with the current user

Write course setup scripts :

course_install.sql

course_uninstall.sql

using __CL_COURSE__ instead of __CL_MAIN__

Call install_module_in_course

module label of the current module

claro_get_current_course_id()

Use get_module_course_tbl instead of get_module_main_tbl

Main databases :

Setup scripts executed only once

Data are shared over the platform

You have to store course informations

Course databases :

Install script executed at each access to the module, uninstall script executed at course deletion

Data are private to a course, not shared

Course information stored in database schema

And make your scripts code simpler with embed.lib

No more need to include header and footer

Make display options

Simpler to control

Easier to understand

Make your source code clearer

Easily convert an existing script into a Claroline module

Use embed.lib that provides

function claro_embed, to embed script output in Claroline

class ClaroScriptEmbed, OOP version with methods to add extra element and control display

Use a buffer to store your script output

A buffer string variable

PHP output buffering functions

Pass the buffer contents to the function/object

Content of entry.php :

Let's take a look at some potential improvements in the Claroline module architecture

Enhance current module types

Group tools

Allow applet contextualization

Add new module types

Shared libraries and drivers

Administration, platform and other tools that run outside a course

Languages, Themes and Wysiwyg editors

Dependency checking and enforcement

Version management and upgrade

Developer-friendly

Kernel safe mode (no modules loaded) in case of platform crash

Course install by Kernel not by hand

Module reinstallation

Split file uninstallation from data deletion

Enhanced debugging facilities

New embedding classes for HTML Frames and Framesets (already in 1.9), for Applets (decorators)...

Module packager

Manifest generator

Unit test integration

zen and the art of claroline module development

Technology