Doc for claroline developpers



Make a script for Claroline

Modifié le 05/12/03 à 14:28:32

I Organisation of a scripts

1 Structure of a scripts

1.1 One script in 7 steps

1.2 preview of steps

Step 1 is probably only setting of $langFile, and later à tool id setting.

more info in 2.2

Step 2 and Step 4 are needed

more info in 2.3 for step 2

Step 3

a. Use value from step 2 to set some values used by step 4

b. We go try here to let all code wich don't change set 4 effect after step 5.

Step 5 don't exist now because there is no function already writed.

Step 6 It's your time coders.... it's your space to code.

Step 7 just include wanted footer.

1.3 Sample

1.3.1 Source

1. <?php

2. /*==========================

3. INIT

4. ==========================*/

5. $langFile = "course_foo";

6. @include('../include/claro_init_global.inc.php');

7. $nameTools = $langTitleOfFoo;

8. @include($includePath."/claro_init_header.inc.php");

9. ?>

10. <h3><?php echo $nameTools ?></h3>

11. <?php

12. @include($includePath."/config/foo.config.inc.php");

13. $Tbl_FOO = $mysqlMainDb."`.`foo";

14. $Tbl_BAR = $_course['dbName']."`.`bar";

15. $CourseIDToShowInFoo = $_course['sysCode'];

16. $is_allowedToSeeFooInfo = $is_courseAdmin;

17. ####################### SUBMIT #################################

18. if($is_allowedToSeeFooInfo)

19. {

20. echo "hello world","<BR>";

21. echo "You are in the course with sys code : ", $CourseIDToShowInFoo,"<BR>";

22. $sqlSelectAllFoo ="select * from ".$Tbl_FOO." order by idFoo";

23. $sqlSelectAllBar ="select * from ".$Tbl_BAR." order by idBar";

24. (...)

25. }

26. else

27. {

28. echo $langForbidden;

29. }

30. @include($includePath."/claro_init_footer.inc.php");

31. ?>

1.3.2 details

line 5 : step 1

line 6 : step 2

line 7 : step 3

line 8 : step 4

lines 9 to 29 : step 6, your script

line 30 : step 7

2 claroline init section

We go to present here step 1 and step 2.

We have search to give to coder an easy sytsem to plug a script in claroline. So you can see in the sample thats not very hard, just some line to add in top, one in bottom and you can interact your script with claroline. But, it can be interresting to understand whats (and why) do the init functions.

In easy word, init read some value to produce a set of value usefull to influence your script. Theses values are called « parameters »

2.1 parameters of Claroline Scripts

There is 2 types of parameters from init section

• permanent parameters

  read in config file. Theses values are fixed during the install, and can be edit by admin of the platform.

• Current/dynamics/contextual parameters was

1. /include/setting.php for courses in Claroline132. This script was only write to init parameters between current user and current courses and globals parameters for this course.

2. During login procedure for user for user datas.

Now theses values are set during claro_init_global. But many more value are set there, with our new init :

config.inc.php (permanent parameters) and claro_init_local.inc.php are called by claro_init_global.inc.php

The init section is in the script claro_init_global. It's not a function, just include is enough.

2.2 Before the init

The step 1

Step 1 is probably only setting of $langFile. Line 5 in the sample.

The usage of $langFile is explain in « 2.6 lang files »

2.3 Structure of init

The Step 2

This step is just include our script, (line 6 in sample claro.init.global). We show now what's happen in it.

InitStep 1 Session_start();

initStep 2 Set $includePath

Determine the directory path where this current file lies.

This path will be useful to include the other intialisation files

initStep 3 Set $SELF

A shorter reference to $PHP_SELF. Useful to lighten the HTML code.

initStep 4 Include the main Claroline platform configuration file

config.inc.php (permanent parameters)

initStep 5 Connect to the server database and select the main claroline DB

initStep 6 Include the « local » init

claro_init_local.inc.php (contextual parameters)

initStep 7 Load languages

