Створення PDF-звітів

Важливо

Цей посібник є продовженням посібника Серверний фреймворк 101. Переконайтеся, що ви його виконали, та використовуйте модуль estate, який ви створили, як основу для вправ у цьому посібнику.

Раніше ми вже знайомство з QWeb, де його використовували для створення канбан-представлення. Тепер ми розглянемо одне з інших основних застосувань QWeb: створення PDF-звітів. Поширеною вимогою бізнесу є можливість створювати документи для надсилання клієнтам та для внутрішнього використання. Ці звіти можна використовувати для узагальнення та відображення інформації в організованому шаблоні для підтримки бізнесу різними способами. Odoo також може додавати заголовок і нижній колонтитул нашої компанії до наших звітів з мінімальними додатковими зусиллями.

Документацію щодо цієї теми можна знайти в Шаблони QWeb, Звіти QWeb і в розділі Звіт про дії (ir.actions.report) довідника про дії.

Структура файлу

Основну частину PDF-звіту становить його шаблон QWeb. Також зазвичай потрібен відповідний ir.actions.report, щоб включити звіт у бізнес-логіку модуля. Немає суворих правил щодо назв файлів або їх розташування, але ці дві частини зазвичай зберігаються в 2 окремих файлах у папці report на верхньому рівні каталогу вашого модуля. Якщо модуль має багато або кілька довгих шаблонів звітів, вони часто організовані логічно в різних файлах, названих відповідно до звітів, які вони містять. Усі дії зі звітами зазвичай зберігаються в одному файлі, який закінчується на _reports.xml, незалежно від кількості звітів, які він містить.

Тому очікується, що ваше робоче дерево виглядатиме приблизно так:

estate
├── models
│   ├── *.py
│   └── __init__.py
├── report
│   ├── estate_property_templates.xml
│   └── estate_property_reports.xml
├── security
│   └── ir.model.access.csv
├── views
│   └── *.xml
├── __init__.py
└── __manifest__.py

Не забудьте додати будь-які файли вашого шаблону та перегляду дій до вашого __manifest__.py. У цьому випадку ви захочете додати файли до списку data і пам’ятайте, що файли, перелічені в маніфесті, завантажуються послідовно!

Базовий звіт

Примітка

Ціль: наприкінці цього розділу ми зможемо надрукувати звіт, у якому відображатимуться всі пропозиції щодо нерухомості.

Простий звіт у форматі PDF

У нашому прикладі нерухомості є багато корисних звітів, які ми могли б створити. Один простий звіт, який ми можемо створити, це той, який відображає всі пропозиції нерухомості.

Дата звіту

Перш ніж щось робити, нам спочатку знадобляться деякі дані для заповнення наших звітів, інакше цей посібник не буде дуже цікавим. Під час створення звітів вам знадобляться деякі дані, щоб перевірити код звіту та перевірити, чи результат виглядає так, як очікувалося. Це гарна ідея для тестування з даними, які охоплюють більшість або всі очікувані випадки використання. Хороший набір представлень для нашого простого звіту:

  • Принаймні 3 властивості, де 1 «продано», 1 «отримано пропозицію» і 1 «новий».

  • Щонайменше 2-3 пропозиції на наші «продані» та «отримані пропозиції»

Якщо у вас ще немає такого набору даних, ви можете:

  • Виконайте підручник Визначення даних модуля (якщо ви цього ще не зробили) і додайте додаткові випадки до своїх демонстраційних даних (може знадобитися створити нову базу даних для завантаження демонстраційних даних).

  • Вручну створіть дані у своїй базі даних.

  • Скопіюйте цей файл даних у новий каталог (data) у вашому модулі estate та скопіюйте ці рядки у ваш файл __manifest__.py (можливо, вам знадобиться створити нову базу даних для завантаження демонстраційних даних).

Перш ніж продовжити, клацніть по своїх даних у своїй базі даних і переконайтеся, що ваші дані відповідають очікуванням. Звичайно, ви можете додати дані після написання коду звіту, але тоді ви не зможете поступово тестувати частини коду під час написання. Це може ускладнити перевірку на наявність помилок і налагодження коду в довгостроковій перспективі для складних звітів.

Мінімальний шаблон

