Друк квитанцій

Починаючи з релізу 0.9.8 з'явилася можливість~~, яка нікому не потрібна~~, друкувати квитанції на оплату послуг (для подальшого вручення абонентам або розсилки будь-якими можливими засобами зв'язку) для абонентів Інтернет та UKV. Також у квитанцію може бути впроваджено QR-код з необхідною інформацією ~~або побажанням усього найкращого тому, хто його відсканує~~. Вмикається модуль опцією PRINT_RECEIPTS_ENABLED в alter.ini. За допомогою опції alter.ini PRINT_RECEIPTS_IN_PROFILE можна ввімкнути друк квитанцій особисто для кожного користувача прямо з його профілю \\.

Виглядає це приблизно так: На наш погляд, якихось пояснень інтерфейс модуля не потребує, а ось про шаблон для нього і генерацію QR-кодів варто згадати окремо.

Починаючи з релізу 1.0.9 стало можливим зберігати кожну зі згенерованих квитанцій у БД. Для цього просто відмітьте відповідний чекбокс на формі безпосередньо перед генерацією. Для використання цієї можливості потрібно всього лише додати в alter.ini опцію PRINT_RECEIPTS_HISTORY_ENABLED=1.

Шаблон

Приклад шаблону квитанції ви знайдете за цим шляхом:
content/documents/receipt_template/

Нескладно помітити, що це - звичайний HTML-документ, розділений на 3 секції (частини): heading, body, footer.

heading - “шапка” документа, що додається до нього один раз на самому початку. Крім того, саме тут мають бути описані формати дат/років/місяців, а також вміст інтегрованого QR-коду. Якщо він вам у квитанції потрібен, звісно.
Файл: payment_receipt_head.tpl

body - основна і, власне, “повторювана” для кожного абонента частина документа. Тут має міститися вся інформація, яку ми хочемо донести до абонента.
Файл: payment_receipt.tpl.

footer - те саме що й “шапка”, тільки в самому кінці. Не передбачає наявності будь-якої корисної інфи (крім закриваючих тегів </body></html>) у принципі. Але якщо вам, наприклад, дуже хочеться нагадати співробітникові, який займається квитанціями, про щось дуже-дуже важливе, коли він закінчить розбір пачки надрукованого паперу - це саме те місце.
Файл: payment_receipt_footer.tpl.

