Розбіжності

Тут показані розбіжності між вибраною ревізією та поточною версією сторінки.

--- development [2019/02/22 02:51]
+++ development [2024/12/23 11:48] (поточний)
nightfly [Розташування модулю як плагіну профілю користувача]
@@ Рядок 1: / Рядок 1: @@
+====== Короткий посібник із розробки модулів для Ubilling ======
+Писати додаткові модулі для Ubilling дуже просто, розгляньмо процес написання найпростішого модуля на прикладі модуля, що показує всіх користувачів з їхніми ПІБ та адресами у вигляді гарної сортувальної таблички.
+Типовий модуль Ubilling розміщується в окремому підкаталозі **/modules/general/** і складається з двох файлів: **index.php** і **module.php**. Перший із них є власне модулем із його виконуваним кодом, другий же - описом модуля для вбудованого диспатчера. Давайте припустимо, що наш модуль називатиметься samplemod і таким чином складатиметься з двох файлів:\\
+\\
+{{:samplemod.png?|}}
+\\
+Давайте детально розберемо що-ж знаходиться в цих двох містичних файликах.\\
+<file php module.php>
+  <?php
+  $this->registerModule($module, 'main', 'Sample module', 'Sample developer', array('SAMPLE' => __('right for access sample module')));
+</file>
+Містить у собі стандартний набір, який описує те, що модуль має клас **main** (тобто може розміщуватися в центральному блоці контенту за замовчуванням), зветься **Sample module**, написаний розробником на ім'я **Sample developer** і під час свого довантаження породжує право **SAMPLE**, за яким згодом ми розмежовуватимемо доступ до цього модуля. Зверніть увагу на конструкцію <code>__('Рядок англійською')</code> використану в цьому прикладі в ролі опису права на модуль. Функція повертатиме локалізований рядок відносно поточної мови, якщо він знайдений у словниковому файлі. Власне локалізація в Ubilling є подібною до gettext.\\
+Все, з файлом опису модуля розібралися, поїхали далі.\\
+\\
+\\
+<file php index.php>
+<?php
+  // перевіряємо чи має користувач права на користування цим модулем
+  if (cfr('SAMPLE')) {
+    //робимо запит до БД з метою отримати логіни всіх користувачів
+    $query="SELECT `login`,`IP` from `users`";
+    $alllogins=simple_queryall($query);
+    //отримуємо масиви всіх П.І.Б. користувачів та їхніх адрес
+    $allrealnames=zb_UserGetAllRealnames();
+    $alladdress=zb_AddressGetFulladdresslist();
+    //перевіряємо, чи є взагалі у нас користувачі
+    if (!empty ($alllogins)) {
+            //Збираємо заголовок таблички для виведення
+            $tablecells=wf_TableCell(__('Login'));
+            $tablecells.=wf_TableCell(__('IP'));
+            $tablecells.=wf_TableCell(__('Real Name'));
+            $tablecells.=wf_TableCell(__('Address'));
+            $tablerows=wf_TableRow($tablecells, 'row1');
+        // Перебираємо всіх користувачів
+        foreach ($alllogins as $io=>$eachlogin) {
+            $userlogin=$eachlogin['login'];
+            $userip=$eachlogin['IP'];
+            //Збираючи для кожного рядка таблички
+            $tablecells=wf_TableCell($userlogin);
+            $tablecells.=wf_TableCell($userip);
+            $tablecells.=wf_TableCell(@$allrealnames[$userlogin]);
+            $tablecells.=wf_TableCell(@$alladdress[ $userlogin]);
+            $tablerows.=wf_TableRow($tablecells, 'row3');
+        }
+        // оголошуємо як результат табличку з попередньо зібраними рядками
+        // а також шириною в 100%, бордюром в 0 і класом sotrable
+        $result=wf_TableBody($tablerows, '100%', '0', 'sortable');
+    } else {
+        //якщо немає натякаємо що їх немає
+        $result=__('No users found');
+    }
+    // виводимо наш результат за допомогою функції show_window
+    show_window(__('Sample module'), $result);
+  } else {
+      // якщо ні - вивалюємо на нього помилку про відмову в доступі
+      show_error(__('You cant control this module'));
+  }
+</file>
+Доступ до нашого модуля ми можемо отримати за допомогою посилання **?module=samplemod**, в результаті чого ми повинні побачити приблизно таке:\\
+{{:samplemod2.png?|}}
+Як бачите, замість рядків **Real Name** і **Address** у нас автоматично підставилися їхні мовно-залежні заміни зі словника поточної локалізації. Не перекладеним залишився один рядок **Sample module**, про який рушій локалізації поки що нічого не знає. Давайте перекладемо його скажімо російською мовою для початку.\\\
+Зробити це досить просто - потрібно створити файл **/languages/ukrainian/samplemod.php** такого змісту:
+<file php samplemod.php>
+<?php
+$lang['def']['Sample module'] = 'Модуль для прикладу';
+$lang['def']['Yet another string'] = 'Ще якийсь рядок';
+</file>
+Після чого ми побачимо як рядок локалізувався сам по собі в нашому модулі:\\
+{{:samplemod3.png?|}}
+\\
+З нестандартних речей, чужих чистому PHP, ми використовували тільки функції бібліотеки** api.astral** для збирання таблиць за допомогою **wf_**, що не є обов'язковою, просто виглядає красивіше та читабельніше, а також результат крізь **show_window($title,$data)** замість **print()**, що вже є обов'язковою для роботи шаблонізатора фреймворка.\\
+А що робити, якщо нашому модулю потрібна якась бібліотека/клас потрібна йому одному? Варіантів є кілька. Перший з них менш красивий, але більш портабельний - вставити її прямо всередину нашого модуля в **modules/general/samplemod/index.php**. Другий - просто покласти цю бібліотеку в директорію **modules/engine/**. У цьому разі вона буде довантажена до виконання нашого модуля. Хорошим тоном у цьому випадку буде переконатися, що під час свого завантаження вона не буде виробляти якогось виводу, і друге - постарайтеся уникати створення великих об'єктів у цій бібліотеці, щоб уникнути деградації продуктивності загалом. Що мається на увазі під цим? Наведемо на прикладі бібліотеки, яка описує якийсь клас SampleClass і знаходиться в **modules/engine/sampleClass.php**
+<file php sampleClass.php>
+<?php
+class SampleClass {
+  protected $data=array();
+  public function __construct() {
+    $this->loadData();
+  }
+  protected function loadData() {
+    $this->data=......
+  }
+}
+$sampleObject=new SampleClass(); // ось цього тут бути не повинно, місце йому в modules/general/samplemod/index.php
+?>
+</file>
+Також чудовим (**і рекомендованим!**) способом може бути розміщення вашої бібліотеки в **api/libs/**, звідки її може підхопити автозавантажувач, якщо ім'я класу створюваного об'єкта відповідає імені бібліотеки з префіксом "**api.**" у лаверкейсі. Для прикладу вище це має бути файл **api/libs/api.sampleclass.php**. Під час створення об'єкта $sampleObject=new SampleClass(); цю бібліотеку буде автоматично завантажено, і вам взагалі нічого не потрібно для цього робити.
+====== Розташування модуля на панелі задач ======
+А як додаються модулі на панель завдань? Ну там з іконками, правами та опціями? А все так само дуже просто - розкладанням потрібних файликів у потрібні місця. Починаючи з релізу 0.8.0 цими місцями є директорія **config/taskbar.d/**, а точніше її підкаталоги. Припустимо, наш тестовий модуль є з нашої точки зору звітом. Також ми хочемо, щоб вмикався він за допомогою необов'язкової опції [[alteriniconf|alter.ini]] на ім'я SAMPLE_ENABLED. Разом кладемо файлик sample.ini в директорію **config/taskbar.d/reports/**
+<file ini sample.ini>
+; Ідентифікатор модуля. Повинен бути як мінімум унікальним.
+ID="samplemod"
+; Підпис іконки модуля - буде автоматично локалізовано поточною локаллю.
+NAME="Sample module"
+; URL нашого модуля. Не повірите - буде клікабельним :)
+URL="?module=samplemod"
+; Іконка модуля. Спочатку намагається знайтися в директорії taskbar поточного скіна, якщо не існує - у глобальному skins/taskbar.
+ICON="goat.gif"
+; Право, яке вимагає модуль. Ну як мінімум право, яке потрібне для показу іконки.
+NEED_RIGHT="SAMPLE"
+; Опція конфіга alter.ini необхідна для показу іконки таскбару.
+NEED_OPTION="SAMPLE_ENABLED"
+; Цей параметр сигналізує, що опція є необов'язковою.
+; Якщо видалити цей параметр - панель завдань буде кричати про відсутню опцію.
+UNIMPORTANT=1
+; Тип елемента. У нашому випадку це icon - типова іконка з підписом. Є ще widget але про це пізніше.
+TYPE="icon"
+; Ця необов'язкова опція описує те буде відкриватись посилання на елемент.
+; Може бути відсутньою чи порожньою або приймати значення _blank, _self, _parent, _top чи ім'я iframe.
+; детальніше тут: https://www.w3schools.com/tags/att_a_target.asp
+LINK_TARGET=
+</file>
+та отримуємо результат очікуваний результат
+{{:undefined:samplemod4.png|}}
+А що ж із віджетами, і як вони взагалі виглядають? А ось якось так [[taskbarwidgets|так]].
+====== Приклад використання dataTable ======
+<code php>
+   // jQuery dataTable construction and rendering
+    $myUrl = '?module=testing';
+    $callbackRoute = 'ajaxlist';
+    $columns = array('Якась колонка', 'Друга колонка');
+    $dataTable = wf_JqDtLoader($columns, $myUrl . '&' . $callbackRoute . '=true', false, __('Data'), 50);
+    show_window(__('Title'), $dataTable);
+    // JSON dataTable data output on some callback route
+    if (ubRouting::checkGet($callbackRoute)) {
+        $json = new wf_JqDtHelper();
+        $json->addRow(array('якісь дані', 'інші дані'));
+        $json->addRow(array('це в першій колонці', 'також дані'));
+        $json->getJson();
+    }
+</code>
+результат
+{{:jqdt.png|}}
+====== Розташування модулю як плагіну профілю користувача ======
+Формат plugins.ini дуже близький до формату опису елементу панелі задач. Тільки імена опцій в лаверкейсі.
+<file ini plugins.ini>
+[унікальний ідентифікатор модуля]
+name = "Ім'я модулю"
+icon = "ім'я файлу іконки модулю"
+need_right=Право яке необхідне модулю
+need_option=Опція яка необхідна
+;Наступна опція не є обов`язковою. Просто вказує те де буде відкрито посилання.
+;детальніше тут: https://www.w3schools.com/tags/att_a_target.asp
+;link_target=_self
+</file>
+також модуль може бути описаним у оверлеї "чорної магії" в bmagic.ini в тому ж форматі.

Ubilling Wiki

Користувальницькькі налаштування

Налаштування сайту

Розбіжності

Налаштування сторінки