Создание модулей на основе DataTable

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

Мы создадим модуль testimonials, позволяющий добавлять, редактировать и удалять отзывы. Со времен создания базового модуля DataTable, подобное стало очень легко реализовывать.

Файлы модуля

Во-первых нам надо создать папку testimonials в разделе модулей /system/module. Затем в него положить файл index.php, который будет содержать информацию о модуле. Так же, необходимым условием является создание файла локализации для модуля. Для этого в папке /system/language/ru создадим файл module_testimonials.php.

Локализация модуля

В файле локализации для нашего языка вставим следующие строки:

<?php return array (
  'module_testimonials' => 'Отзывы',
);

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

<?php return array (
  'module_testimonials' => 'Отзывы',
  'name' => 'Имя',
  'photo' => 'Фото',
  'text' => 'Отзыв',
);

И, соответственно для английского языка, в папке /system/language/en

<?php return array (
  'module_testimonials' => 'Testimonials',
  'name' => 'Name',
  'photo' => 'Photo',
  'text' => 'Text',
);

Код модуля

После создания всех файлов, откройте index.php модуля и вставьте следующий код:

<?php
class TestimonialsController extends DataTable{
	public $name = 'testimonials';
	public $structure = array(
		'name' => array(
			'label' => 'Имя',
			'type' => 'string',
			'def' => 'TEXT NOT NULL',
			'visible' => true,
			'attr' => 'class="form-control" required'
		),
		'image' => array(
			'label' => 'Фото',
			'type' => 'string',
			'def' => 'TEXT NOT NULL',
			'visible' => false,
			'attr' => 'class="form-control field-image"'
		),
		'text' => array(
			'label' => 'Отзыв',
			'type' => 'textarea',
			'def' => 'TEXT NOT NULL',
			'visible' => true,
			'attr' => 'class="form-control ckeditor"'
		)
	);
}

Каждый модуль SyDES, это один класс с названием вида "НазваниемодуляController", расширяющий класс Controller, или в нашем случае расширяющий базовый модуль DataTable. Обратите внимание, что название класса всегда начинается с большой буквы.

Первое обязательное свойство, $name, содержит в себе название модуля в нижнем регистре, как и имя папки. На основе его создается таблица, а так же ссылки в админке.

Второе обязательное свойство, $structure, содержит в себе структуру создаваемой таблицы и свойства полей. Во время работы модуля, к этой структуре добавляются еще 2 поля, ID и статус, так что нет необходимости их указывать.

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

label - Заголовок поля, может быть любым словом. В случае мультиязычности, здесь нужно указать ключ для перевода: name, photo или text.

type - Тип поля. Может быть одним из следующих:

select (требует элемент list)
checkbox (требует элемент list)
radio (требует элемент list)
yesNo
string
textarea

def - Описание столбца в базе данных. Поскольку используется SQLite3, то выбор можно можно ограничить между TEXT NOT NULL и INTEGER

visible - Указывает, отображать ли это поле в таблице, в списке элементов

attr - Атрибуты для html-тега, вроде класса, id или data- атрибутов

list - Дополнительный элемент массива, содержащий простой или ассоциативный массив доступных вариантов для выбора

Обратите внимание, что в атрибутах можно указать особые классы, вроде field-date, field-image, field-file, field-folder и ckeditor, чтобы добавить особых свойств полям.

Кастомные шаблоны

С версии 2.5.1 появилась возможность указывать свои шаблоны для списка элементов и формы редактирования без необходимости править контроллер. Достаточно в разделе модуля создать папку view и в нее залить файлы index.php или form.php соответственно и получить данные из переменной $result

Установка модуля

После указания всех настроек модуля, его можно установить на сайт, как и прочие модули, то есть в разделе Система > Настройки > Модули нажать на кнопку Установить. После этого должна создаться отдельная таблица в базе и он появится в главном меню, в разделе Модули.

Как вывести элементы на сайте

Для работы с таблицами данных на фронте был создан инфоблок datatable. Он содержит 5 параметров:

show - название модуля, данные которого хотим вывести
limit - количество элементов на странице (по умолчанию 20)
order - порядок сортировки элементов (по умолчанию id DESC)
show_pagination - показывать ли пагинацию, если количество элементов больше лимита (по умолчанию 1)
template - собственный шаблон для инфоблока

Примеры вызова:

{iblоck:datatable?show=testimonials} - выведет таблицу из 20 отзывов со всеми столбцами и пагинацией

{iblоck:datatable?show=testimonials&template=my} - отзывы с версткой из выбранного шаблона

{iblоck:datatable?show=testimonials&template=carousel&limit=10&show_pagination=0} - выведет карусельку из 10 последних отзывов

Пример кастомного шаблона my:

<div class="testimonials">
<?php foreach ($result as $item){ ?>
	<div class="item">
		<div class="name"><?=$item['name'];?></div>
		<img src="/cache/img/100_100_c<?=$item['image'];?>" class="pull-left img-circle"?>
		<?=$item['text'];?>
	</div>
<?php } ?>
</div>
<?php if ($args['show_pagination']){
	echo H::pagination($page['fullpath'], $count, $skip, $args['limit']);
} ?>