common language properties and generic expressions

english version

localised version

2.4 Config file

InitStep 4

In the permanent parameters, we find info about path, databases, some strings and some option

2.4.1 Parameters to config databases

2.4.2 Parameters to config paths

2.4.3 Datas

2.4.3.1 Strings

2.4.3.2 switchs

2.4.3.3 backgrounds

2.4.4 Compatibility

To keep a compatibility with 1.3.2 thes following variables are filled with new variables content

2.5 local init

2.5.1 work of local init

2.5.1.1 The keys

Init is working starting 5 values called key in my document

• about User : $_uid

• about Course : $_cid

• about Group : $_gid

• about Tool : $_tid

• about Session : $_sid

$_uid

So $_uid is set by auth procedure and only by auth procedure.

They can be reset by logout script and by « change my profile »

$_cid

The key of course is usally defined when we enter in course, so in « CoursesRepository/CoursePath/index.php »

$_gid

The key of group is actually the key of a group in a course.

To find a group we need to know the $_gid AND the $_cid

$_sid

The key of session is théoretic beacause still unique.Indeed, in actual system, a course can have only one session. If you want run the course again,with a new classe, without less « datas of previous course life (student list, works, forum,....), you need to create a new course and copy again common documents was in the previous course.

$_tid

The key of tools is not always defined. Is actually use by the introduction function.

So, as the keys are used to find some value about the element linked to this key (course, group, session, user, tool), tools is implicit in each script, so, values about tools can be assigned in the script.

2.5.1.2 Types and levels

Whe have 2 types of datas from 3 levels

Types

• boolean datas

• explicit datas

Level

• Key // Id

• Element // Domain // oneKeyDependance

• Intersection // multiKeysDependance

Rules

All boolean are always set

All boolean are called $is_*

All explicit values are called $_*

Explicit values are filled with good value or destroyed (empty = really empty, empty != not set) Explicit values are filled when all keys needed have a value.

2.5.1.3 Element // Domain // oneKeyDependance

When you can associate some data to one key, you are in this level.

Sample

with $_uid, I can found a name, a username, an email ...

with $_cid, I can found a coursename, a coursepath, visibility status ...

2.5.1.4 Intersection // multiKeysDependance

When you need more than one key, you are in this level.

Sample

to find the rôle of John Doe in course Foo, you need the $_uid of John and the $_cid of course foo.

Note that for groups it's always this third level. Because there is no data for a group « bar » witch is not link to a course because all groups are link to a course.

2.5.2 Variables read by init

2.5.2.1 From config

$mainDbName

This value is used for thes SQL request

$userPasswordCrypted

This value is used to know if password stored in database is clear or crypted

2.5.2.2 From the script (in code or read in $HTTP_*_VARS)

$_uid, $_cid, $_gid ($_sid and $_tid don’t exist actually)

only read from the session ($HTTP_SESSION_VARS)

($uidReq => $login+$password), $cidReq, $gidReq

to request access respectively to user, courses, and groups area/domain

$uidReq don’t exist, because we must understand « $uidReq is user id of user link to $login AND $password » pair

if $logout is set thats like a uidReset with login null

Theses variables would be set before include of init. Most part of time, they are set by the way of post or get values.

$uidReset, $cidReset, $gidReset

To force read for all dependent value of each keys. This actionrefresh value in session.

