[docs] Report helper docs (#12300)

* [docs] Report helper docs * Split out docs for assets and snippets * Updates
2026-07-04 06:00:38 +00:00 · 2026-07-03 21:40:28 +10:00
parent 4895fbc9fe
commit f656ac7263
10 changed files with 239 additions and 121 deletions
@@ -4,15 +4,57 @@ title: Report Mixin
 ## ReportMixin
-The `ReportMixin` class provides a plugin with the ability to extend the functionality of custom [report templates](../../report/report.md). A plugin which implements the ReportMixin mixin class can add custom context data to a report template for rendering.
+The `ReportMixin` class provides a plugin with the ability to extend the functionality of custom [report templates](../../report/report.md). A plugin which implements the ReportMixin mixin class can add custom context data to a report template for rendering, and can also receive a callback when a report is generated.
 ### Add Report Context
 A plugin which implements the ReportMixin mixin can define the `add_report_context` method, allowing custom context data to be added to a report template at time of printing.
 This method is called each time a report is generated, and is passed the following arguments:
 | Argument | Description |
 | --- | --- |
 | `report_instance` | The report template instance which is being rendered |
 | `model_instance` | The model instance against which the report is being generated |
 | `user` | The user who initiated the report generation |
 | `context` | The context dictionary, which can be modified in-place |
 Any data added to the provided `context` dictionary is made available to the report template, and can be rendered using standard django template syntax:
 ```python
 def add_report_context(self, report_instance, model_instance, user, context):
    """Add extra context data to the report template."""
    context['my_custom_data'] = self.calculate_custom_data(model_instance)
 ```
 ### Add Label Context
-Additionally the `add_label_context` method, allowing custom context data to be added to a label template at time of printing.
+Similarly, the `add_label_context` method allows custom context data to be added to a label template at time of printing:
 | Argument | Description |
 | --- | --- |
 | `label_instance` | The label template instance which is being rendered |
 | `model_instance` | The model instance against which the label is being generated |
 | `user` | The user who initiated the label generation |
 | `context` | The context dictionary, which can be modified in-place |
 ### Report Callback
 The `report_callback` method is called after a report has been generated, and allows the plugin to perform custom actions with the generated report - for example, forwarding the report to an external system, or performing custom post-processing.
 | Argument | Description |
 | --- | --- |
 | `template` | The report template instance which was used to generate the report |
 | `instance` | The model instance against which the report was generated |
 | `report` | The generated report (PDF file data) |
 | `user` | The user who initiated the report generation |
 ```python
 def report_callback(self, template, instance, report, user, **kwargs):
    """Custom callback function - called after a report is generated."""
    # For example, forward the generated report to an external service
    self.upload_to_external_service(report)
 ```
 ### Sample Plugin
@@ -0,0 +1,45 @@
 ---
 title: Report Assets
 ---
 ## Report Assets
 Users can upload asset files (e.g. images) which can be used when generating reports. For example, you may wish to generate a report with your company logo in the header.
 Asset files are managed from the [Admin Center](../settings/admin.md#admin-center), via the *Report Assets* panel. Staff users can upload new asset files, and remove assets which are no longer required.
 Asset files can be rendered directly into the template as follows
 ```html
 {% raw %}
 <!-- Need to include the report template tags at the start of the template file -->
 {% load report %}
 <!-- Simple stylesheet -->
 <head>
  <style>
    .company-logo {
      height: 50px;
    }
  </style>
 </head>
 <body>
 <!-- Report template code here -->
 <!-- Render an uploaded asset image -->
 <img src="{% asset 'company_image.png' %}" class="company-logo">
 <!-- ... -->
 </body>
 {% endraw %}
 ```
 !!! warning "Asset Naming"
    If the requested asset name does not match the name of an uploaded asset, the template will continue without loading the image.
 !!! info "Assets location"
    Upload new assets via the *Report Assets* panel in the [Admin Center](../settings/admin.md#admin-center) to ensure they are uploaded to the correct location on the server.
 There are various [helper functions](./helpers.md#report-assets) available to assist with embedding assets into templates.
@@ -69,12 +69,14 @@ Templates (whether for generating [reports](./report.md) or [labels](./labels.md
 | Model Type | Description |
 | --- | --- |
-| company | A Company instance |
+| [company](#company) | A Company instance |
 | [build](#build-order) | A [Build Order](../manufacturing/build.md) instance |
 | [buildline](#build-line) | A [Build Order Line Item](../manufacturing/build.md) instance |
 | [salesorder](#sales-order) | A [Sales Order](../sales/sales_order.md) instance |
 | [salesordershipment](#sales-order-shipment) | A [Sales Order Shipment](../sales/sales_order.md#sales-order-shipments) instance |
 | [returnorder](#return-order) | A [Return Order](../sales/return_order.md) instance |
 | [purchaseorder](#purchase-order) | A [Purchase Order](../purchasing/purchase_order.md) instance |
 | [transferorder](#transfer-order) | A [Transfer Order](../stock/transfer_order.md) instance |
 | [stockitem](#stock-item) | A [StockItem](../stock/index.md#stock-item) instance |
 | [stocklocation](#stock-location) | A [StockLocation](../stock/index.md#stock-location) instance |
 | [part](#part) | A [Part](../part/index.md) instance |
@@ -141,6 +143,16 @@ When printing a report or label against a [PurchaseOrder](../purchasing/purchase
 {{ report_context("models", "purchaseorder") }}
 ### Transfer Order
 When printing a report or label against a [TransferOrder](../stock/transfer_order.md) object, the following context variables are available:
 {{ report_context("models", "transferorder") }}
 ::: order.models.TransferOrder.report_context
    options:
        show_source: True
 ### Stock Item
 When printing a report or label against a [StockItem](../stock/index.md#stock-item) object, the following context variables are available:
@@ -173,7 +185,7 @@ When printing a report or label against a [Part](../part/index.md) object, the f
 ## Model Variables
-Additional to the context variables provided directly to each template, each model type has a number of attributes and methods which can be accessedd via the template.
+Additional to the context variables provided directly to each template, each model type has a number of attributes and methods which can be accessed via the template.
 For each model type, a subset of the most commonly used attributes are listed below. For a full list of attributes and methods, refer to the source code for the particular model type.
@@ -187,7 +199,6 @@ Each part object has access to a lot of context variables about the part. The fo
 |----------|-------------|
 | name | Brief name for this part |
 | full_name | Full name for this part (including IPN, if not null and including variant, if not null) |
 | variant | Optional variant number for this part - Must be unique for the part name
 | category | The [PartCategory](#part-category) object to which this part belongs
 | description | Longer form description of the part
 | keywords | Optional keywords for improving part search results
@@ -244,7 +255,6 @@ Each part object has access to a lot of context variables about the part. The fo
 | Variable | Description |
 |----------|-------------|
 | parent | Link to another [StockItem](#stock-item) from which this StockItem was created |
 | uid | Field containing a unique-id which is mapped to a third-party identifier (e.g. a barcode) |
 | part | Link to the master abstract [Part](#part) that this [StockItem](#stock-item) is an instance of |
 | supplier_part | Link to a specific [SupplierPart](#supplierpart) (optional) |
 | location | The [StockLocation](#stock-location) Where this [StockItem](#stock-item) is located |
@@ -263,7 +273,6 @@ Each part object has access to a lot of context variables about the part. The fo
 | build | Link to a Build (if this stock item was created from a build) |
 | is_building | Boolean field indicating if this stock item is currently being built (or is "in production") |
 | purchase_order | Link to a [PurchaseOrder](#purchase-order) (if this stock item was created from a PurchaseOrder) |
 | infinite | If True this [StockItem](#stock-item) can never be exhausted |
 | sales_order | Link to a [SalesOrder](#sales-order) object (if the StockItem has been assigned to a SalesOrder) |
 | purchase_price | The unit purchase price for this [StockItem](#stock-item) - this is the unit price at time of purchase (if this item was purchased from an external supplier) |
 | packaging | Description of how the StockItem is packaged (e.g. "reel", "loose", "tape" etc) |
@@ -353,7 +362,7 @@ Each part object has access to a lot of context variables about the part. The fo
 | Variable | Description |
 |----------|-------------|
 | username | the username of the user |
-| fist_name | The first name of the user |
+| first_name | The first name of the user |
 | last_name | The last name of the user |
 | email | The email address of the user |
 | pk | The primary key of the user |
@@ -907,7 +907,7 @@ If you have a custom logo, but explicitly wish to load the InvenTree logo itself
 ## Report Assets
-[Report Assets](./index.md#report-assets) are files specifically uploaded by the user for inclusion in generated reports and labels.
+[Report Assets](./assets.md) are files specifically uploaded by the user for inclusion in generated reports and labels.
 You can add asset images to the reports and labels by using the `{% raw %}{% asset ... %}{% endraw %}` template tag:
@@ -72,10 +72,24 @@ Label and report templates are created and edited using the built-in [template e
 Each report template requires a name and description, which identify and describe the report template.
 ### Revision
 Each template has a revision number, which is automatically incremented each time the template is updated. This provides a simple mechanism for tracking changes to a template over time. The revision number is read-only, and cannot be edited directly.
 !!! info "Template Revision Context"
    The revision number of the template is made available when rendering, via the `template_revision` [context variable](./context_variables.md#global-context).
 ### Enabled Status
 Boolean field which determines if the specific report template is enabled, and available for use. Reports can be disabled to remove them from the list of available templates, but without deleting them from the database.
 ### Attach to Model
 If the *Attach to Model on Print* option is enabled, a copy of the generated report is automatically saved as a file attachment against the item (model instance) for which it was generated, each time the template is printed.
 !!! warning "Attachment Support"
    The report output is only attached if the target model type supports file attachments.
 ### Filename Pattern
 The filename pattern used to generate the output `.pdf` file. Defaults to "report.pdf".
@@ -147,93 +161,15 @@ Setting the *Debug Mode* option renders the template as raw HTML instead of PDF,
 ## Report Assets
-Users can upload asset files (e.g. images) which can be used when generating reports. For example, you may wish to generate a report with your company logo in the header.
+User can upload asset files (e.g. images) which can be used when generating reports. For example, you may wish to generate a report with your company logo in the header.
 Asset files are managed from the [Admin Center](../settings/admin.md#admin-center), via the *Report Assets* panel. Staff users can upload new asset files, and remove assets which are no longer required.
 Asset files can be rendered directly into the template as follows
 ```html
 {% raw %}
 <!-- Need to include the report template tags at the start of the template file -->
 {% load report %}
 <!-- Simple stylesheet -->
 <head>
  <style>
    .company-logo {
      height: 50px;
    }
  </style>
 </head>
 <body>
 <!-- Report template code here -->
 <!-- Render an uploaded asset image -->
 <img src="{% asset 'company_image.png' %}" class="company-logo">
 <!-- ... -->
 </body>
 {% endraw %}
 ```
 !!! warning "Asset Naming"
    If the requested asset name does not match the name of an uploaded asset, the template will continue without loading the image.
 !!! info "Assets location"
    Upload new assets via the *Report Assets* panel in the [Admin Center](../settings/admin.md#admin-center) to ensure they are uploaded to the correct location on the server.
 Refer to the [report assets](./assets.md) documentation for further information.
 ## Report Snippets
-A powerful feature provided by the django / WeasyPrint templating framework is the ability to include external template files. This allows commonly used template features to be broken out into separate files and reused across multiple templates.
+InvenTree provides report "snippets" - reusable template files which cannot be rendered by themselves, but can be included in other templates.
-To support this, InvenTree provides report "snippets" - short (or not so short) template files which cannot be rendered by themselves, but can be called from other templates.
+Refer to the [report snippets](./snippets.md) documentation for further information.
 Snippet files are managed from the [Admin Center](../settings/admin.md#admin-center), via the *Report Snippets* panel. Staff users can upload new snippet files, and edit or remove existing snippets.
 Additionally, the content of an existing snippet can be modified directly within the browser - simply select a snippet from the table to open it in the built-in code editor.
 Snippets are included in a template as follows:
 ```
 {% raw %}{% include 'snippets/<snippet_name.html>' %}{% endraw %}
 ```
 For example, consider a custom stocktake report for a particular stock location, where we wish to render a table with a row for each item in that location.
 ```html
 {% raw %}
 <table class='stock-table'>
  <thead>
    <!-- table header data -->
  </thead>
  <tbody>
    {% for item in location.stock_items %}
    {% include 'snippets/stock_row.html' with item=item %}
    {% endfor %}
  </tbody>
 {% endraw %}
 ```
 !!! info "Snippet Arguments"
    Note above that named argument variables can be passed through to the snippet!
 And the snippet file `stock_row.html` may be written as follows:
 ```html
 {% raw %}
 <!-- stock_row snippet -->
 <tr>
  <td>{{ item.part.full_name }}</td>
  <td>{{ item.quantity }}</td>
 </tr>
 {% endraw %}
 ```
 ## Security
@@ -263,6 +199,6 @@ When enabled, URLs are still validated against private, loopback, link-local, an
 ### Asset Files
-Asset files uploaded through the admin interface are embedded directly into the rendered PDF as base64 `data:` URIs — they are read via the Django storage API and never loaded through WeasyPrint's URL fetcher. This means assets work correctly regardless of whether remote URL fetching is enabled, and also work with remote storage backends such as S3.
+[Asset files](./assets.md) uploaded through the admin interface are embedded directly into the rendered PDF as base64 `data:` URIs — they are read via the Django storage API and never loaded through WeasyPrint's URL fetcher. This means assets work correctly regardless of whether remote URL fetching is enabled, and also work with remote storage backends such as S3.
 There are various [helper functions](./helpers.md#report-assets) available to assist with embedding assets into templates.
@@ -128,6 +128,25 @@ As an example, consider a label template for a StockItem. A user may wish to def
 To restrict the label accordingly, we could set the *filters* value to `part__IPN=IPN123`.
 ## Printing Labels
 Labels are printed directly from the web interface, from the pages where the target items are displayed. To print labels against one or more items:
 1. Select the items to print - either from a table (using the row checkboxes), or by viewing the detail page of a single item
 2. Select the *Print* action, and choose the *Print Label* option
 3. Select the desired label template - only *enabled* templates which match the selected model type (and pass any template filters) are available for selection
 4. Select the *printer* (plugin) to use for printing the labels
 ### Label Printing Plugins
 The actual printing of labels is handled by a [label printing plugin](../plugins/mixins/label.md). InvenTree provides a number of built-in printing plugins:
 - The default [InvenTree Label Printer](../plugins/builtin/inventree_label.md) plugin generates a PDF file, which is then made available for download.
 - The [Label Sheet](../plugins/builtin/inventree_label_sheet.md) plugin arranges multiple labels onto a single sheet for printing.
 - The [Label Machine](../plugins/builtin/inventree_label_machine.md) plugin sends the label to an external [label printer machine](../plugins/machines/label_printer.md).
 Custom label printing plugins (e.g. for driving a specific hardware printer) can be installed to extend this list - refer to the [label mixin documentation](../plugins/mixins/label.md) for further information.
 ## Built-In Templates
 The InvenTree installation provides a number of simple *default* templates which can be used as a starting point for creating custom labels. These built-in templates can be disabled if they are not required.
@@ -1,49 +1,47 @@
 ---
-title: Report and Label Generation
+title: Report Templates
 ---
-## Custom Reports
+## Report Templates
-InvenTree supports a customizable reporting ecosystem, allowing the user to develop document templates that meet their particular needs.
+Report templates are used to generate formal PDF documents - such as order reports, packing lists, or test reports - rendered against a particular database item (or list of items).
-PDF files are generated from custom HTML template files which are written by the user.
+Like all InvenTree templates, report templates are written using a mixture of HTML / CSS and the django template language, and are rendered to a PDF file using the WeasyPrint engine:
-Templates can be used to generate *reports* or *labels* which can be  used in a variety of situations to format data in a friendly format for printing, distribution, conformance and testing.
+- Refer to the [template overview](./index.md) for information on creating and managing templates.
 - Refer to the [template rendering documentation](./weasyprint.md) for information on the WeasyPrint engine and the django template language.
 - Refer to the [context variables documentation](./context_variables.md) for the variables available when rendering a template.
-In addition to providing the ability for end-users to provide their own reporting templates, some report types offer "built-in" report templates ready for use.
+## Report Options
-### WeasyPrint Templates
+In addition to the [options common to all templates](./index.md#creating-templates), each report template provides the following options:
-InvenTree report templates utilize the powerful [WeasyPrint](https://weasyprint.org/) PDF generation engine.
+### Page Size
-!!! info "WeasyPrint"
+The page size (e.g. `A4` or `Letter`) used when rendering the report to a PDF file. When a new report template is created, this value defaults to the [default page size](./index.md#default-page-size) specified in the global settings.
    WeasyPrint is an extremely powerful and flexible reporting library. Refer to the [WeasyPrint docs](https://doc.courtbouillon.org/weasyprint/stable/) for further information.
-### Stylesheets
+### Landscape
-Templates are rendered using standard HTML / CSS - if you are familiar with web page layout, you're ready to go!
+If enabled, the report is rendered in landscape orientation, rather than the default portrait orientation.
-### Template Language
+### Merge
-Uploaded report template files are passed through the [django template rendering framework]({% include "django.html" %}/topics/templates/), and as such accept the same variable template strings as any other django template file. Different variables are passed to the report template (based on the context of the report) and can be used to customize the contents of the generated PDF.
+If enabled, a single report document is generated for all selected items, rather than a separate document for each item. Refer to the [merging reports](#merging-reports) section below for further information.
-### Variables
+!!! info "Context Variables"
    The `page_size`, `landscape` and `merge` values are also made available to the template as [context variables](./context_variables.md#report-context).
-Each report template is provided a set of *context variables* which can be used when rendering the template.
+## Generating Reports
-For example, rendering the name of a part (which is available in the particular template context as `part`) is as follows:
+Reports are generated directly from the web interface, from the pages where the target items are displayed. To generate a report against one or more items:
-```html
+1. Select the items to print - either from a table (using the row checkboxes), or by viewing the detail page of a single item
-{% raw %}
+2. Select the *Print* action, and choose the *Print Report* option
 3. Select the desired report template - only *enabled* templates which match the selected model type (and pass any [template filters](./index.md#template-filters)) are available for selection
 4. The report is generated by the server, and the resulting PDF file is made available for download
-<!-- Template variables use {{ double_curly_braces }} -->
+!!! info "Enable Reports"
-<h2>Part: {{ part.name }}</h3>
+    Report generation must be [enabled in the global settings](./index.md#enable-reports) before reports can be generated.
 <p><i>
  Description:<br>
  {{ part.description }}
 </p></i>
 {% endraw %}
 ```
 ## Merging Reports
@@ -22,6 +22,7 @@ The following report templates are provided "out of the box" and can be used as
 | [Sales Order Shipment](#sales-order-shipment) | [SalesOrderShipment](../sales/sales_order.md) | Sales Order Shipment report |
 | [Stock Location](#stock-location) | [StockLocation](../stock/index.md#stock-location) | Stock Location report |
 | [Test Report](#test-report) | [StockItem](../stock/index.md#stock-item) | Test Report |
 | [Transfer Order](#transfer-order) | [TransferOrder](../stock/transfer_order.md) | Transfer Order report |
 | [Selected Stock Items Report](#selected-stock-items-report) | [StockItem](../stock/index.md#stock-item) | Selected Stock Items report |
@@ -57,6 +58,10 @@ The following report templates are provided "out of the box" and can be used as
 {{ templatefile("report/inventree_test_report.html") }}
 ### Transfer Order
 {{ templatefile("report/inventree_transfer_order_report.html") }}
 ### Selected Stock Items Report
 {{ templatefile("report/inventree_stock_report_merge.html") }}
@@ -68,9 +73,11 @@ The following label templates are provided "out of the box" and can be used as a
 | Template | Model Type | Description |
 | --- | --- | --- |
 | [Build Line](#build-line-label) | [Build line item](../manufacturing/build.md) | Build Line label |
-| [Part](#part-label) | [Part](../part/index.md) | Part label |
+| [Part](#part-label) | [Part](../part/index.md) | Part label (QR code and part name) |
 | [Part (Code128)](#part-label-code128) | [Part](../part/index.md) | Part label (Code128 barcode) |
 | [Stock Item](#stock-item-label) | [StockItem](../stock/index.md#stock-item) | Stock Item label |
-| [Stock Location](#stock-location-label) | [StockLocation](../stock/index.md#stock-location) | Stock Location label |
+| [Stock Location](#stock-location-label) | [StockLocation](../stock/index.md#stock-location) | Stock Location label (QR code) |
 | [Stock Location (with text)](#stock-location-label-with-text) | [StockLocation](../stock/index.md#stock-location) | Stock Location label (QR code and location details) |
 ### Build Line Label
@@ -78,6 +85,10 @@ The following label templates are provided "out of the box" and can be used as a
 ### Part Label
 {{ templatefile("label/part_label.html") }}
 ### Part Label (Code128)
 {{ templatefile("label/part_label_code128.html") }}
 ### Stock Item Label
@@ -86,4 +97,8 @@ The following label templates are provided "out of the box" and can be used as a
 ### Stock Location Label
 {{ templatefile("label/stocklocation_qr.html") }}
 ### Stock Location Label (with text)
 {{ templatefile("label/stocklocation_qr_and_text.html") }}
@@ -0,0 +1,52 @@
 ---
 title: Report Snippets
 ---
 ## Report Snippets
 A powerful feature provided by the django / WeasyPrint templating framework is the ability to include external template files. This allows commonly used template features to be broken out into separate files and reused across multiple templates.
 To support this, InvenTree provides report "snippets" - short (or not so short) template files which cannot be rendered by themselves, but can be called from other templates.
 Snippet files are managed from the [Admin Center](../settings/admin.md#admin-center), via the *Report Snippets* panel. Staff users can upload new snippet files, and edit or remove existing snippets.
 Additionally, the content of an existing snippet can be modified directly within the browser - simply select a snippet from the table to open it in the built-in [template editor](./template_editor.md#editing-snippets).
 Snippets are included in a template as follows:
 ```
 {% raw %}{% include 'snippets/<snippet_name.html>' %}{% endraw %}
 ```
 For example, consider a custom stocktake report for a particular stock location, where we wish to render a table with a row for each item in that location.
 ```html
 {% raw %}
 <table class='stock-table'>
  <thead>
    <!-- table header data -->
  </thead>
  <tbody>
    {% for item in location.stock_items %}
    {% include 'snippets/stock_row.html' with item=item %}
    {% endfor %}
  </tbody>
 {% endraw %}
 ```
 !!! info "Snippet Arguments"
    Note above that named argument variables can be passed through to the snippet!
 And the snippet file `stock_row.html` may be written as follows:
 ```html
 {% raw %}
 <!-- stock_row snippet -->
 <tr>
  <td>{{ item.part.full_name }}</td>
  <td>{{ item.quantity }}</td>
 </tr>
 {% endraw %}
 ```
@@ -174,6 +174,8 @@ nav:
    - Template Editor: report/template_editor.md
    - Reports: report/report.md
    - Labels: report/labels.md
    - Report Assets: report/assets.md
    - Report Snippets: report/snippets.md
    - Context Variables: report/context_variables.md
    - Helper Functions: report/helpers.md
    - Barcodes: report/barcodes.md