Модули системы

В данном разделе будет описано как создавать собственные модули для системы Abills.

Структурная схема системы.

Начало создания модуля.

Все модули системы находятся в папке /usr/abills/Abills/modules/

Название модуля лучше всего делать с заглавной буквы New_module

Название модуля модуля не должно быть длиннее 14 символов

В каталоге модуля обязательно должны находится 2 файла: webinterface и config.

webinterface - Библиотека функций модуля

config            - Конфигурационный файл модуля

Включение модуля в конфигурационном файле: libexec/config.pl

@MODULES = (
  'New_module'
);

Примеры работы с файлом config

%FUNCTIONS_LIST -  список доступных функций в интерфейсе администратора. Каждая функция объявляется отдельной переменной хеш маcива и имеет следующую структуру. 

Рассмотрим пример:

%FUNCTIONS_LIST = ( 
  "01:0:Главное меню модуля:null:"                                 => 5,
  "02:1:Главная функция:main_function:"                            => 5, 
  "10:1:Вторая функция:null"                                       => 5, 
  "11:10:1 вложенная во вторую функцию:second_main_function:"      => 5, 
  "12:10:2 вложенная во вторую функцию:second_second_function:UID" => 5, 
);

%FUNCTIONS_LIST -  список доступных функций в интерфейсе администратора. Каждая функция объявляется отдельной переменной хеш масива и имеет следующую структуру. 

Рассмотрим пример:

"12:10:2 вложенная во вторую функцию:second_second_function:UID" => 5,

Пример работы с файлом webinterface

В данном файле должны располагаться функции модуля, которые вы прописали в файле config.

use strict;
use warnings;



#**********************************************************
=head2 main_function() - Описание функции

=cut
#**********************************************************
sub main_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 second_main_function() - Описание функции

=cut
#**********************************************************
sub second_main_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 second_second_function() - Описание функции

=cut
#**********************************************************
sub second_second_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 client_main_function() - Описание функции

=cut
#**********************************************************
sub client_main_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 daily_periodic_function() - Описание функции

=cut
#**********************************************************
sub daily_periodic_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 monthly_periodic_function() - Описание функции

=cut
#**********************************************************
sub monthly_periodic_function {
  my ($attr) = @_;
  return 1;
}

#**********************************************************
=head2 reports_function() - Описание функции

=cut
#**********************************************************
sub reports_function {
  my ($attr) = @_;
  return 1;
}

1;

Работа с языковыми файлами.

По умолчанию система использует файлы language/english.pl и региональные ukrainian.pl, russian.pl и т.д. Если нужно для модуля создать собственные словари они должны размещаться в папке модуля с названиями lng_xxx.pl.

Например:

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

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

$lang{PAY_ADD}='Начать оплату';

Создание быстрых отчётов для первой страницы

На первой страницы системы можно разместить несколько быстрых отчётов. Какие отчёты размещать определяет администратор в меню профайл. Ниже будет описано как создать быстрый отчёт в созданном вами модуле.

Для того чтобы сообщить системе что модуль (в нашем примере название модуля New_module) имеет быстрые отчёты нужно создать функцию

под названием New_module_start_page Данная функция должна возвращать ссылку на ассоциированный массив значений в котором ключ это название функции выводящей быстрое меню а значение её описание.

Пример:

sub new_module_start_page {
  my ($attr) = @_;

  my %START_PAGE_F = ('new_module_sp_report' => 1 );

  return \%START_PAGE_F;
}

создаём сам отчёт

sub new_module_sp_report {

  print "Hello, World";

}

Работа с базой данных

Для разделения работы с базой и элементов визуализации все функции работы с базой помещаются в каталог /usr/abills/Abills/[название базы данных]
Для СУБД mysql это /usr/abills/Abills/mysql.

Функция добавления

query_add($table, $values, $attr) - Добавление данных в базу.

Аргументы:

Дополнительные атрибуты:

Пример:

$self->query_add( 'table_name', {COL_NAME_1 => VALUE_1, 
                                COL_NAME_2 => VALUE_2, 
                                COL_NAME_3 => VALUE_3}, {REPLACE => 1} );

Функция удаления

query_del($table, $values, $extended_params, $attr) - удаление данных из базы.

Аргументы:

Дополнительные параметры:

Пример:

$self->query_del('table_name', {COL_NAME => VALUE});

$self->query_del('table_name', {}, {CLEAR_TABLE => 1});

Функция изменения

changes2($attr) - вносит изменения в базу

Параметры:

Пример:

$self->changes2(
    {
      CHANGE_PARAM => 'ID',
      TABLE        => 'TABLE_NAME',
      DATA         => {COL_NAME_1=>VALUE_1, COL_NAME_2 => VALUE_2}
    }
  );