Починаючи з релізу 1.0.9 стало можливим мати необмежену кількість шаблонів, які можна вказувати прямо на формі друку квитанцій. Наприклад, якщо для різних підприємців мають бути різні бланки квитанцій. Або якщо ви хочете друкувати і не квитанції зовсім, а, скажімо, повідомлення (ніхто ж вас не зобов'язує до того, щоб у шаблоні фігурували суми та оплати). Просто розмістіть каталог із найменуванням шаблону в content/documents/receipt_template/, а вже в цей каталог покладіть файли секцій heading, body, footer - і ваш шаблон стане доступним у відповідному випадаючому списку на формі модуля.

Підтримувані змінні та макроси

{CURDATE} - поточна дата
{CURTIME} - поточний час
{CURDATENODELIMS} - поточна дата без роздільників
{CURDATETIMENODELIMS} - поточний час без роздільників
{INVOICE_NUM} - номер квитанції. Генерується як наступний ID у таблиці 'invoices', якщо квитанція в процесі генерації зберігається в БД.
Або просто як {CURDATENODELIMS} + {CURDATETIMENODELIMS} + '-' + “поточний індекс масиву обраних для друку абонентів”.
Або просто як {CURDATENODELIMS} + {CURDATETIMENODELIMS}, якщо в heading-секції вказано макрос {INV_NUM_CURDATETIME}.
{MONTH_COUNT} - кількість місяців зазначених для оплати
{PAYFORPERIODSTR} - оплата за період(місяці), наприклад: березень 2019, квітень 2019
{PAYTILLMONTHYEAR} - буде замінено на поточний рік + наступний місяць (згідно з форматом дати, зазначеним у шаблоні)
{PAYTILLDATE} - оплатити до зазначеної дати
{SERVICENAME} - найменування оплачуваної послуги
{CONTRACT} - номер договору користувача
{CONTRACTDATE} - дата договору користувача
{REALNAME} - ПІБ користувача
{CITY} - місто проживання користувача
{STREET} - вулиця проживання користувача
{BUILD} - будинок
{APT} - квартира
{EXTADDR_POSTALCODE} - поштовий індекс з додаткових полів адреси. Вимагає ввімкненої alter.ini опції ADDRESS_EXTENDED_ENABLED.
{EXTADDR_TOWNDISTR} - район/ПГТ/округ/етс із додаткових полів адреси. Потребує ввімкненої alter.ini опції ADDRESS_EXTENDED_ENABLED.
{EXTADDR_ADDREXT} - додаткова інфо за адресою з додаткових полів адреси. Потребує ввімкненої alter.ini опції ADDRESS_EXTENDED_ENABLED.
{PHONE} - телефон користувача
{MOBILE} - мобільний користувача
{TARIFF} - тариф користувача
{TARIFFPRICE} - вартість тарифу користувача
{TARIFFPRICECOINS} - вартість тарифу користувача виражена в копійках
{TARIFFPRICEDECIMALS} - вартість тарифу користувача з двома знаками після коми
{SUMM} - сума до сплати
{SUMMCOINS} - сума до сплати виражена в копійках \
{SUMMDECIMALS} - сума до сплати з двома знаками після коми

QR-коди спеціальні змінні та макроси

Для генерації QR-кодів передбачається використання JS-бібліотеки jquery.qrcode і відповідної мінімальної “обв`язки” для неї. У шаблоні-прикладі вже є всі мінімально необхідні для цього скрипти.

Для коректної генерації та розташування QR-кодів використовуються такі макроси:

{QR_CODES_CNT} - кількість QR-кодів, яка, по суті, дорівнює кількості абонентів (документів, що генеруються). Використовується JS-скриптом для обходу елементів DOM з відповідними індексами. Розташовувати в heading-секції.

{QR_CODE_CONTENT} - дані, які потрібно “упакувати” в QR-код. Розташовувати в body-секції.

{QR_INDEX} - індекс або порядковий номер QR-коду, за яким JS-скрипт знаходитиме елемент DOM, який міститиме сам QR-код або ж містить дані, що їх треба “упакувати” в QR-код. Розташовувати в body-секції.

{QR_EMBED} - наявність цього макросу вказує, що генерація QR-кодів повинна проводитися на стороні сервера і готовий QR-код вбудовується в документ у вигляді закодованого в Base64 зображення. Також необхідно не забути додати в секцію heading прихований інпут виду:

<input id="qr_embedded" type="hidden" value="0" />

зі значенням “value”=1. Розташовувати в heading-секції.
Важливо відзначити, що, оскільки, робиться це засобами гуглоАПІ http://chart.apis.google.com/chart - така генерація займає доволі багато часу і не рекомендована для великої кількості документів (хоча на тестах до 100 штук - цілком собі прийнятно - пара хвилин очікування…). Починаючи з Ubilling 1.4.6 для генерації використовується libGD - все дуже швидко та гарно.

Якщо коротко - логіка процесу генерації QR-коду така:

У циклі від i == 1 до {QR_CODES_CNT} по черзі шукаємо DOM-елементи, наприклад, з id="qr_content_" + i, беремо їхній вміст, 
"упаковуємо" в QR-код, а QR-код зі свого боку пхаємо в DOM-елементи з id="qr" + i.

З чого випливає, що самі QR-коди ніде не зберігаються і генеруються на льоту під час відкриття сторінки в браузері (звісно, якщо ми не використовуємо {QR_EMBED}). Таким чином, зберігання зібраного модулем HTML-документа вимагає в рази менше дискового простору, а так само документ стає набагато легшим для пересилання.

Окремо варто сказати про спеціальні макроси, які повинні розташовуватися виключно в єдиному екземплярі та виключно в heading-секції всередині HTML-коментаря (<!– –>):

Блок даних, які потрібно “упакувати” в QR-код

    {QR_EXT_START}
      here goes your info to pack into QR-code
      {MACRO_IS_ALLOWED_HERE}
    {QR_EXT_END}

Формат дати, який ми хочемо використовувати для наших квитанцій. За замовчуванням встановлено стандартний для наших широт

формат: дд.мм.ммггг. Але в цьому макросі ви можете вказати будь-який валідний формат для PHP функції date().

    {DATES_FORMAT_START}Y-m-d{DATES_FORMAT_END}

Формат місяць-рік (так-так, для макроса {PAYTILLMONTHYEAR}). За замовчуванням так само встановлено стандартний для наших широт

формат: мм.ггггг. Але в цьому макросі ви можете вказати будь-який валідний формат для PHP функції date().

    {MONTHYEAR_FORMAT_START}m-Y{MONTHYEAR_FORMAT_END}

Номери квитанцій будуть генеруватись за принципом {CURDATENODELIMS} + {CURDATETIMENODELIMS}, якщо ви додасте вказаний нижче макрос:

{INV_NUM_CURDATETIME}