Dokeos

This page contains general information about the Dokeos API. If you want to learn how to use it, read the post on Using the API.

Since summer 2004, there has been a serious increase in the amount of code libraries available. We are also busy improving the code documentation, which is written in such a way that we can let PhpDocumentor automatically generate documentation in html format. In the future we will make these API docs available through the Dokeos website, but everyone can generate this documentation from the code.

History

The first library we created was to be the main API, the most important one that all scripts now include by default, through including the claro_init_global.inc.php. This [b]main_api.lib.php[/b] was built on for some time, which was good. But we wanted to see in one glance where a certain function was defined, so we renamed all functions in that library [b]api_xxx[/b]. The others remain only for compatibility reasons and will be removed in future revisions.

After that we used some good suggestions about coding from a book called Advanced PHP Programming (great book). One of the tips they gave was to built libraries and store functions inside a class, even when not using object oriented programming. This means you can use the functions as before, no need to create objects, but they are organised more cleanly. So we experimented with this, and created a few functions in e.g. the new dababase.lib.php, inside a class called Database. All functions inside that class are called like this: [b]Database::function_name()[/b] . This looks very neat, you see immediately what this function is about and where it is stored.

The proposal to organise all our libraries that way was accepted in a developer meeting some time ago. Since then, we've added the classes GroupManager, Display, CourseManager, FileManager ... some of these are already very usable (Display, GroupManager, Database), others are still very small or specific.

The main_api was not changed to that new convention yet. Almost every script calls api_xxx functions, so it would be time consuming to change all this. It would probably be useful to do so, but I can't recall having discussed this yet.

Before the creation of the Database and Display libraries, we already added several database and display functions to the main API. Most of them should indeed move towards the specific libraries.

Especially the api_display_xxx_message functions should go. However, to avoid breaking the code we can built in a grace period, where the functions become "deprecated", and take them out only after that period.

File structure

The following code folders contain scripts important for using the API:

• inc folder, short for include
• inc/lib (library) - this contains the actual function libraries
• inc/conf (configuration)

Recent new or improved libraries

The most recent new or improved code library additions are

• main_api.lib.php (older name was claro_main.lib.php)
• database.lib.php
• display.lib.php
• course.lib.php
• groupmanager.lib.php (older name was group.inc.lib.php)

In short, the number of good working API functions is increasing. Most of these are new, and not based on functions from the older Claroline environment on which Dokeos is based.

For example, there is a general function to display the tool title; there is a function to show a [student view / course manager view] option, to show an html dialog box. There are several database functions to get table names, execute common, queries...

Create API functions while you develop

If you work on Dokeos, and need a query that returns e.g. the properties of a group, you should add a function getGroupProperties(necessary parameters) to the group.inc.lib.php and call that function. It's a bit more work in the beginning, but it will make your code smaller and easier to maintain, it also means there is only one place to change the query if it needs changing  no more updating 700 copies of the same query.