If an acces to one of theses domains is request (by setting wanted id the $*Req var of this domain/area, and that this value is not same than current id/key of this domain/area then init force to true the $*Reset

The $*Reset are only set by init for this previous reason, so if before including the init, theses variables are already set tu true, they continue with this value and the reset would be keep.

But on the end of the init the $*Reset variables would be deleted.

If a $*Reset is set and the corresponding $*Req is not filled¹, that's mean that we leave the domain. $*Req is null so init destroy value about this area.

The $*Req are destroy on end of init.



2.5.3 Variables Set by init

2.6 lang files

$langFile is defined in step 1

$langFile must contain string to build lang filename

Sample

$langFile = "myTool";

Must be understand that init do load /langFileRepository/selectedlanguage/myTool.inc.php

Note : that myTool.inc.php MUST exist in /langFileRepository/english/

Read more info about it in « langfile of my tool ».

Each tool have a included file with all strings of output.

Theses lines ares each time assign in a set of variables beginning by « $lang »

There is one file by language, by script.

English file need to exist with all variable to exist.

Translation files contains same variables

Hugues works on a better sytem to prefect inclusion of languages.

3 header section

We go to present here steps 3,4, and 5. (enumered in « 1 structure of script »)

After init, you can change values, there is no change in the init system.

It’s your job to accept or refuse user following $is_* states

But somes generic function must be writed to standardize this job to have generic message (sub step 3.3)

3.1 Before the header script

Set variables before call header output

3.1.1 variables used by header init

3.1.2 Set variable used by header init script

The step 3.

You have see that only the six first are filled by user.

Note also that $langFile is normaly already set, because needed by init section.

3.2 Structure of header section

The step 4

headerStep1 send HTTP header

headerStep2 send HTML header

headerStep3 send layout header

3.3 HTTP header

This output have already be started during the init by the session_start();

Actually, we send just header to set the charset.

We tell add some other header later to enhance the cache usage.

We send also header that the script receipt in step 3 by the way of $httpHeadXtra

3.4 HTML header

We begin here the output of html

3.4.1 DTD

We have chose this DTD

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

3.4.2 TITLE

The title of page is build like this : name of tools and name of course, name of platform.

3.4.3 <LINK> and <META>

3.4.3.1 CSS

We use the <link> to keep the default.css file as stylesheet.

3.4.3.2 others

There is no more default, you can add your <link> and <meta> by the way of $httpHtmlXtra

So we go perhaps add some meta for « information » and <link> for alternate navigation.

3.5 Layout header

3.5.1 body

<body bgcolor="white" dir="<?= $text_dir ?>">

All body are white and we use the dir read in init. (generic lang parameters)

3.5.2 banner

The banner is a complete <TABLE> in a complete <DIV>

and after the breadcrump.

The breadcrump is build in order with content of SiteName, courseName, interbredcrump, ToolName

3.7 Select database

3.8 Standard functions for scripts

The step 5

This sub step don't exist but this is a sample of function we want to prupose.

• thisIsOnlyForCourseMember();
• thisIsOnlyForCourseManager();
• thisIsOnlyForCourseTutor();
• thisIsOnlyForClarolineUser();

3.9 Meaning of variables

I have list a lot of varibale but not always describe the meaning

4. The body of Script

Step 6

There is your code but we can suggest some idea.

4.1 sql

Claroline work with 1, 1+n or 2+n databases (n as number of courses)

For this reason, the first big request for you code is build table name in top of script and one time by table.

4.1.1 databases

4.1.1.1 Names

The names of databases is fix init

For central database the name is in config

4.1.1.2 Fill

4.1.2 tables

If « foo » is the name of a table of dbCourse and « bar » the name of a table in main DB

build something like this.

In top of script :

$Tbl_BAR= $mysqlMainDb."`.`bar";

$Tbl_FOO = $_course['dbName']."`.`foo";

and later in script

sql = "select * from `".$Tbl_BAR."` WHERE .....";

sql = "select * from `".$Tbl_FOO."` WHERE .....";

4.2. Variables connection.

Values from init have a name following the right or the global sense of content.

This note have perhaps more sense for the boolean value.

We recommend to assign a new var with a name wich have a sense in your script with the content of a variable from the init plutot que use the variable from init in your script.

Why ?

The first reason is the distinction between your code and global code.

The second, is because it's very more easy for an admin the change the code to change something in data from init if he can easy find where it's use for the first time.

Sample

You have a script where user can edit some data if he have administration right

We recommend to have something like this :

$is_allowedToEdit = $is_adminOfCourse;

If an admin want give also this rigth to tutors, he change this line in

$is_allowedToEdit = $is_adminOfCourse || $is_tutorOfCourse;

You see here that's very easy to change.

With usage we go to check if it's not a good idea to move this in a config file or build some function to have dynamics rigth (following parameters dependant of some keys).

Name of variables .

Each time as possible find a name, in english, following the rules , and witch have a sense in your script (and not necessary in the global claroline naming space).

In top of your script, you set values with value from init.

Try don't use directly variable name of our init scripts.

If the name used in int script have a sense for your script add a commented affectation to show that you use the value during the script

// $nameOfVarInInitScript = $nameOfVarInInitScript ;

Why, we think that can't comes.

• If the variable contain a state with a name like « $is_ », the new name would be a var like « canDoThis » or better « $is_allowedTo »

• If the variable contain a string value, the name in init is too generic. The word « current » would be added in the name of variable used in the script.

• Prevent our semantic errors. We had already do errors in choose of names of variable. Probably that some errors of sense still in our scripts. If we decide to change one, and that you don't use the « variable connection bloc », the sense of the var name can no more follow the sense of is usage.

About the values of init.inc.php

$is_course_allowed means that $_uid can acces to course.

$is_course_admin means that user can manage the course.

$is_course_member mean that this user have subscribed this course.

Is course participant ? = $is_course_allowed.

I want change these status for

The CourseAdmin can decide if Participant is only open to member or to everybody.

When a course is close, it's easy. Nobody can be eable to contribute in course without be member.

When course is open, the option can be present

Note about spaces of keys.

We have see that some scripts can be multi Keys Dependant

But somes scripts can be multi level space.

They can have in the same output, part dependent of on key and other part dependant of another key but in the to part same type of data.

The page can show a list of element where a part of this elements are link to $_a and another part link to $_b or $_a&$_b or $_b&$_c ....

Our init script give to say

• who amI

• wich course

• wich session

• wich tool

• wich team

and wich is my right in this situation

But it's your script wich « decide » what I can do and see.

In other words

If I'm uid 7 and not course admin.

I can see the list of users in a course where I'm allowed.

But the link to « edit user » is only show for the use with uid == 7.

If some element can be single link to many key. (je c plus ce que je voulais dire là)

Imagine that in the future, our announcement tool axist for course, user and group_course.

The list of announcements contains some element because I'm uid 7, some other because I'm in course ZZZZ, and others more because I'm in course ZZZ in groupe 4.

Abstract sample.

In a shoes shop, there is shoes for men, for women, for childs and also for sports and walk.

We see in this list, 3 keys.

1. Sex

2. Activities

3. Age

So all theses shoes are in the same shop. But in the next street there is a shop only for Sport Shoes.

Under a « stamp » theres is sometimes many keys fixed or not.

Sport shoes you fix activities, and sex is floating.

Think like this with your scripts.

Forum have categories.

Is for Course-User

Course-Group-User

Note that Course and user are in the 2 kits.

So in script we talk about « categories » and « categories for groups »

To back to the sample with the user list.

We want to add the link edit when it's me. The idea ist to fix the right the most readabely

somethink like

$showEditForThisUser = ($userToShow['id']==$_uid) || $is_courseAdmin || $is_plateformAdmin

4.3 Config for tools

If some tools have some config values, it's better to move theses assingment in /inc/conf/nameTools.config.inc.php

In next version of claroline, an editor by web for theses parameters would be added in admin section.

Some idea are

use ini file in place of php files.

Editing of config value done in a table of the database with generate files config files.

4.4 editing values use/set by init

If you edit values stored in init system, you need to re-store in session, if you want to use them later in the script.

Why

To protect the system, value in session can be only set by value from database. And value in database can be set only by a procedure wich check validity before writing.

So if you wan change a value keep in session, change it in database directly, if we don't have write a function to do this work, or use one function of our libs. And relaunch init procedure.

2 methods are used

1. include again th claro_local_int.inc.php file

2. Send header to reload.

Actually we have frequently use the 1, without search wich is best when. But the 2^nd need a good MVC Script. Ie : The claro_init_header won't be already loaded

Sample

in course_info.php

This script change properties of the current course, but theses datas are stored in session.

The good way is to update database, and after

activate the request for this domain -> courses -> $cidReq = 1

and next call the init script

include( "....../claro_local_init.inc.php ");

if your script edit data in domain of an active key

actually you need to

1° update data in the real place of storage

(db with an update) or file

2° Now the new data is writed, but the data in your variables set (vars from init and session) need to be to refresh.

You can do it just by include the init script.

With 2 assignements before.

$*Req = $_*; $*Reset = true;

Where * is the key that you have updated.

Global or local init script ?

If value use by global aren't change, prefers local init.

Later a function would be write to edit thes datas with an auto-refresh.

4.5 Another aproaching for step of script.

As we recommend to split compute and output, we can disallowed the point B of step 3. (1.2 preview of steps)

If we consider that steps 4 and 5 are the official limit between compute and output. In deed, the main work of step 4 is to begin output.

If you follow this other aproaching

Note that the step to include config tools come before your code, so also before steps 4 and 5

To stay easy to read we recommend to add just before and just after steps 4 and 5 big comments marks (view writing rules )

4.6 near MVC model

Order

1. Command

   1. Get values

   2. Check values

   3. Set flag for work

2. Work

   1. make job

   2. store msg and body to output in variables (not formated)

   3. set view flag

3. Output

   1. claro_header

   2. output title

   3. output messages (4.6.1. Message To user)

   4. output body (process by php )

   5. output foot

4.6.1 Message to User

4.6.1.1 One message by output

If you know that in script we go tou output one message use this.

In the control code

$msgClass ="success"; // success | warning | error

$msgBody ="foo";

In ouput (try to use the same for all output, so before case ($display)

if ($msgBody)

{

echo "<br><br><DIV class=\"".$msgClass."\">".$msgBody."</DIV><br>";

}

4.6.1.2 Many messages by output

If you can have many message in one output use this.

In the control code

$msgClass ="success"; // success | warning | error

$msgArrBody[$msgClass][] ="foo";

In ouput.

if (is_array($msgArrBody))

{

echo "<br><br>";

while(list($msgClass,$msgBodies)=each($msgArrBody))

{

echo "<DIV class=\"".$msgClass."\"><UL>";

while(list($msgNo,$msgBody)=each($msgBodies))

{

echo "<LI>".$msgBody."</LI>";

}

echo "</UL></div>";

}

}

5 End of scripts

On end of scripts you can call the footer script.

So there is 2 contents for one name.

During the debug the best is to replace claro_init_footer.inc.php with the content of claro_init_footer.inc.php.for.dev.dist

We hope to refine this solution.

How work the footer for debug ?

Actually you need to swap the to contents to use debug echo in all script

or edit the script to debug

The debug footer print out the state of all value set by init and the content of the arrays $error_msg and $error_no

So you can add in your code somthing like this

$classError = "thisTool";

$error_msg[$classError][] = "[".__FILE__."][".__LINE__."] this brol don't work ";

$error_no[$classError][] = "25"; -> add in /claroline/docs/errorCodes.txt

So think to add your error code in the file /claroline/docs/toolname.errorCodes.txt

We study home solution and php_unit and syslog.

Protections of scrips, using value from init.

As local init provide some values, you can use it to manage right.

Usually there is 2 places use the protection.

1^st in the script wich need theses right/datas.

So you can't enter if agenda tools, if your not courseAllowed.

2^nd in the scripts where link to the protected script is show to user which have right

Why show a link to a forbidden place ?

Strings

Places strings in variables, and place theses variables with content in the file ($langFile based)

Rules and logical decision

Claroline have no specifications but a roadbook. (found it on www.claroline.net)

We make choice and we try to follow them.

Find here a list of choices.

Users

1. a user have always a username, a password, a name and a firstname
2. a user can subscribe it'self (can be dislabed ;-( )
3. a user can give an email, a phone number, an officialCode (be unique or empty)
4. for the system, 2 accounts are 2 differents persons
5. Name, Firstname and email are public
6. username and password are only readable by owner
7. email is reserved to platform users
8. phone are reserved to courses manager (and owner + admin)
9. status, expiration, creatorId are sysadmin reserved
10. only admin of course can edit user properties

11. admin of course can add account other than is own, but still the propritary until first login of a user with this account login-pass

User Info

(bloc = section, including a title ,write by course admin and a content fill by user.

1. The manager of the course define blocs
2. Defined blocs are required (show also title for not filled blocs)
3. A user can edit only it's own info
4. Empty blocs do not necessary existing in DB.
5. Empty blocs are show
6. Some contents can exist for undefined blocs.
7. Some contents can exist for unknow users.
8. A bloc can't be hide for one user.

Courses

1. course have many users
2. course can have many course admin
3. course have 1 categorie
4. course are used of one session
5. course must have as less One User adminOfCourse
6. course can work without groups
7. course can work without student

8. all admin of a course have sames right

Groups

1. groups are always member of a course.
2. groups can be empty
3. groups have tutor and members
4. user marked as tutor in a course, can be member of another groups of same course
5. user marked as tutor can be tutor of many groups
6. groups can have only 1 tutor
7. groups can count many member
8. groups can have a max of member defined or not)
9. groups can work with less than max member
10. groups can't count twice the same user

11. user can have many groups

1. group (can) have forum
2. group (can) have wiki
3. group (can) have documents repository
4. group (can) have agenda
5. group (can) have forum

6. tools of group can be public or private. (1 flag for all tools). private means only member of this group can ...

Course description

1. course_description is a list of blocs
2. each bloc contain a title and a body
3. some titles can't be change (only translate during change of lang

4. There is 1 calandar by course

Course_home

1. only admin of course can switch tools for student between visible and hide

2. only admin of platform can switch tools for admin of course between visible and hide

Course_info

1. admin of a course can edit course properties

Create_course

1. A user need creator status to use this script

Admin

1. admin is reserved to user present in .htaccess

2. table admin content user who can admin all courses

Todo

1. every user can add suggestion

Auth

1. only owner of an account can edit an account

ps: My Profile <> My User Info ?

Student_view

1. a admin of cours or of platform can view all as a user

Statistique / tracking

1. a teacher can view stat usage about his course.
2. a user can see all information stored about him
3. tutor can have view on activity of student of his group.

Announcement

1. Announcement are linked to a course.
2. Only admin(s) the course can post announcement
3. Creation date-time of announcement is only « info »

4. admin of course can edit ordering of announcement.

Forum

1. there is only 1 forum by course.
2. forum contain many categories
3. a user can view categorie content , if he can view the category in his list
4. categories can be "public", "course member only", "group member only", "teatcher team only"
5. user can edit is own messages
6. only user member of course can post in forum
7. tutor can edit post of other in forum of his group
8. admin of course can edit all post in his course
9. admin of platform can edit all post in all course

10. admin of course can lock a categories

Chat / Discussion

1. 1 chat général pour le cours
2. 1 chat per team
3. chaque chat peut-être remis à blanc par l'administrateur

4. chaque chat peut-être sauvé par l'administrateur

Calendar

1. only admin of course can add entries in calandar

2. There is 1 calandar by course

Document

1. only admin of course can add, rename, delete or move document and directories

Exercice

1. only admin of course can add exercices

Import

1. only admin of course can imports links and pages

Link

1. only admin of course can add entries in bookmarks

2. There is 1 calandar by course

Work

1. only admin of course can delete and edit works
2. users member of course can add works
3. admin can create many "session of works"
4. user can chose to submit a work in ALL section
5. admin of course can lock a session of work BEFORE the first open
6. admin of course can Not lock a session of work BEFORE the first submit of work

7. admin of course can give a dead line

Garbage

        Must be created on install