Мінімальний життєздатний шаблон можна переглянути в розділі «Мінімальний життєздатний шаблон» документації Шаблон звіту. Ми можемо змінити цей приклад, щоб створити файл шаблону мінімальних пропозицій властивостей:

<?xml version="1.0" encoding="UTF-8" ?>
<odoo>
    <template id="report_property_offers">
        <t t-foreach="docs" t-as="property">
            <t t-call="web.html_container">
                <t t-call="web.external_layout">
                    <div class="page">
                        <h2>
                            <span t-field="property.name"/>
                        </h2>
                        <div>
                            <strong>Expected Price: </strong>
                            <span t-field="property.expected_price"/>
                        </div>
                        <table class="table">
                            <thead>
                                <tr>
                                    <th>Price</th>
                                </tr>
                            </thead>
                            <tbody>
                                <t t-set="offers" t-value="property.mapped('offer_ids')"/>
                                <tr t-foreach="offers" t-as="offer">
                                    <td>
                                        <span t-field="offer.price"/>
                                    </td>
                                </tr>
                            </tbody>
                        </table>
                    </div>
                </t>
            </t>
        </t>
    </template>
</odoo>

Більшість специфічних для Odoo (тобто не HTML) елементів у нашому файлі пояснюється в розділі мінімального життєздатного шаблону. Деякі додаткові функції в нашому шаблоні:

  • Використання атрибута class="table", тому наша таблиця має гарне форматування. Класи Twitter Bootstrap (у цьому випадку ми використовуємо клас таблиці) і Font Awesome (корисний для додавання значків) можна використовувати в шаблоні звіту.

  • Використання t-set, t-value, t-foreach і t-as, щоб ми могли циклічно переглядати всі offer_ids.

Якщо ви вже знайомі з механізмами створення шаблонів для веб-сайтів, то директиви QWeb (тобто команди t-), ймовірно, не потребують особливих пояснень, і ви можете просто переглянути її документацію і пропустити до наступного підрозділу.

В іншому випадку вам пропонується прочитати більше про них ( Wikipedia має хороший високорівневий опис), але загальна ідея полягає в тому, що QWeb надає можливість динамічно генерувати веб-код на основі даних Odoo та простих команд. тобто QWeb може отримувати доступ до набору даних (і методів) і обробляти прості операції програмування, такі як налаштування та доступ до тимчасових змінних. Наприклад, у наведеному вище прикладі:

  • t-set створює тимчасову змінну під назвою «offers», значення якої встановлюється t-value для поточного offer_ids набору записів estate.property.

  • Використання t-foreach і t-as є еквівалентом Python:

for offer in offers:

Дія звіту

Тепер, коли у нас є шаблон, нам потрібно зробити його доступним у нашому додатку через ir.actions.report. Практичний приклад ir.actions.report є тут відповідний до цього шаблону. Весь його вміст пояснюється в документації.

Файл ir.actions.report в основному використовується через меню Друк у представленнімоделі. У практичному прикладі binding_model_id визначає, які вигляди моделі має відображатися у звіті, і Odoo автоматично додасть його для вас. Іншим поширеним випадком використання дії звіту є пов’язування її з кнопкою, як ми дізналися в Розділ 9: Готові до дії?. Це зручно для звітів, які мають сенс лише за певних умов. Наприклад, якщо ми хочемо створити звіт «Фінальний продаж», то ми можемо пов’язати його з кнопкою «Друк інформації про продаж», яка відображається у вигляді форми лише тоді, коли властивість має значення «Продано».

Кнопка меню друку

Можливо, ви помітили або дивувалися, чому наш шаблон звіту циклічно переглядає набір записів. Коли нашому шаблону передано кілька записів, він може створювати один PDF-звіт для всіх записів. Це продемонструє використання меню Друк у представленні списку з кількома вибраними записами.

Зробіть звіт

Нарешті, тепер ви знаєте, де створювати файли та як має виглядати вміст файлів. Гарного звіту!

Exercise

Зробіть звіт.

  • Додайте звіт про пропозиції властивостей із підрозділу мінімального шаблону до меню Друк Властивості представлень.

  • Покращте звіт, додавши більше даних. Перегляньте Ціль цього розділу, щоб дізнатися, які додаткові дані ви можете додати, і не соромтеся додавати ще більше.

  • Бонус: створіть додатковий гнучкий звіт, додавши деяку логіку, щоб ми не створювали таблицю, коли немає пропозицій щодо об’єкта нерухомості, а писали щось про те, що пропозицій ще немає. Підказка: вам потрібно буде використовувати t-if і t-else.