Другие команды в базу

query2($query, $type, $attr) - выполнение своих команд в базу

Параметры:

Дополнительные параметры:

Пример:

$self->query2(
  "SELECT * FROM table_name;",
  undef,
  {}
);

HTML.pm

Модуль для вывода HTML контента

Шаблоны

Для визуализации используется система шаблонов

отображение глобального шаблона системы c названием form_chg_tp. Глобальные шаблоны системы размещаются в каталоге Abills/main_tpls/.

print $html->tpl_show(templates('form_chg_tp'), $attr, { ... });

Функция templates() ищет шаблон в каталоге кастомных шаблонов а также сморит есть ли языковой шаблон данного типа.

параметр $attr передаёт обработчику шаблонов ссылку на массив значений маркеров переменных

отображение шаблона для модуля (шаблоны модулей сохраняются в каталоге Abills/module/[module_name]/templates)

print $html->tpl_show(_include('dv_users_search', 'Dv'), $attr);

Функция _include() загружает шаблон dv_users_search для модуля DV

Дополнительные возможности

Дополнительные возможности

Проверка значения input на соответствие шаблону

Если указать атрибут data-check-for-pattern=«RegExp», где RegExp - JavaScript шаблон, то при вводе значение будет проверяться на соответствие патерну.
Если значение не соответствует патерну, родительскому элементу добавляется класс has-error. Текст label и рамка input меняют цвет на красный.

Если значение соответствует шаблону, клас has-error снимается.
Шаблоны JavaScript тут: http://javascript.ru/RegExp\

Для полей ввода IP-адресов, достаточно добавить класс ip-input. Автоматически добавится патерн для проверки коректности IPv4 или IPv6 адреса.

Ввод значения в один input при доступных нескольких

Добавить атрибут data-input-disables=%ID% в <input> (<select>, <input type='checkbox'>)
При вводе значения, удаляет значение в <input id='%ID%'> и добавляет свойство disabled.

Если указать id тега <fieldset>, отключит все <input> внутри тега.

Можно указать несколько Id через запятую (без пробелов).

Обратное поведение ( включить поле ввода по значению ), можно используя атрибут data-input-enables=%ID%

Всплывающая подсказка при наведении мыши

Добавьте элементу атрибут data-tooltip для отображения всплывающей подсказки.
Значением атрибута можут быть любой HTML код.
Аттрибут data-tooltip-position управляет позицией tooltip'а, возможные значения left, right, top, bottom.

Решение проблемы с checkbox

По умолчанию, браузер не отправляет неотмеченый checkbox, иногда это может быть неудобно.
Если checkbox используется в форме, где нужно отсылать неотмеченное состояние, укажите аттрибут data-return='1'

AJAX загрузка файла

Шаблон модального окна

Select с автотправкой

Автоматически отправляет форму после изменения. Доступны 2 варианта

• Отправка GET по указаному линку. &COLORS=%значение селекта%, добавится автоматически

  SELECT с отправкой

   my $colors_css = $html->form_select( 'COLORS',
      {
        SELECTED => $admin->{SETTINGS}->{COLORS} || q{},
        SEL_ARRAY => \@names,
        NO_ID    => 1,
        SEL_OPTIONS => { '' => $lang{DEFAULT} },
        EX_PARAMS => "data-auto-submit='index=$index&AWEB_OPTIONS=1'"
      }
    );

  • Отправка формы, в которой находится <select>

 my $custom_select = $html->form_select( 'CUSTOM',
    {
      SELECTED => $FORM{CUSTOM} || q{},
      SEL_ARRAY => \@options,
      NO_ID    => 1,
      SEL_OPTIONS => { '' => $lang{NO} },
      EX_PARAMS => "data-auto-submit='form'"
    }
  );

Условное скрытие/показ элемента

Доступно через аттрибут data-visible.
Любое значение интерпретируемое в JS как false добавит display : none
Любое значение интерпретируемое в JS как true добавит display : block

Отображение даты в человекочитаемом формате

Отобразить время от/до наступления даты (3 часа назад, 5 дней назад, Через 3 дня)

Отображение даты в человекочитаемом формате

Отобразить время от/до наступления даты (3 часа назад, 5 дней назад, Через 3 дня)

<span class='moment-insert' data-value='YYYY-MM-DD hh:mm:ss'></span>

Отобразить временной интервал (3 часа, 5 дней)

<span class='moment-range' data-value='ss'></span>

Подтверждение действий в кабинете пользователя

Есть возможность добавить в кабинете пользователя подтверждение действий паролем. Для этого необходимо добавить форме класс pswd-confirm. При попытке сабмита формы с этим классом, откроется модальное окно для ввода пароля. Введенный пароль добавится к данным формы. (работает при включенной опции $conf{user_confirm_changes}=1;)

