Делаем свой модуль, часть 1

2152
Здравствуйте.
Этим постом мы начнем серию публикаций о том, как делаются собственные модули и
компоненты для InstantCMS. От читателя требуется базовое знание PHP и MySQL.

Ставим цели

В качестве примера создадим компонент "Гостевая книга" и модуль
"Последние записи" для него. В конечном итоге мы хотим получить:

- Таблицы в БД для хранения записей гостевой книги
- Возможность вывода случайных записей через модуль
- Возможность для зарегистрированных пользователей добавлять и просматривать записи гостевой книги через компонент

Компонент будет расчитан только на зарегистрированных пользователей,
чтобы показать как создавать ограничения.

Внимание: Во всех примерах кода нужно заменить косые кавычки на апострофы.
Или проще скачать весь пример одним архивом (ссылка в конце поста).

Создаем таблицу в БД

Чтобы было проще, давайте сразу создадим таблицу с несколькими сообщениями гостевой книги.
Для каждой записи нам потребуется 4 поля - ID, дата, автор и текст сообщения.

SQL-запрос создаст нужную нам таблицу:

Код PHP:
CREATE TABLE `cms_guestbook` (
`id` INT NOT NULL AUTO_INCREMENT ,
`pubdate` DATETIME NOT NULL ,
`user_id` INT NOT NULL ,
`content` VARCHAR( 255 ) NOT NULL ,
PRIMARY KEY ( `id` )
);

Таблицу называем "cms_guestbook", по аналогии с другими таблицами в БД InstantCMS.
Поле id создаем с флагом AUTO_INCREMENT, чтобы при вставке записей их порядковые
номера вычислялись автоматически базой данных.

Обратите внимание, что поле user_id мы делаем с типом INT, т.е.
хранить авторов сообщений мы будем в виде чисел. Каждое такое число будет указывать
на номер пользователя в системной таблице cms_users.

Теперь давайте заполним таблицу несколькими записями. Будем считать, что все эти
записи оставил администратор (т.е. пользователь с номером 1):

Код PHP:
INSERT INTO 
 `cms_guestbook` (`pubdate`, `user_id`, `content`) 
VALUES 
 (NOW(), 1, 'Первое сообщение гостевой книги'),
 (NOW(), 1, 'Второе сообщение гостевой книги'),
 (NOW(), 1, 'Третье сообщение гостевой книги');

Поле id при вставке не передаем, оно будет присвоено автоматически
(1, 2 и 3 соответственно). В качестве даты подставляем функцию NOW(),
которая будет заменена на текущую дату сервера.

Теперь сообщения хранятся в базе и мы можем написать модуль, который
будет показывать случайное сообщение из гостевой книги.

Пишем модуль

Пусть наш модуль будет называться "Случайное в гостевой" и
иметь краткое название mod_guestbook.

Каждый системный модуль InstantCMS находится в отдельном файле внутри собственной папки.

Перейдите в папку modules в корне сайта и создайте в ней папку mod_guestbook.
В папке mod_guestbook создайте файл module.php.

В файл module.php помещаем код модуля:

Код PHP:
<?php
function mod_guestbook($module_id){	

		//Формируем запрос:
		$sql = "SELECT DATE_FORMAT(g.pubdate, '%d/%m/%Y') as pubdate,
						g.content as content,
						u.id as author_id,
						u.nickname as author_name
				FROM cms_guestbook g, cms_users u
				WHERE g.user_id = u.id
				ORDER BY RAND()";
		
		//Выполняем запрос:
		$result = @mysql_query($sql);
		
		//Если не произошла ошибка:
		if(!mysql_error()){
				
			//Получаем данные из ответа БД:
			$record = mysql_fetch_assoc($result);
			
			//Выводим текст сообщения:
			echo '<p>'.$record['content'].'</p>';
			
			//Формируем ссылку на автора:
			$author_link = '<a href="/users/0/'.$record['author_id'].'/profile.html">'.$record['author_name'].'</a>';
			
			//Выводим дату и ссылку на автора:
			echo '<p>'.$record['pubdate'].' - '.$author_link.'</p>';						
			
			//Разрешаем показать модуль:
			return true;
			
		} else {
		
			//Если данные из БД не были получены,
			//то запрещаем показывать модуль:
			return false;
			
		}
						
}
?>

Модули InstantCMS оформляются в виде функций, название которых совпадает
с названием модуля (mod_guestbook в нашем случае).