Не забудьте перевірити, чи ваші PDF-звіти відповідають очікуваним даним.

Підшаблони

Примітка

Ціль: у кінці цього розділу ми матимемо підшаблон, який ми використовуємо у 2 звітах.

Звіт за допомогою підшаблону

Є дві основні причини використання підшаблонів. Одна з них полягає в тому, щоб полегшити читання коду під час роботи з наддовгими або складними шаблонами. Інший - повторне використання коду, де це можливо. Наш простий звіт про пропозиції нерухомості корисний, але інформація про пропозиції нерухомості може бути корисною не лише для одного шаблону звіту. Одним із прикладів є звіт із переліком усіх пропозицій нерухомості продавця.

Перевірте, чи можете ви зрозуміти, як викликати підшаблон, прочитавши документацію щодо нього та/або переглянувши приклад (пам’ятайте, що QWeb використовує однакові потоки керування незалежно від того, для звіту чи представлення в Odoo.)

Exercise

Створіть і використовуйте підшаблон.

  • Розділіть табличну частину пропозицій на окремий шаблон. Після цього не забудьте перевірити, чи ваш оригінальний звіт все ще правильно друкується.

  • Додайте новий звіт для res.users, який дозволить вам друкувати всі властивості нерухомості, видимі в їхній формі (тобто в додатку «Налаштування»). Включіть пропозиції для кожного з цих об’єктів продавця в той самий звіт. Підказка: оскільки binding_model_id у цьому випадку не буде в модулі нерухомості, вам потрібно буде використовувати ref="base.model_res_users".

    Ваш кінцевий результат має виглядати подібно до зображення в Цілі цього розділу.

Не забудьте перевірити, чи ваші звіти відповідають очікуваним даним!

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

Примітка

Ціль: наприкінці цього розділу ми успадкуємо звіт про власність у модулі estate_account.

По спадковому звіту

Успадкування в QWeb використовує ті ж елементи xpath, що й успадкування представлень. Однак шаблон QWeb посилається на свій батьківський шаблон по-іншому. Це ще простіше зробити, просто додавши атрибут inherit_id до елемента template та встановивши його рівним module.parent_template_id.

Ми не додали жодних нових полів до жодної моделі нерухомості в estate_account, але ми все одно можемо додавати інформацію до нашого наявного звіту про власність. Наприклад, ми знаємо, що для будь-якої «Проданої» нерухомості вже буде створено рахунок-фактуру, тому ми можемо додати цю інформацію до нашого звіту.

Exercise

Успадкувати звіт.

  • Розширте звіт про власність, щоб включити деяку інформацію про рахунок-фактуру. Ви можете переглянути Ціль цього розділу для натхнення (тобто друкувати рядок, коли властивість виконано, інакше нічого не друкувати).

Знову ж таки, не забудьте перевірити, чи ваші звіти відповідають вашим даним, як очікувалося!

Додаткові можливості

Усі наступні додаткові функції описано далі в документації Звіти QWeb, включаючи те, як реалізувати кожну з них.

Переклади

Ми всі знаємо, що Odoo використовується кількома мовами завдяки автоматичному та ручному перекладу. Звіти QWeb не є винятком! Зауважте, що іноді переклади не працюють належним чином, якщо в текстовому вмісті вашого шаблону є непотрібні пробіли, тому намагайтеся уникати їх, коли це можливо (особливо пробіли на початку).

Звіти – це веб-сторінки

Можливо, ви втомилися чути, що QWeb створює HTML, але ми повторюємо це знову! Одна з чудових особливостей звітів, створених у QWeb, полягає в тому, що їх можна переглядати у веб-браузері. Це може бути корисним, якщо ви хочете вставити гіперпосилання, яке веде до певного звіту. Зауважте, що звичайні перевірки безпеки все одно застосовуватимуться, щоб запобігти доступу неавторизованих користувачів до звітів.

Штрих-коди

Odoo має вбудований засіб створення зображень штрих-кодів, який дозволяє вставляти штрих-коди у ваші звіти. Перегляньте відповідний код, щоб побачити всі підтримувані типи штрих-кодів.