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

• Maps

В данном разделе будет описано как создавать собственные модули для системы 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 и региональные ukraine.pl,russian.pl и т.д. Если нужно для модуля создать собственные словари они должны размещаться в папке модуля с названиями lng_xxx.pl.

Например:

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

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

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

Для того чтобы сообщить системе что модуль (в нашем примере название модуля 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

$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=%значение селекта%, добавится автоматически

  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 дня)

<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 для объектов имеющих возможность гео привязки можно рисовать карту покрытия

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

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:Коментарии (текст уведомления)