Creating of modules based on DataTable

The aim of this tutorial is to demonstrate how to create a most basic module for data management, as well as display the result on the site.

We are going to develop a testimonials module, that allows you to add, edit, and delete testimonials. Since the creation of the base module DataTable, such has become very easy to implement.

Module files

Firstly, we will need to create the testimonials folder inside the modules directory /system/module. Then put the file index.php that contains information about the module. Also, it is indispensable to create a file for the localization of the module. To do this, create a file module_testimonials.php in a folder /system/language/en.

Localization of the module

In the location file for our language, insert the following lines:

<?php return array (
  'module_testimonials' => 'Testimonials',
);

If you have assumed a multilingual admin panel, you can create these files for other languages in the neighboring directories. But then the array will need to add translations for the labels, such as:

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

And therefore for the Italian language, in folder /system/language/it

<?php return array (
  'module_testimonials' => 'Testimonianze',
  'name' => 'Nome',
  'photo' => 'Foto',
  'text' => 'Testo',
);

Module source code

After creating all the files, open the index.php of the module and insert the following code:

<?php
class TestimonialsController extends DataTable{
	public $name = 'testimonials';
	public $structure = array(
		'name' => array(
			'label' => 'Name',
			'type' => 'string',
			'def' => 'TEXT NOT NULL',
			'visible' => true,
			'attr' => 'class="form-control" required'
		),
		'image' => array(
			'label' => 'Photo',
			'type' => 'string',
			'def' => 'TEXT NOT NULL',
			'visible' => false,
			'attr' => 'class="form-control field-image"'
		),
		'text' => array(
			'label' => 'Testimonial',
			'type' => 'textarea',
			'def' => 'TEXT NOT NULL',
			'visible' => true,
			'attr' => 'class="form-control ckeditor"'
		)
	);
}

Each SyDES module is a class with the name like "ModulenameController" extends the class Controller, or in our case, extends the base module DataTable. Please note that the name of the class always begins with a capital letter.

The first required property, $name, contains the module name in lower case, as well as the folder name. Based on his table is created, as well as links in the admin.

The second required property, $structure, contains the structure of the table and field properties. During operation of the module, this structure adds two fields, ID and status, so there is no need to specify them.

In the key of the array specifies the name of the field, it is also the name of a column in the table.

label - Field label, may be any word. In the case of multi-language, here you need to specify the key for translation: name, photo or text.

type - Type of field. Perhaps one of the following::

select (requires list)
checkbox (requires list)
radio (requires list)
yesNo
string
textarea

def - A column definition in the database. As used SQLite3, the choice may be possible to limit between TEXT NOT NULL and INTEGER

visible - It indicates whether to display the field in the table in the list of elements

attr - Attributes for html tag like class, id, or data- attributes

list - An additional element of the array that contains a simple or an associative array of options available for selection

Note that in attributes you can add specific classes, such as field-date, field-image, field-file, field-folder and ckeditor, to add special properties to fields.

Custom templates

Since version 2.5.1 added the ability to make custom templates for the elements and the edit form without having to edit the controller. Just create folder view in the module directiory and upload files index.php or form.php respectively, and receive data from the $result variable

Module installation

After specifying all the settings of the module, it can be installed on site, as well as other modules, ie in the section System > Settings > Modules click to button Install. After this should create a separate table in the database and it will appear in the main menu, under Modules.

How to display the elements on the site

To work with data tables at the front was created information block datatable. It contains 5 parameters:

show - the name of the of the module, the data of which we want to bring
limit - number of items per page (default 20)
order - sorting order for items (default id DESC)
show_pagination - whether to show pagination, if the number of elements exceeds the limit (default 1)
template - own template for the iblock

Samples:

{iblоck:datatable?show=testimonials} - displays a table of the 20 testimonials with all columns and pagination

{iblоck:datatable?show=testimonials&template=my} - testimonials with layout of the selected template

{iblоck:datatable?show=testimonials&template=carousel&limit=10&show_pagination=0} - displays a carousel of the last 10 testimonials

Example of custom template 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']);
} ?>