View file mc-master/docs/dev.modules.html

File size: 11.54Kb
<html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Документация по MobileCMS</title>
	<link rel="stylesheet" href="style.css" type="text/css" />
</head>

<body><div class="navheader">
<table width="100%" summary="Navigation header">
	<tr>
		<th align="center">Документация по MobileCMS</th>
	</tr>
	<tr>
		<th align="center">Структура модулей и их разработка</th>
	</tr>
</table>
<hr />
</div>
    
<div class="refsect1">
	<h2>Введение</h2>
	<p class="classname">
		Модули в MobileCMS состоят из 4х основных частей:<br />
		<ul>
			<li>Файл <strong class="command"><b>module.ini</b></strong> - содержит важную информацию о модуле</li>
			<li>Папка <strong class="command"><b>controllers</b></strong> - содержит контроллеры модуля</li>
			<li>Папка <strong class="command"><b>views</b></strong> - содержит шаблоны модуля</li>
			<li>Папка <strong class="command"><b>helpers</b></strong> - содержит хелперы (помощники) модуля</li>
		</ul>
		Также модули могут содержать и другие необходимые для работы файлы и папки.<br />
		<br />
		Рассмотрим структуру модулей более подробно на примере тестового модуля.
	</p>
</div>

<div><br /></div>

<div class="refsect1">
	<h2>module.ini</h2>
	Файл <strong class="command"><b>module.ini</b></strong> содержит важную информацию о модуле, необходимую для его установки. Основные компоненты файла:
	<ul>
		<li><strong class="command"><b>name</b></strong> - название модуля, в названии могут быть только латинские буквы, цифры и знаки подчеркивания, например,  <strong class="command">test</strong> (обязательный пареметр)</li>
		<li><strong class="command"><b>title</b></strong> - отображаемое имя модуля, например, <strong class="command">Тест</strong> (обязательный пареметр)</li>
		<li><strong class="command"><b>admin_link</b></strong> - ссылка на управление модулем в панеле управления, формат как для первого параметра функции <strong class="command">a_url()</strong> (сегменты ссылки), например, <strong class="command">test/admin</strong> (не обязательный пареметр, используется только если есть управление модулем из панели управления)</li>
		<li><strong class="command"><b>description</b></strong> - краткое описание модуля, например, <strong class="command">Тестовый модуль</strong> (не обязательный пареметр)</li>
		<li><strong class="command"><b>author</b></strong> - автор модуля, например, <strong class="command">Ant0ha</strong> (не обязательный пареметр)</li>
		<li><strong class="command"><b>version</b></strong> - версия модуля, например, <strong class="command">0.1</strong> (не обязательный пареметр)</li>
	</ul>
	Пример module.ini:<br />
	<pre class="programlisting">
name = "test"
title = "Тест"
admin_link = "test/admin"
description = "Тестовый модуль"
author = "Ant0ha"
version = "0.1"</pre>
</div>

<div><br /></div>

<div class="refsect1">
	<h2>controllers</h2>
	Папка <strong class="command"><b>controllers</b></strong> содержит контроллеры модуля. Контроллер - это основная часть модуля, где выполняется логика скрипта.<br />
	Рассмотрим примеры простых контроллеров тестового модуля.<br />
	<br />
	Файл <strong class="command"><b>controllers/test.php</b></strong><br />
	<pre class="programlisting">
&lt;?php
/**
* Контроллеры модулей происходят от класса Controller.
* Название контроллера происходит от названия модуля с большой буквы с окончанием _Controller
*/
class Test_Controller extends Controller {
	/**
	* Доступ к контроллеру (укажем 0 чтобы разрешить доступ каждому пользователю)
	*/
	public $access_level = 0;
	
	/**
	* Метод вызываемый по умолчанию
	*/
	public function action_index() {
		# Вызовем главный и единственный метод нашего контроллера
		$this->action_hello_world();
	}
	
	/**
	* Метод выводит "Hello world!"
	*/
	public function action_hello_world() {
		# Ассигнуем переменную для теста модуля
		$this->tpl->assign(array(
			'hello' => "Hello world!"
		));
		
		# Подключаем шаблон нашего метода, шаблон приведен ниже, в описании views
		# Будет подключен файл modules/test/views/default/hello_world.tpl
		$this->tpl->display('hello_world');
	}
}
?&gt;</pre>
	<br />
	Так выглядит простой контроллер нашего тестового модуля, показыающий всем фразу "Hello world!", теперь расмотрим самый простой контроллер нашего модуля для панели управления.<br />
	<br />
	Файл <strong class="command"><b>controllers/test_admin.php</b></strong><br />
	<pre class="programlisting">
