=====Модули системы===== В данном разделе описано как создавать собственные модули для системы. ==== Структурная схема ==== {{:abills:docs:development:modules:abills.png|}} Модуль для системы должны находиться в папке /usr/abills/Abills/modules. Название модуля лучше всего писать с заглавной буквы ''New_module''. В каталоге модуля должно быть обязательно два файла webinterface и config. \\ * **webinterface** - Библиотека функций модуля * **config** - Конфигурационный файл модуля Включение модуля в конфигурационном файле: **libexec/config.pl** @MODULES = ( 'Modulename' ); =====config===== Пример файла: #Iner_ID : Main or Sub or if -1 user menu func list %FUNCTIONS_LIST = ("01:0:$_ICARDS:cards_main:" => 5, "04:1:BRUTE FORCE:cards_bruteforce:" => 5, "05:1:$_ICARDS:cards_main:" => 5, "06:1:$_DILLERS $_TARIF_PLANS:cards_dillers_tp:" => 5, "06:5:$_ADD:cards_add:" => 5, "08:0:$_ICARDS:cards_user_payment:UID" => 2, "09:0:$_ICARDS:cards_report:" => 4, "11:8:$_DILLERS:cards_report_dillers:" => 4, "12:0:$_DILLERS:cards_dillers_list:" => 1, "13:0:$_DILLERS:cards_diller:UID" => 15, ); %USER_FUNCTION_LIST = ("01:0:$_ICARDS:cards_user_payment:" => 0, ); %RESELLER_FUNCTION_LIST = ("01:0:$_ICARDS:cards_reseller_face:defaultindex" => 0, "02:1:$_REPORTS:cards_diller_stats:" => 1 ); %PERIODIC = (daily => [ 'cards_bruteforce_clean' ] ); В данном файле можно объявлять следующие переменные которые влияют на работу и отображение модуля в системе. * **%FUNCTIONS_LIST** Список доступных функций в интерфейсе администратора. Каждая функция объявляется отдельной переменной хеш масива и имеет следующую структуру. Рассмотрим на примере: %FUNCTIONS_LIST = ("01:0:$_ICARDS:cards_main:UID" => 5); В данном примере обявлена одна функция визуализации. ^01 | Номер функции в данном модуле | ^0 | Номер родительской функции. Если 0 (ноль) функция является корневой. Если значение больше нуля то функция располагается в меню под родительской функцией | ^$_ICARDS | Название функции в меню панели управления | ^cards_main | Название фукции которая выполняется при нажатии соответственного меню | ^UID | Дополнительные параметры. Они могут быть и не объявлены. Если объявляются тогда меню показывается только если данные доп параметры присутствуют HTTP запросе. \\ Например ели объявлен параметр UID то данная функция будет отображаться только если в запросе он присутствует. Пример запроса: http://your.host:9443/index.cgi?UID=15 | ^ 5 | Номер корневого каталога в котором разместить меню. Номера корневых меню: \\ 1 - Клиенты \\ 2 - Оплаты \\ 3 - Снятие денег \\ 4 - Отчёт \\ 5 - Настройка \\ 6 - Мониторинг \\ 7 - Поиск \\ 8 - Обслуживание \\ 9 - Профиль | * **%USER_FUNCTION_LIST** - Список функций личного кабинета пользователя. Функции формируются за тем же правилом что и функции интерфейса администратора. * **%RESELLER_FUNCTION_LIST** - Список функций интерфейса реселлера. Интерфейс реселлера появляется только при включении модуля [[abills:docs:modules:multidoms:ru:abills|Multidoms]] * **%PERIODIC** - Список функций которые используются в периодических процессах системы. ОНи вызываются из программы abills/libexec/periodic. \\ В системе доступно несколько видов функций: ^ daily | Дневные переодические функции | ^ monthly | Месячные переодические функции | ^ reports | Функции составления дневные отчётов | пример объявления: %PERIODIC = (daily => [ 'dv_daily_fees', 'dv_users_warning_messages'], monthly => [ 'dv_monthly_fees', 'dv_periodic_logrotate' ], report => [ 'dv_report' ]); **Проверить** \\ дневной периодик /usr/abills/libexec/periodic daily MODULES=[module name] =====webinterface===== В данном файле должны располагаться функции модуля =====Языковые файлы===== По умолчанию система использует файлы **language/english.pl** и региональные ukraine.pl,russian.pl и т. д. Если нужно для модуля создать собственные словари они должны размещаться в папке модуля с названиями lng_xxx.pl. Например: lng_english.pl lng_ukraine.pl lng_russian.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)** - Добавление данных в базу. **Аргументы:** ^ $values | хеш ключей и значений, **например [COL_NAME] => [value]** | ^ $table | название таблицы | ^ $attr | дополнительные атрибуты | **Дополнительные атрибуты:** ^ REPLACE | Меняет команду INSERT на REPLACE | **Пример:** $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)** - удаление данных из базы. **Аргументы:** ^ $table | название таблицы | ^ $values | параметры удаления | ^ $extended_params | расширенные параметры удаления, хеш ключей и значений, **например [COL_NAME] => [value]** | ^ $attr | дополнительные параметры | **Дополнительные параметры:** ^ CLEAR_TABLE | очищается таблицу целиком | **Пример:** $self->query_del('table_name', {COL_NAME => VALUE}); $self->query_del('table_name', {}, {CLEAR_TABLE => 1}); ==== Функция изменения ==== **changes2($attr)** - вносит изменения в базу ^ $attr | параметры, хеш ключей и значений | **Параметры:** ^CHANGE_PARAM | параметр изменения, изначально ID (обязателен)| ^SECOND_PARAM | дополнительный параметр изменения| ^TABLE | название таблицы (обязателен)| ^DATA | новые данные (хеш ключей и значений)| ^EXT_CHANGE_INFO | | ^FIELDS | | ^OLD_INFO | | ^ACTION_ID | | **Пример:** $self->changes2( { CHANGE_PARAM => 'ID', TABLE => 'TABLE_NAME', DATA => {COL_NAME_1=>VALUE_1, COL_NAME_2 => VALUE_2} } ); ==== Другие команды в базу ==== **query2($query, $type, $attr)** - выполнение своих команд в базу ** Параметры: ** ^ $query | запрос | ^ $type | тип запроса, undef - with fetch result like SELECT, do - do query without fetch (INSERT, UPDATE, DELETE) | ^ $attr | дополнительные параметры| ** Дополнительные параметры: ** ^ COLS_NAME | Возвращает ссылку на хеш. Имя колонки как ключ хеша | ^ COLS_UPPER | Сделать ключи большими буквами | ^ INFO | Return fields as objects parameters $self->{LOGIN} | ^ LIST2HASH | Возвращает хеш, вместо листа {KEY=>VAL} | ^ MULTI_QUERY | Мультизапросы (только для INSERT, UPDATE) | ^ Bind | Массив или бинд значений [ 10, 12, 33 ] | ^ DB_REF | Обьект БД. Используется когда работа идет с несколькими ДБ северами | ^ test | Исполняется без запроса. Если исползуется $self->{debug} показывается запрос. | **Пример:** $self->query2( "SELECT * FROM table_name;", undef, {} ); =====HTML.pm===== [[abills:docs:development:modules:html:ru|Модуль для вывода 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%'' в () \\ При вводе значения, удаляет значение в и добавляет свойство ''disabled''. \\ \\ Если указать id тега
, отключит все внутри тега.\\ \\ Можно указать несколько Id через запятую (**без пробелов**).\\ \\ Обратное поведение ( включить поле ввода по значению ), можно используя атрибут ''data-input-enables=%ID%'' \\ === Всплывающая подсказка при наведении мыши === Добавьте элементу атрибут ''data-tooltip'' для отображения всплывающей подсказки.\\ Значением атрибута можут быть любой HTML код.\\ Аттрибут ''data-tooltip-position'' управляет позицией tooltip'а, возможные значения **left**, **right**, **top**, **bottom**.\\ === Решение проблемы с checkbox === По умолчанию, браузер не отправляет неотмеченый checkbox, иногда это может быть неудобно.\\ Если checkbox используется в форме, где нужно отсылать неотмеченное состояние, укажите аттрибут ''data-return='1' ''\\ === AJAX загрузка файла === [[abills:docs:development:modules:ajax_upload|Шаблон модального окна]] === 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'" } ); * Отправка формы, в которой находится ''