result_former

Функция формирование результирующей таблицы используя SQL, XML JSON или HASH данные

 my ($table, $list) = result_former({
     INPUT_DATA      => $Dv,
     FUNCTION        => 'list',
     BASE_FIELDS     => 0,
     DEFAULT_FIELDS  => 'LOGIN,FIO,DEPOSIT,CREDIT,TP_NAME,DV_STATUS',
     FUNCTION_FIELDS => 'form_payments,dv_stats, del, change',
     EXT_TITLES      => {
       'ip'          => 'IP',
       'netmask'     => 'NETMASK',
       'speed'       => $_SPEED,
       'port'        => $_PORT,
       'cid'         => 'CID',
       'filter_id'   => 'Filter ID',
       'tp_name'     => "$_TARIF_PLAN",
       'dv_status'   => "Internet $_STATUS",
       'dv_status_date' => "$_STATUS $_DATE",
       'online'      => 'Online',
       'dv_expire'   => "Internet $_EXPIRE",
       'dv_login'    => "$_SERVICE $_LOGIN",
       'dv_password' => "$_SERVICE $_PASSWD"       
         },
     TABLE           => {
       width      => '100%',
       caption    => "Internet - $_USERS",
       qs         => $pages_qs,
       ID         => 'INTERNET_USERS_LIST',
       header     => $status_bar,
       EXPORT     => 1,
       MENU       => "$_ADD:index=" . get_function_index('dv_wizard_user') . ':add' . ";$_SEARCH:index=$index&search_form=1:search",
     },
     MAKE_ROWS    => 1,
     SEARCH_FORMER=> 1,
     MODULE       => 'Dv',
     TOTAL        => 1
  });

Карта покрытия

Если у системе подключён модуль Maps (old) для объектов имеющих возможность гео привязки можно рисовать карту покрытия

Для включения опции карты параметр

MAP         => 1,

Также можно указать информацию для отображения на сводных таблицах

MAP_FIELDS  => 'ID,CLIENT_ID,SUBJECT'

И фильтр обработки параметров полей сводной таблицы

MAP_FILTERS => { id     => 'search_link:msgs_admin:UID,chg={ID}',
                      }

При отображении элементов на карте система устанавливает цвета точек гео локации

Графики

$html->make_charts(
      {
        PERIOD        => $graph_type,   #Период графика, 
        DATA          => \%DATA_HASH,
        AVG           => \%AVG,
        TRANSITION    => 1,
        TYPE          => {column_name => 'type' },
        X_LINE        => [ $val ], 
        X_TEXT        => [ $val ],
        DATA          => { cols_name => [ $val ] };
        OUTPUT2RETURN => 1,
      }
    );

PERIOD

Период и тип графиков

week - недельный с пн по пт
year - Год
month - месячный от 1 до 31 числа
hour - почасовой график 0 до 24 часов
pie - круг

AVG

Усреднённые значения

TRANSITION

Анимация визуализации

TYPES
⇒ {column_name ⇒ 'type' },

тип отображения значений поля на графике

column_name - название колонки
type - тип:

X_LINE
⇒ [ $val ],

Текст X оси

X_TEXT
⇒ [ $val ],

Текст X оси

DATA

⇒ { cols_name ⇒ [ $val ] };

массив значений
cols_name - название колонки
$val - список значений для отображения

Если задана $attr→{PERIOD}, то в зависимости от значения, формируются категории (X_TEXT) и корректируется длина массива (отрезается 0-ой индекс).

OUTPUT2RETURN
отдать значение в STDO

Полезные функции WEB интерфейса

• get_function_index('form_info_fields')

Получить index функции.

Maps

Документация разработчика Maps

JavaScript

Документация по JS библиотекам

Статические значения qindex

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

• 100000 - QRCode former

• 100001 - msgs_register_push_client

• 100002 - form_events (Клиентский интерфейс)

Подсказки к шаблонам

Начиная с версии 0.77.66 можно заполнять дополнительные подсказки для полей шаблона.
При использовании новой схемы отображения шаблона

$html->tpl_show('', {
  VAR1 => 'VAL1',
},
{
  TPL    => 'module_entity',
  MODULE => 'Module',
  HELP   => 1
});

Если задан ключ HELP ⇒ 1, к шаблону добавится контент файла module_entity_help.tpl, который будет обработан на странице.
Формат файла шаблона подсказок: ID:комментарий.
Пример:

MODULE:Имя модуля
EXTRA:Ссылка для получения доп. информации
COMMENTS_id:Коментарии (текст уведомления)