Внутри функции происходит вся работа модуля. Сначала мы составляем запрос
к двум таблицам: cms_guestbook и cms_users. Из первой мы хотим получить текст и дату
сообщения, а из второй - никнейм автора. Для связи этих таблиц нам и нужно поле user_id
в таблице с записями гостевой.

В запрос добавлена строка ORDER BY RAND() для того, чтобы получить случайную запись из таблицы cms_guestbook.

Если запрос к базе происходит успешно, модуль выводит сообщение на экран.

Добавляем модуль в систему

Для того чтобы наш новый модуль заработал и начал отображаться в админке, нужно зарегистрировать его в нашей базе данных.
InstantCMS получает сведения о модулях из таблицы cms_modules, в которую нам и нужно вставить строчку.

Выполните SQL-запрос:

Код PHP:
INSERT INTO `cms_modules` ( `id` , `position` , `name` , `title` , `is_external` , `content` , `ordering` , `showtitle` , `published` , `user` , `config` , `original` , `css_prefix` , `allow_group` , `cache` , `cachetime` , `cacheint` )
VALUES 
 ('', 'right', 'Случайное в гостевой', 'Случайное в гостевой', '1', 'mod_guestbook', '1', '1', '1', '0', '', '1', '', '-1', '', '1', 'HOUR');

Для своих модулей в будущем вы можете использовать точно такой же запрос,
просто заменив в нем названия "Случайное в гостевой" и "mod_guestbook" на собственные.

Учтите, что если вы захотите установить этот модуль на другую систему вам
потребуется выполнить все приведенные SQL-запросы и там.
Одного копирования файлов будет недостаточно.

После совершения всех описанных действий вы можете перейти в панель управления
сайтом, в раздел "модули" и включить наш новый модуль, привязав его к меню.

В следующих статьях мы усложним созданный нами сегодня модуль, добавив к нему
возможность настройки через админку и вывод на экран через шаблонизатор Smarty.

Скачать архив с примером
Разделение прав администраторов
Теги: модули
Комментарии (15)
Madmax 28 февраля 2009 в 14:14 0
УРА! Заработало - то - чего так не хватало!
Suslik 5 декабря 2010 в 19:38 -1
странно что функции работы с базой не вынесены в API ядра, а есть хелп по API CMS?
Fuze 5 декабря 2010 в 23:45 +1
Опубликовано: 645 дней назад (28-02-2009 13:08)

как вы считаете, многое изменилось с того времени???

загляните в код текущей версии для начала.
0 28 февраля 2009 в 21:03 0
Очень полезная публикация! :)
0 28 февраля 2009 в 23:29 0
Очень важная статья для всех пользователей InstantCMS!
0 1 марта 2009 в 00:05 0
Так-то всё понял, только не понял, а как попасть в саму гостевую? scratch
lezginka.ru 2 марта 2009 в 15:46 0
как сказал один мой знакомы :   "...да что тут не понять и ребенку все ясно", как прослушал вводную часть "Теоремы Элера", потом добавил: "только объясните мне ... как в карамель повидло попадает, никак не могу понять".
вывод:
приводить примеры нужных модулей , к примеру: модуль "профиль пользователя" - с возможность администрирования полей и т.д.
--------------
хотя и на том спасибо.
InstantCMS 2 марта 2009 в 16:43 0
2 lezginka.ru

Обратите внимание на слова "часть 1" в заголовке поста...
И мы не ставим задачу описать создание "нужного" модуля или компонента, т.к.
понятия о нужности у каждого свои. Наша задача - только показать суть технологии.
0 25 апреля 2009 в 16:17 0
А есть гостевая для Instant ? выложите плизики
0 27 апреля 2009 в 13:32 0
Не плохо было бы включить в след. версию эту гостевую книгу, как компонент, ну и модуль соответственно!
0 19 мая 2009 в 01:27 0
Спасибо, толковая статья!

Но неплохо бы еще объяснить как добавляются записи в базу из комментариев.
0 25 июня 2009 в 18:08 0
Спасибо за статью! Но больше интересует статьи о компонентах. Будет ли допустим продолжение "делаем компонент гостевая книга"?
0 22 октября 2009 в 21:15 0
А почему не отображается в админке? Как его запустить?
Fuze 22 октября 2009 в 22:49 0
esterny, будь внимательна,
Администратор:
Наша задача - только показать суть технологии.
0 24 октября 2009 в 16:09 +1
Даешь вторую часть!