&lt;?php
class Test_Admin_Controller extends Controller {
	/**
	* В доступе к контроллеру пропишем 10, т.е. он доступен только админам сайта.
	* Чтобы разрешить доступ и модерам, можно будет прописать 8.
	*/
	public $access_level = 10;
	/**
	* Тема, используемая в контроллере, для админки необходимо указать "admin"
	*/
	public $template_theme = 'admin';
	
	/**
	* Метод вызываемый по умолчанию
	*/
	public function action_index() {
		# Вызовем главный и единственный метод нашего контроллера
		$this->action_hello_admin();
	}
	
	/**
	* Метод выводит "Hello Admin!"
	*/
	public function action_hello_admin() {
		# Ассигнуем переменную для теста модуля
		$this->tpl->assign(array(
			'hello' => "Hello Admin!"
		));
		
		# Подключаем шаблон нашего метода, шаблон приведен ниже, в описании views
		# Будет подключен файл modules/test/views/admin/hello_admin.tpl
		$this->tpl->display('hello_admin');
	}
}
?&gt;</pre>
</div>

<div><br /></div>

<div class="refsect1">
	<h2>helpers</h2>
	Папка <strong class="command"><b>helpers</b></strong> содержит хелперы (помощники) модуля. Это служебные php файлы, помогающие в работе модуля.<br />
	Обычно в helpers модуля присутствуют 2 хелпера - инсталлер и виджет, рассмотрим их более детально.<br />
	<br />
	Файл <strong class="command"><b>helpers/test_installer.php</b></strong> (название файла состоит из названия модуля и окончания <strong class="command">_installer.php</strong>) предназначен для выполнения каких-либо действий во время установки и деинсталляции модуля, если никаких действий не требуется, то этот файл не обязателен.<br />
<pre class="programlisting">
&lt;?php
/**
* Название класса инсталлятора также состоит из названия модуля и окончания _installer
*/
class test_installer {
	/**
	* Метод для установки модуля
	*/
	public static function install(&$db) {
		# Создадим таблицу a_test, якобы нужную нашему модулю test
		$db->query("CREATE TABLE`a_test` (
			`item_id` INT NOT NULL AUTO_INCREMENT PRIMARY KEY ,
			`item` VARCHAR( 30 ) NOT NULL
			) ENGINE = MYISAM ;
		");
	}
	
	/**
	* Метод для удаления модуля
	*/
	public static function uninstall(&$db) {
		$db->query("DROP TABLE a_test");
	}
}
&gt;</pre>

В инсталляторе можно не только создавать/удалять таблицы, но так же и создавать/удалять файлы и папки, добавлять правила роутинга, события и т.д.<br />
<br />
	Файл <strong class="command"><b>helpers/test_widget.php</b></strong> (название файла состоит из названия модуля и окончания <strong class="command">_widget.php</strong>) предназначен для вывода какой-либо информации на главную страницу сайта.<br />
<pre class="programlisting">
&lt;?php
/**
* Название класса виджета также состоит из названия модуля и окончания _widget
*/
class test_widget {
	/**
	* Показ виджета
	*/
	public static function display($widget_id) {
  		return 'Это виджет тестового модуля&lt;br /&gt;';
	}
	
	/**
	* Настройка виджета
	*/
	public static function setup($widget) {
		a_notice('Данный виджет не требует настройки', a_url('index_page/admin'));
	}
}
&gt;</pre>
<br />
Виджет может быть намного сложнее, выводить динамическую информацию и иметь более сложные настройки, для примера можете посмотреть виджет модуля загрузок в <strong class="command">modules/downloads/helpers/downloads_widget.php</strong> вашей копии MobileCMS<br />
<br />
Также хелперы модулей могут (и это очень рекомендуется) содержать частоиспользуемые методы (функции) в модуле, для примера взгляните хелпер модуля смайлов <strong class="command">modules/smiles/helpers/smiles.php</strong>
</div>

<div><br /><br /></div>

<div class="navfooter"><hr />
	<table width="100%" summary="Navigation footer">
		<tr>
			<td width="40%" align="left"><a href="dev.general_functions.html">Пред</a></td>
			<td width="20%" align="center"><a href="index.html">На уровень выше</a></td>
			<td width="40%" align="right"><a href="dev.module_main.html">След</a></td>
		</tr>
		<tr>
			<td width="40%" align="left" valign="top">Главные методы ядра</td>
			<td width="20%" align="center">Содержание</td>
			<td width="40%" align="right" valign="top">Методы модуля main</td>
		</tr>
	</table>
</div>
    
</body>
</html>