Розбіжності

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

--- nodeny:docs:calls.pm [25/01/2023 21:47] – створено Method
+++ nodeny:docs:calls.pm [15/05/2023 12:46] (поточний) – [%%_(%%)] Method
@@ Рядок 106: / Рядок 106: @@
 <code>
 Show Message
+WideBox('Повідомлення');
+</code>
+**Box** виводить темплейт box.html. Усі параметри необов'язкові
+   * title - заголовок повідомлення
+   * msg - повідомлення
+   * wide - якщо встановлений, то рамка розтягується по ширині
+   * css_class - css class повідомлення
+<code>
+Show Box(
+     title => 'Заголовок',
+     wide => 1,
+     msg => 'Текст повідомлення всередині рамки',
+     css_class => 'error txtpadding',
+);
+</code>
+**WideBox** теж, що й Box, але параметр wide встановлений в 1
+<code>
+Show WideBox();
+</code>
+**Menu**
+Menu теж, що і MessageWideBox, але повідомлення має css class `navmenu`, що наказує виводити гіперпосилання на всю ширину блоку, одне під одним.
+<code>
+ToLeft Menu(
+     url->a( 'Список клієнтів', a=>'users' ).
+     url->a( 'Статистика трафіку', a=>'traf_log' ).
+     url->a( 'Google', -base=>'http://google.com' )
+);
+</code>
+**Center** виводить інформацію відцентрованої по горизонталі
+<code>
+Show Center MessageBox('Center');
+</code>
+Відмінність від css h_center у цьому, що дозволяє центрувати як текст.
+**Error** виводить повідомлення про помилку та завершує виконання скриптів
+<code>
+> 2 && Error('1 > 2 !!!');
+</code>
+**Error_** теж, що й Error, але повідомлення обробляється підпрограмою %%_(%%)
+<code>
+$lang::hello_msg = 'Здрастуйте [filtr|bold], на вашому рахунку [bold] $';
+Error_($lang::hello_msg, 'адміністратор', 1000);
+</code>
+**ErrorMess** теж, що й Error, але виконання скрипту не припиняється
+<code>
+ErrorMess('Щось не так!');
+Error('Точно щось не так...');
+</code>
+===== Pay_to_DB =====
+**Pay_to_DB** створює запис у таблиці pays за вхідними параметрами:
+   * uid - id клієнта, з яким пов'язана запис чи 0, а то й пов'язана. Необов'язковий параметр за промовчанням 0.
+   * cash – сума, або 0, якщо платіж не фінансовий. Необов'язковий параметр за промовчанням 0.
+   * reason - поле reason. Необов'язковий параметр.
+   * comment – поле comment. Необов'язковий параметр.
+   * time - timestamp платежу. Необов'язковий параметр за промовчанням поточний час.
+   * category - категорія. Обов'язковий параметр.
+Повертає 1 у разі успішного запису. У параметрах запису автоматично встановлюється автор адмін або клієнт залежно від авторизованого. Також встановлюється IP.
+\\ Якщо запис фінансовий, то має бути виконаний у транзакції, наприклад:
+<code>
+  Db->begin_work або Error($lang::err_try_again);
+  my $rows1 = Db->do("UPDATE users SET balance=balance+(?) WHERE id=?", $money, $uid);
+  my $rows2 = Pay_to_DB(uid=>$uid, cash=>$money, category=>1);
+  if( $rows1 < 1 || $rows2 < 1 || !Db->commit )
+  {
+     Db->rollback;
+     Error($lang::err_try_again);
+  }
+</code>
+Тут Db->begin_work перемикає Db на режим транзакцій. Починаючи з цього моменту, sql update/insert будуть виконуватися, але не фіксуватися в БД поки не буде виконаний Db->commit. У разі перевіряється, що обидва запити було виконано успішно, тобто. якщо хоча б один із запитів повернув менше одиниці - виконується відкат Db->rollback. Відкат гарантує, що жоден із запитів не буде зафіксовано у БД. Також він вимикає режим транзакцій.
+===== Get_usr_info =====
+Отримує дані клієнта щодо його id. У разі успіху повертає посилання на хеш з даними, інакше повідомлення про помилку.
+<code>
+my $ info = Get_usr_info(15);
+ref $info або Error $info;
+Show 'ПІБ клієнта з id=15: '.v::filtr($info->{fio});
+</code>
+Підпрограма повертає як основні дані, а й додаткові поля, і навіть список ip, які належать клієнту.
+<code>
+debug('pre', $info);
+</code>
+===== _() =====
+Підпрограма, що складається з одного символу підкреслення, вставляє в заданий рядок параметри:
+<code>
+Show _('[div][p h_center][div bold h_right]', 'Текст1', 'Текст2', 'Текст3');
+</code>
+Перетворюється на:
+<code>
+<div>Текст1</div><p class='h_center'>Текст2</p><div class='bold h_right'>Текст3</div>
+</code>
+Як видно, квадратні дужки вказують на вставку чергового параметра у поточне місце. При цьому перше слово у квадратних дужках вказує на тег. Є кілька зарезервованих слів, які не вказують на тег, наприклад, filtr - ескейпити html-спецсимволи в параметрі. trim – видаляє прогалини по краях параметра. Крім того, вертикальна характеристика дозволяє вставляти кілька керуючих послідовностей:
+<code>
+Show _('Ви ввели [filtr|trim|span bold]', 'xxx');
+</code>
+Перетворюється на рядок «Ви ввели <span class='bold'>xxx</span>»
+====== Таблиці ======
+perl код
+<code>
+     # Створюємо таблицю
+     my $tbl = tbl->new(-class=>'td_wide');
+     # Перший рядок
+     $tbl->add( '*', 'lll', 'комірка 1', 'комірка 2', 'комірка 3' );
+     # Другий рядок
+     $tbl->add( '*', 'lll', 'комірка 1', 'комірка 2', 'комірка 3' );
+     # Виводимо таблицю
+     Show $tbl->show;
+</code>
+Методом new створюється нова порожня таблиця. Вхідні параметри:
+<code>
+-class : css class таблиці
+-row1 : css class першого ряду
+-row2 : css class другого ряду
+</code>
+Параметри не є обов'язковими. Можуть бути взяті з іншого:
+perl код
+<code>
+     my $tbl1 = tbl->new( -class=>'td_wide td_ok' );
+     # Class для таблиці 2 буде 'td_wide td_ok'
+     my $tbl2 = $tb1->new(-row1=>'row5');
+</code>
+Приклади класів для таблиць
+<code>
+td_wide : таблиця максимальної ширини
+fade_border : осередки відокремлюються напівпрозорими лініями
+pretty : якщо в таблиці буде мало рядків, то вони будуть більшими за висотою
+td_ok : оптимальний паддинг для осередків таблиці
+td_tall : високі рядки
+td_medium : рядки середньої висоти
+td_wide : широкі осередки
+td_narrow : вузькі осередки
+</code>
+Рядки додаються методами add (наприкінці таблиці) і ins (на початок таблиці.). Формат параметрів:
+   * css ряду, що вставляється
+   * рядок - карта осередків
+   * осередок 1
+   * осередок 2
+   * ...
+Якщо в css буде символ зірочка - це вказівка дати ряду css з параметра -row1, після чого значення в -row1 і -row2 обміняються місцями. У такий спосіб можна організувати «зебру».
+Карта осередків - це рядок, який описує вирівнювання кожного осередку:
+<code>
+l : вирівнювання по лівому краю
+r : з правого
+c : по центру
+L : по лівому та 2 осередки об'єднуються в один
+R : праворуч і 2 осередки об'єднуються в одну
+C : по центру та 2 осередки об'єднуються в один
+E : по лівому та 3 осередки об'єднуються в один
+: по центру та 3 осередки об'єднуються в один
+: по центру та 4 осередки об'єднуються в один
+..
+: по центру та 9 осередків об'єднуються в одну
+t : по центру та вертикальне вирівнювання top
+T : 2 осередки в одну, по центру та вертикальне вирівнювання top
+пробіл : порожній осередок
+</code>
+perl код
+<code>
+     my $tbl = tbl->new( -class=>'td_wide td_ok' );
+     $tbl->add( '*', 'rcl', 'рівняння праворуч', 'центр', 'ліво');
+     $tbl->add( '*', 'rL', 'текст у 1й комірці', 'комірка 2 і 3 об'єднана в 1');
+     $tbl->add( '*', '3', 'текст центром і всі осередки об'єднані в одну');
+     Show $tbl->show;
+</code>
+Якщо будь-яка комірка буде у квадратних дужках - це відключить фільтрацію html-спецсимволів. Якщо ви відображаєте дані, надіслані клієнтом, ви не повинні відключати фільтрацію.
+perl код
+<code>
+     $tbl->add( '*', 'rl', 'ви надіслали рядок', ses::input('str'));
+     $tbl->add( '*', 'rl', 'поле введення', [ v::input_t(name=>'str') ]));
+</code>
+Автоматично ведеться облік рядків та стовпців таблиці. Метод rows дозволяє отримати поточну кількість рядів. Якщо при вставці рядків з'ясовується, що осередок менше ніж у попередньому, то йде автоматичне розширення останнього шляхом об'єднання з рештою:
+perl код
+<code>
+     $tbl->add( '*', 'll', 'Здрастуйте', 'Станіслав');
+     осередок буде з'єднаний з останньою т.к. у попередньому рядку 2 стовпці
+     $tbl->add( '*', 'l', 'сьогодні все ок');
+     # return не спрацює т.к. у таблиці 2 рядки
+     $tbl->rows < 1 && return;
+</code>
+**Альтернативний спосіб вставки рядків** дозволяє надавати css клас персонально кожному осередку (а не тільки всьому рядку в цілому). Крім того, для кожного осередку вказується заголовок. Кожен рядок необхідно обернути у квадратні дужки:
+perl код
+<code>
+     $tbl->add( '*', [
+         [ 'bold h_left', 'Заголовок 1й колонки', 'Увага' ],
+         [ 'h_right', 'Заголовок 2й колонки', 'всім' ],
+     ]);
+</code>
+У результаті буде вставлено рядок із двома осередками: у першому вирівнювання по лівому краю, у другій - по правому. У лівій виділений (клас bold) текст «Увага», у правій текст «усім». Коли таблиця буде виведена, то її шапці у першому осередку буде текст «Заголовок 1й колонки», у 2й - «Заголовок 2й колонки».
+\\ \\ ====== Package Url ======
+Призначений на формування гіперпосилань.
+Методи
+<code>
+new : створення нового об'єкту
+a : рендеринг url-об'єкта в гіперпосилання
+post_a : рендеринг у гіперпосилання, при натисканні на яке
+             дані будуть надіслані post-методом
+form : рендеринг url-об'єкта у форму
+url: отримання url з об'єкта
+redirect: редирект
+</code>
+Якщо параметр **не** починається зі знака тире – це параметр url-а:
+perl код
+<code>
+     my $url = url->new( a=>1, b=>2, -class=>'nav', -style=>'color:#000' );
+     Show $url->a('Текст посилання');
+</code>
+Буде перетворено на <a href='?a=1&b=2' class='nav' style='color:#000'>Текст посилання</a>
+Одне посилання можна створити на основі іншого, можна перевизначати параметри і т.д.
+perl код
+<code>
+     my $url = url->new( a=>1, b=>2, -class=>'nav', -style=>'color:#000' );
+     my $ url2 = url-> new (b => 3); #?a=1&b=3
+     $url2->{a} = 'demo'; #?a=demo&b=3
+     Show $url2->a('OK', b=>4); #?a=demo&b=4
+     $url->{b} = undef;
+     Show $url2->a('OK'); #?a=demo
+</code>
+У всіх параметрах ескейп html-спецсимволи. Квадратні дужки відключають це, найчастіше необхідно для тексту посилання:
+perl код
+<code>
+     my $url = url->new(-class=>'nav');
+     Але краще це зробити через стиль або клас
+     Show $url->a( [ '<b>Bold text</b>' ] );
+</code>
+У формах порядок параметрів відрізняється від гіперпосилання, спочатку параметри, потім вміст форми:
+perl код
+<code>
+my $form = _('[p][p h_center][p h_center]',
+     'Введіть ціле позитивне число:',
+     v::input_t(name=>'num'),
+     v::submit('Далі')
+);
+my $form = $Url->form(
+     a=>'module_name', param2=>'test', $form
+);
+</code>
+Параметр -ajax автоматично конвертується на -class='ajax'. При цьому JS NoDeny усі посилання, у яких присутній такий клас, робить «аяксовими» - при натисканні на такі посилання не завантажується нова сторінка, але йде http-запит на сервер, а відповідь обробляється скриптом nody.js у браузері.
+\\ \\ ====== Package Db ======
+Призначений для роботи з базою даних. Основний метод – sql.
+формати виклику
+   * Db->sql(sql, параметри для плейсхолдерів)
+   * Db->sql%%({%% параметри})
+Якщо необхідна вибірка лише одного рядка:
+<code>
+my %p = Db->line(параметри);
+</code>
+Хеш %p порожній якщо
+   * Порожня вибірка
+   * сталася помилка (невірний sql, дисконнект БД,...)
+Щоб уточнити: DB->ok повертає 1, якщо не було помилок.
+Вибір одного рядка
+<code>
+my %p = Db->line("SELECT * FROM users WHERE id=? AND grp=?", $id, $grp);
+Show %p? "$p{name}, $p{fio}" : Db->ok? 'порожня вибірка' : 'внутрішня помилка';
+</code>
+Вибірка кількох рядків
+<code>
+my $db = Db->sql("SELECT id, name FROM users WHERE field=?", $unfiltered_field);
+while( my %p = $db->line )
+{
+     Show "$p{id} = $p{name}<br>";
+}
+</code>
+Вибір декількох рядків з іншим форматом виклику
+<code>
+my $db = Db->sql(
+     sql => "SELECT * FROM tbl WHERE field=? AND val=?",
+     param => [ $filed, $val ],
+     comment => 'Вибірка номер 2',
+);
+while( my %p = $db->line ) { ... }
+</code>
+UPDATE/INSERT
+<code>
+my $rows = Db->do("UPDATE websessions SET uid=?, role=? WHERE ses=? LIMIT 1", $id, $role, $ses);
+$rows>0 or Error('Помилка!'); не робіть $rows or Error() т.к. rows може = -1
+</code>
+Виконання кількох запитів у транзакції
+<code>
+Db-> do_all (
+     [$sql1, $param1, $param2 ],
+     [$sql2, $param3 ],
+);
+</code>
+Перевіряється, що кожен запит торкнувся як мінімум 1 рядка. Увага! Якщо запит виконався, але не торкнувся жодного рядка (жоден збіг за умовою WHERE), то буде відкат транзакції.
+Додаткові методи
+   * disconnect - розриває з'єднання з БД
+   * connect - здійснює з'єднання з БД
+   * begin_work - старт транзакції
+   * commit - коміт транзакції
+   * rollback - відкат транзакції
+   * ok - чи був успішний останній виконаний sql
+   * rows - рядків торкнувся останній виконаний sql
+   * filtr - екранування небезпечних символів sql