DotProject — lack of documentation sindrom

Поведать я хочу об ужасном. Об ужасном заболевании многих cms — тотальном отсутствии документации. С этой проблемой я столкнулся не далее, как на прошлой неделе — именно тогда я получил задание от руководства написать модуль для системы управления проектами DotProject (текущая версия — 2.1.1). Итак, скальпель, свет! Приступим к вскрытию тела.
Читаем подробную Ниже очень много букаф! инструкцию:

В двух словах о том, что за зверь попал ко мне на разделочный стол.
Система управления проектами, workspace любой современной компании. Именно она позволяет узнать что, надо сделать и до какого срока. Именно она позволяет хлопнуть перед носом начальства или менеджера отчётами за прошедший месяц и требовать премию за н-цать переработанных часов. Ну и не стоит, конечно, забывать, что централизованное планирование работа над проектами помогает максимально эффективно пользоваться людскими ресурсами, составлять графики работ и контролировать производственный процесс.
Практически все мы здесь — ойтишнеги. А значит извращенски подходим даже к менеджменту заданий — используем для этого web-приложение. Одним из вариантов, open-source кстати говоря, является и рекомый DP.
Ну, с преамбулами покончено, перейду к сути.
Для разделки надо иметь собственно тело. Ну, и крайне желательно иметь для него адекватный перевод на родную мову. После скачивания и установки (нам крайне рекомендуют воспользоваться apache, т.к. всякий намек на windows вызывает по словам разработчика стойкую аллергическую реакцию. Ну что же, воспользуемся denwer-ом) и, наконец, приступим.
На самом деле документации по составлению модулей действительно нет. Нет ни примеров, ни ку/ро.водств. Конечно, есть wiki проекта, а там есть рефернс проекта. И, конечно есть source. Именно сорс, как ни странно стал моей опорой и надеждой.
Первое и самое главное — чтобы не потерять функционал нужно помнить, ху из ху и не изобретать велосипед. Если нам нужен модуль, то нужно взять готовый пример. Я выбрал для себя модуль links, вы можете выбрать что-то другое. Не буду замороачивать вас созданием полноценного суб-приложения. Ограничусь лишь необходимым для старта минимумом (именно его отсутствие увеличило срок разработки на ~10 часов).
1) Модуль располагается в папке modules/<имя модуля>
2) Каждый файл в нашей директории должен начинаться с кода

if (!defined('DP_BASE_DIR')){
    die('You should not access this file directly.');
}

— это защитит его от внешнего доступа.
3) Модули подключаются к главному файлу после инициализации путём обработки в index.php $_GET-переменных (?m=<имя модуля>&a=<действие>)
По-умолчанию используется $dPconfig['default_view_m']; (модуль, назначенный в конфигурации).
Если быть более точным, то за это отвечает участок кода в файле /index.php

if (! isset($_GET['m']) && !empty($dPconfig['default_view_m'])) {
  	$m = $dPconfig['default_view_m'];
	$def_a = !empty($dPconfig['default_view_a']) ? $dPconfig['default_view_a'] : $def_a;
	$tab = $dPconfig['default_view_tab'];
} else {
	// set the module from the url
	$m = $AppUI->checkFileName(dPgetCleanParam( $_GET, 'm', getReadableModule() ));
}
// set the action from the url
$a = $AppUI->checkFileName(dPgetCleanParam( $_GET, 'a', $def_a));

Как видно из кода, мы получаем имя модуля и действие. Если действие не определено, то по-умолчанию в систему подключится содержимое файла /modules/<имя модуля>/index.php При этом, если у вас существует класс модуля, то (он должен располагаться по адресу /modules/<имя модуля>/<имя модуля>.class.php). Но оставим классы продвинувшимся пользователям.
4) Разберём наши возможности.

Во-первых прошу заметить, что в системе используется класс абстракции БД — adoDB, документации по которому не в пример больше.
Простейшая конструкция на нём выглядит как:

$q = new DBQuery();
$q->addTable('users', 'u');
$q->addQuery('u.user_id, u.user_username');
$q->addOrder('u.user_username');
$sql = $q->prepare();
$q->clear();
$users = db_loadList( $sql );

и позволяет получить список имен пользователей и соответствующих User_id.
Так же можно пользоваться более простой конструкцией

$sql = 'SELECT * FROM `projects` WHERE `project_id` = '.$projectid;
$project_name = db_exec($sql);
$project_name = db_fetch_assoc($project_name);

, которая позволяет получить информацию более привычным способом.

Во-вторых все сведения о модуле храняться в файле setup.php в директирии модуля. (Останавливаться на этом не буду, достаточно будет изучить содержимое этого файла одного из стандартных модулей.)

В-третьих внимательно посмотрим на содержимое файла index.php в корне сервера.
В глаза сразу бросается строка

// don't output anything. Usefull for fileviewer.php, gantt.php, etc.
$suppressHeaders = dPgetParam( $_GET, 'suppressHeaders', false );

Ура! У нас есть реальная возможность отказаться от системного хеадера и прицепить что-то своё всего лишь передав в адресе параметр &suppressHeaders=1

Используя нижеследующий код, можно проверить права доступа пользователя к конкретному модулю:

// check overall module permissions
// these can be further modified by the included action files
$perms =& $AppUI->acl();
$canAccess = $perms->checkModule(<имя модуля>, 'access');
$canRead = $perms->checkModule(<имя модуля>, 'view');
$canEdit = $perms->checkModule(<имя модуля>, 'edit');
$canAuthor = $perms->checkModule(<имя модуля>, 'add');
$canDelete = $perms->checkModule(<имя модуля>, 'delete');

Больше пока в индексном файле нас не интересует ничего.

5) Используя директивы вида:

require_once( $AppUI->getModuleClass( 'tasks' ) );
require_once( $AppUI->getModuleClass( 'projects' ) );

мы можем подключать различные модули. Не забываем предварительно проверять права доступа к ним.

Ну, на этом быстрый старт можно было бы и закрыть, но для полноты картины приведу небольшой hello world:
helloworld.rar

З.Ы. Собственно, вот и всё. Если вам понадобится какая-нибудь помощь по DOTproject — обращайтесь!