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

Важливо

This tutorial is an extension of the Server framework 101 tutorial. Make sure you have completed it and use the estate module you have built as a base for the exercises in this tutorial.

We were previously introduced to QWeb where it was used to build a kanban view. Now we will expand on one of QWeb’s other main uses: creating PDF reports. A common business requirement is the ability to create documents to send to customers and to use internally. These reports can be used to summarize and display information in an organized template to support the business in different ways. Odoo can additionally add our company’s header and footer to our reports with minimal extra effort.

Документацію щодо цієї теми можна знайти в Шаблони 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 пропозиції на наші «продані» та «отримані пропозиції»

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

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

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

  • Copy this data file into a new directory (data) in your estate module and copy these lines into your __manifest__.py file (you may need to create a new database to load in the demo data).

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

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

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

<?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 є тут відповідний до цього шаблону. Весь його вміст пояснюється в документації.

An ir.actions.report is primarily used via the Print menu of a model’s view. In the practical example, the binding_model_id specifies which model’s views the report should show, and Odoo will auto-magically add it for you. Another common use case of the report action is to link it to a button as we learned in Chapter 9: Ready For Some Action?. This is handy for reports that only make sense under specific conditions. For example, if we wanted to make a «Final Sale» report, then we can link it to a «Print Sale Info» button that appears in the form view only when the property is «Sold».

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

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

Зробіть звіт

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

Exercise

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

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

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

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

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

Підшаблони

Примітка

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

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

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

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

Exercise

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

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

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

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

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

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

Примітка

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

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

Inheritance in QWeb uses the same xpath elements as views inheritance. A QWeb template refers to its parent template in a different way though. It is even easier to do by just adding the inherit_id attribute to the template element and setting it equal to the module.parent_template_id.

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

Exercise

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

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

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

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

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

Переклади

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

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

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

Штрих-коди

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