Plugin system modelisation
From ClaroDevel
WARNING : This page aims to be THE detailed modelisation we are going to use for the Claroline module system.
- No code suggestions welcome here (this is not this page's goal)
- Do not put either "several potential solution", just make this page become the FINAL specifications of the future module system. If there are things to be talked and decided together, then just put the final decision here. (The page is then subject to a lot of changes.)
- MODULE is the name that should be used, not PLUGIN any longer as the existing tool of Claroline could also be refactored as modules of the system
It is based on a lot of reflexions from the development team, either in the Claroline forum or in other pages of this wiki (see the references at the end of the page)
Module definition and purpose
A Claroline module is a sample of code you can add into Claroline to add new features to a default Claroline platform. Modules may be
- a new tool in the tool list of a course
- a new tool acessible from a defined place of the platform (banner,footer, homepage,...)
This sample of code do not necessary need to be written in PHP, but must content at least an entry.php script as the entry point of the new functionnalities, and a manifest.xml file to describe some needed informations.
This article will focus first on the restrictions and suggestions a claroline module developpers should follow in a module file structure. We will spend more time after on a specific mandatory xml file, the manifest.xml, which must describe the module content, purpose and requirements. Next, we will focus on the different way the module code can interact with the Claroline kernel: which useful librairies should be used and for what, how to display the modules and where,... throught the use of the module docks a buffering system to display links dedicated to the module. Then we will describe the administration interface of the module system in Claroline, what administrator will be able to do and how it will be suggested to them.
Module file structure
The module is supposed to be a .zip file in which the following structure is suggested (two files only are mandatory, the rest is optionnal)
/module_label/ |-- manifest.xml (mandatory) |-- entry.php |-- functions.php |-- admin.php |--/conf | \--/def | \-- config.def.conf.inc.php | |--/lang | |--/en | |--/fr | |--/setup | |-- install.sql | |-- install.php | |-- uninstall.sql | \-- uninstall.php | |--/css | \-- style.css | |-- icon.png (or icon.gif) |-- readme.txt \-- license.txt
manifest.xml (mandatory file)
The manifest is an xml file describing the module's content and structure, see the next chapter for a complete description of this structure.
entry file (mandatory file)
This is the entry point of the module. If there is a "homepage for the module, then it should start from this page. When the module is placed into a 'dock' of Claroline, then this is this file that is included by the kernel.
Default name is entry.php but Manifest can propose another filename. This would be present in most of case for applet, never for language or themas, always for tools.
functions.php
If this file exists it will be included by the Claroline kernel
- only when the module is activated
- everytime a user loads a page in the platform
It means everytime a user loads a page in the platform, this code is included by the Claroline kernel. Module coders should be aware of this and that the code optimisation in that part is critical.
admin.php
This is the script to access to the module ADMINISTRATION PAGE. If there is a stand alone administration page for the module, then it should be callable by using the admin.php page. When going into your module list in the Clarolne administration, this will be linked to this page if there is one in the module repository. A very simple (but not very well integrated) way to add an administration of the module in Claroline
It is also possible to do much more by defining which configuration variables can be modified for the module in a specific file, so that the page to do so is generated by Claroline kernel. Report you to the /conf repository for more information about that.
The /conf/def repository
The /conf/def repository should contain (if needed by the module) the definition file of the configuration parameters of the module. The configuration tool of the Claroline platform can automatically generate the appropriate forms to edit those configuration variables.
EXAMPLE : (the document tool parameters are settable in the administration interface)
config.def.conf.inc.php
This file contains the definition of the module's parameters.
EXAMPLE : (a 'whoisonline' module, where we could set the exact information shown in banner,...)
see Claroline Configuration Definition File Format
The /lang repository
This repository is suggested to contains the translation files of languages in which the module is translated.
/lang/lang_english.php
could be used for the english version for example.
The /setup repository
install.sql
This sql file contains the table that must be created at the installation of the module on the platform database. Any SQL table created with this file can also take account of the table prefix used in Claroline (to represent the main database) if the following tag is used : __CL_MAIN__
example :
CREATE TABLE `__CL_MAIN__user_online` ( `id` int(11) NOT NULL auto_increment, `user_id` int(11) NOT NULL default '0', `last_action` datetime NOT NULL default '0000-00-00 00:00:00', PRIMARY KEY (`id`) ) TYPE=MyISAM AUTO_INCREMENT=1 ;
where the table 'user_online' will be dynamically prefixed, taking account of the one used by the Claroline kernel an main tables.
install.php
This PHP script shall be executed at the installation of the module on the platform.
uninstall.sql
This sql file contains the table that must be droped at the uninstallation of the module on the platform database.
to remove any SQL table created with a dynamic name prefixed (see install.sql) should also take account of the table prefix used in Claroline to be droped correctly on uninstall process.
if the following tag is used : __CL_MAIN__
example :
DROP TABLE IF EXISTS `__CL_MAIN__user_online`;
where the table 'user_online' which was dynamically prefixed taking account of the one used by the Claroline kernel an main tables can be droped correctly.
uninstall.php
This PHP script shall be executed at the uninstallation of the module on the platform.
/css/style.css
Specific style that the module needs to run properly
icon.png and icon.gif
Square png (or gif) image of 16x16 pixels, used in module administration near the module name. In case the module is also a new tool in the course tool list, this will be also the icon used in the tool list on course homepage, once the tool is installed and used in a course.
readme.txt
Important information about this module use that anybody should read before installing and using it.
licence.txt
Detailed license under which this module is released.
Module manifest : manifest.xml (mandatory file)
This xml file describes the module's archive content. Some elements are mandatory, some others not :
Here is a sample of the smallest valid manifest a module could have :
<module> <label>CLMYMODULE</label> <name>module_name</name> <type>tool</type> </module>
Here is a longer version, showing the different metadata's the manifest may contain about the module :
<module>
<label>CLMYmodule</label>
<name>module_name</name>
<version>1.0</version>
<license>GPL</license>
<type>applet</type>
<entry>entry.php</entry>
<icon>icon.gif</icon>
<default_dock value="userBannerRight"/>
<description>
<![CDATA[
This module allows to blah blah blah.
]]>
</description>
<author>
<name>Hugues Peeters</name>
<email>hugues@claroline.net</email>
<web>http://www.claroline.net</web>
</author>
<context>
<course database="kernel"
enabling="automatic"
default_access="all"
access_manager="platform_admin" >
<link target="commonToolList"
path="../../announcements/announcements.php" />
<link target="toolSelectBox"
path="../../announcements/announcements.php" />
</course>
<group db="emule" file="share" enabling="automatic" default_access="group_member" access_manager="course_admin" />
</context>
<requirements>
<claroline>
<version>1.8</version>
<configuration>
<conf name="singleDBEnabled" value="true" />
</configuration>
</claroline>
<php>
<minversion>4.1</minversion>
<maxversion>5.1</maxversion> <!-- phpversion() -->
<extensions>
<loaded>pcre</loaded> <!-- extension_loaded() -->
</extensions>
<phpini>
<ini name="register_global" value="off" /> <!-- ini_get() -->
</phpini>
</php>
<mysql>
<minversion>3.23</minversion>
<maxversion>5.1</maxversion> <!-- mysqlversion() -->
</mysql>
<environment>
<env name="OS" value="Windows" /> <!-- getenv() -->
<server name="SERVER_SOFTWARE" value="Apache" /> <!-- $_SERVER -->
<server name="SERVER_PROTOCOL" value="HTTPS" />
</environment>
</requirements>
</module>
- label : is a unique identifier for this module. You can't install several time a module with the same identifier (label). This element is mandatory
- name : This is the name of the module, which will be used in the module administration. This must be also the name of the zipped package.
This element is mandatory
- toolname : if the module is a new tool, then this element must define the name of the tool
- version : version of this module
- license: license under which this module is released
- type : this element defines the type of the module. Several different types are possible in Claroline (This element is mandatory):
- Tool : for any module that creates a new tool in the course tool list/
- Applet : (example : who is online)
- ... ???
- description : a description of what the module does, which useful additionnal features it supplies on the platform.
- author : informations about the author of the module, including name, mail and website
- requirements : the requirement section defines the technical requirements needed for the module to run properly on the platform, it is separated in 3 sections : the claroline platform (version,...), the php server used and its configuration restriction (version, php.ini file, needed extensions), and the environment(operating system, server software and protocol) used for the server.
- context : list of context (course, group, user, ...) where tool can be actived. Actually most of tools are in course, and some of them also in group.
- each tag is the context name with some attributes
- db : is tool able to store many instance of the context in same tables.
- file : is tool able to manage itself file repository for many instance of the context
- enabling : automatic/manual automatic to auto enable the tool on creation of new instance of this context
- default_access : level required to enter the tool
- access_manager : level to be eable to change default_access value
- each tag is the context name with some attributes
Module docks
The "module docks" in Claroline are the places in the platform pages where a module can add links or contents in the platform interface. Here is the list of those places :
docks for applet modules
- In the Claroline banner :
- In the campus banner
- aligned on the right : campusBannerRight
- or on the left : campusBannerLeft
- In the user banner
- aligned on the right : userBannerRight
- or on the left : userBannerLeft
- In the course banner
- aligned on the right : courseBannerRight
- or on the left : courseBannerLeft
- In the campus banner
- On the campus homepage :
- On the center : homePageCenter
- In the right menu : homePageRightMenu
- On the course homepage :
- In the tool list, as a new tool in the course tool list (this dock is dedidacted to coursetool module type) : courseToolList
This is 14 different places where the module can display contents. This display is settable through the module administration interface.
Module display : the buffering system
Once the docks where the modules are supposed to display code are set, the modules must define and add in a specific buffer the code itself. Typically, for a module with the label my_module, the entry point PHP script will be /my_module/entry.php
You must use the Claroline buffer identified by the name $claro_buffer in the entry file to output some links, text, forms,... in the dock.
A simple example of use if this concept in /my_module/entry.php (in a whoisonline plugin) :
$myCodeToOutput = 'User connected : '.$userNumbers; $claro_buffer->append($myCodeToOutput);
Module administration
This chapter aims to describe the functionnalities the end user (in this case the platform administrator, installing and configurating modules on his own Claroline platform) must be able to do, which interfaces he will have to install/uninstall modules, etc.
Module states and parameters in Claroline
to be reviewed
Detailed list of the possible states (and their detailed description) of a module in Claroline :
- Installed / not Installed
- Activated / not Activated
Some parameters concerning the module display in the platform interface can be set :
- Position : In which module dock the module displays its content (or link to its main page if there is any)
- An order value, is used for the module to be displayed in its dock. In this way, if several modules are installed or added in the same dock, their order of display can be set using this value.
- Access : defines will see the module and will be allowed to enter in its pages (if there is any). The possible values for this parameters are :
- public
- registered users only
- course managers only
- administrators only
Administration interface
"Screenshots" previsions of what the interface looks like, description of how it will behave, how to change the "state" of a module.
Claroline kernel changes needed
The detailed needed (or highly recommanded) changes in the Claroline kernel are the following :
Module System SQL tables
Some new tables for the module administration will be created :
module
Comments
Comments: id, label, name, activate, module_type
Label and Id are two different keys to identify the module
Data structure
|
Field |
Type |
Null |
Default |
Comments |
|
id |
int(11) |
No |
|
unique id number for the module |
| label |
varchar(8) |
No |
|
|
|
name |
varchar(100) |
No |
|
|
| activation |
ENUM('activated', 'desactivated') |
No |
'desactivated' |
|
|
module_type |
ENUM('coursetool','applet') |
No |
'applet' |
Index
Primary key: id
module_info
Comments
Non-technical information about a module is saved in the module_info table. The idea is to keep the table module as small as possible for performance reasons.
Data structure
|
Field |
Type |
Null |
Default |
Comments |
|
id |
int(11) |
No |
|
unique id number for the module |
| module_id |
int(11) |
No |
0 |
|
|
version |
varchar(10) |
No |
|
|
| author |
varchar(50) |
Yes |
NULL |
|
|
author_email |
varchar(100) |
Yes |
NULL |
|
|
website |
varchar(255) |
Yes |
NULL |
|
|
description |
varchar(255) |
Yes |
NULL |
|
|
license |
varchar(50) |
Yes |
NULL |
Index
Primary key: id
dock
Comments
Each entry in this table stores the place (called dock) in the Claroline interface where a module displays its output some HTML code. (links image,...) throught the buffering system.
Data structure
|
Field |
Type |
Null |
Default |
Comments |
|
id |
int(11) |
No |
|
unique id number for the dock |
| module_id |
int(11) |
No |
0 |
related module attached to this dock |
|
name |
varchar(50) |
No |
|
name of the dock where the module displays its buffer content. |
| rank |
int(11) |
No |
0 |
Index
Primary key: id
tool
Comments
This is an adaptation of an existing table in Claroline main DB of 1.7 : cl_course_tool. The table is used for describing existing course tool in Claroline and a new tool resulting of the installation of a module will be the same.
data Structure
| Field | Type | Null | Default | Comments |
|---|---|---|---|---|
| id | smallint | No | unique id number for the tool. | |
| module_id | int(11) | No | foreign key of the related module attached to this tool. | |
| entryUrl | varchar(255) | No | entry.php | url for the tool |
rel tool context Structure
comment
Pour le moment cette table ne semble concerner que les module de type outil mais des réflexion ont déjà montré que ca pourrait être porté aux applet
La table défini les contextes valides pour l'outil.
Par rapport au passé. C'est partiellement l'ancienne table course_tool mais course est devenu un des contextes
data Structure
| Field | Type | Null | Default | Comments |
|---|---|---|---|---|
| id | smallint | No | unique id number for the tool. | |
| tool_id | smallint | No | foreign key of the related tool attached to this contextualisation. | |
| context | enum('PLATFORM','COURSE','USER','GROUP') | No | 'COURSE' | context of the tool, defining where it will be usable. |
| tool_menu | VARCHAR(15) | define where tool entry is shown | ||
| default_rank | smallint | 0 | NULL | default value for the rank in the dock. |
| tool_menu | boolean | No | value to know if the tool must be added by default to a newly created course | |
| access_manager | which user profiles have the right to manage this tool | |||
| entry | varchar(100) | this is the relative url of the entry point of the tool, used in the coursetool right menu to enter in the tool for example |
Index
Primary key: id
New PHP scripts in the /admin repository
Existing scripts to be modified
- /admin/index.php will be changed, just to display a link to the modules'administration page (module_list.php).
- /course_home/course_home_edit will be changed to allow the display of available modules to activate in the course.
- /claro_init_global.inc.php :
- inclusions (include or require in PHP) of the functions.php (if present) in the modules repositories.
- inclusions (of the needed code to add in HTML output) the /css/style.css (if present) in the modules repositories.
- declaration of the installed module's buffers for the docks.
- For each dock (in course homepage and platforme homepage, the concerned scripts must be adapted to display the buffers's content:
- cours_home...
- index_authenticated...
- index_anonymous...
- ...
- The course creation must be modified, to have one installer of each tool.
module_list.php
This script is the main page to administrate the modules available in the platform.
- Existing course tools should become modules and appear also in this list (maybe not in the first version of the module system)
- Any uploaded module is a module in this list.
Purpose of the script :
- display the list of modules
- display links to :
- upload new module
- activate a module
- go to the configuration page of a specific module (module.php)
- change the display order of each module in the dock where they appear.
The script will be based on the classical structure : treatment- data extraction - display like many other scripts of the platform.
module.php
install_module.php
Lang managment
Place your file traduction in lang repository. The name of the file must begin by lang_ and follows by the name of the langage, example lang_french.php
- Introduce your translation in this file :
<?php
$mod_lang['Survey'] = "Sondage";
$mod_lang['Surveys'] = "Sondages"; ?>
- In your script, add $tlabelReq and the function add_module_lang to load your translation
$tlabelReq = 'CLSURVEY';
add_module_lang_array($tlabelReq);
Lang managment
Place your file traduction in lang repository. The name of the file must begin by lang_ and follows by the name of the langage, example lang_french.php
- Introduce your translation in this file :
<?php
$mod_lang['Survey'] = "Sondage";
$mod_lang['Surveys'] = "Sondages"; ?>
- In your script, add $tlabelReq and the function add_module_lang to load your translation
$tlabelReq = 'CLSURVEY';
add_module_lang_array($tlabelReq);
References
- Joomla_!_modules_architecture Analyse of the Joomla! CMS module system
- Dotclear_modules_architecture Analyse of the dotClear CMS module system
- Drupal_modules_architectureAnalyse of the Drupal CMS module system
- Seagull_modules_architectureAnalyse of the SeagullLMS module system
- Horde_modules_architectureAnalyse of the Horde LMS module system
- Moodle_modules_architectureAnalyse of the Moodle LMS module system
- Plugins_talking_8_12_2005recent discussion about modules at the IPM
- Plugins
- Claroline forum
