mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-28 05:36:46 +00:00
Merge remote-tracking branch 'inventree/master'
This commit is contained in:
Oliver Walters
commit
fd2d78fe1d
@ -107,19 +107,6 @@ static_root: '../inventree_static'
|
||||
# If unspecified, the local user's temp directory will be used
|
||||
#backup_dir: '/home/inventree/backup/'
|
||||
|
||||
# LaTeX report rendering
|
||||
# InvenTree uses the django-tex plugin to enable LaTeX report rendering
|
||||
# Ref: https://pypi.org/project/django-tex/
|
||||
# Note: Ensure that a working LaTeX toolchain is installed and working *before* starting the server
|
||||
latex:
|
||||
# Select the LaTeX interpreter to use for PDF rendering
|
||||
# Note: The intepreter needs to be installed on the system!
|
||||
# e.g. to install pdflatex: apt-get texlive-latex-base
|
||||
enabled: False
|
||||
interpreter: pdflatex
|
||||
# Extra options to pass through to the LaTeX interpreter
|
||||
options: ''
|
||||
|
||||
# Permit custom authentication backends
|
||||
#authentication_backends:
|
||||
# - 'django.contrib.auth.backends.ModelBackend'
|
||||
|
||||
BIN
docs/assets/images/report/report_debug_mode.png
Normal file
BIN
docs/assets/images/report/report_debug_mode.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
docs/assets/images/report/report_default_page_size.png
Normal file
BIN
docs/assets/images/report/report_default_page_size.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
@ -14,7 +14,7 @@ Multiple plugins are supported:
|
||||
|
||||
### Reporting Plugins
|
||||
|
||||
InvenTree can generate customized reports (for example stocktake information, packing lists, acceptance test reports, etc). The reporting interface is extremely versatile, allowing the generation of reports in multiple formats (PDF / LaTeX / etc).
|
||||
InvenTree can generate customized reports (for example stocktake information, packing lists, acceptance test reports, etc).
|
||||
|
||||
!!! missing "TODO"
|
||||
Include more information here on reporting plugins
|
||||
|
||||
@ -8,6 +8,22 @@ title: v0.1.5
|
||||
|
||||
## New Features
|
||||
|
||||
### Report Templates
|
||||
|
||||
Support for report templates has been greatly improved, moving towards "out of the box" support for various reports.
|
||||
|
||||
[#1270](https://github.com/inventree/InvenTree/pull/1270) represents a significant refactor of code, and tooling for report functionality.
|
||||
|
||||
[#1279](https://github.com/inventree/InvenTree/pull/1279) adds the following report features:
|
||||
|
||||
- Adjustable page size for generated reports
|
||||
- Debug mode (renders reports as simple HTML files)
|
||||
|
||||
Refer to the [report documentation](../../report/report) for further information.
|
||||
|
||||
!!! warning "LaTeX Support"
|
||||
LaTeX report templates are no longer supported for a number of technical and ideological reasons
|
||||
|
||||
## Major Bug Fixes
|
||||
| PR | Description |
|
||||
| --- | --- |
|
||||
|
||||
@ -6,62 +6,189 @@ title: Report Generation
|
||||
|
||||
InvenTree supports a customizable reporting ecosystem, allowing the user to develop reporting templates that meet their particular needs.
|
||||
|
||||
PDF reports can be generated from either [HTML](https://github.com/fdemmer/django-weasyprint) or [LaTeX](https://github.com/weinbusch/django-tex) template files which are written by the user.
|
||||
PDF reports are generated from custom HTML template files which are written by the user.
|
||||
|
||||
Reports are used in a variety of situations to format data in a friendly format for printing, distribution, conformance and testing.
|
||||
|
||||
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 Types
|
||||
### WeasyPrint Templates
|
||||
|
||||
Following is a list of available report types
|
||||
InvenTree report templates utilize the powerful [WeasyPrint](https://weasyprint.org/) PDF generation engine.
|
||||
|
||||
* [Test Report](../test): Format results of a test report against for a particular StockItem
|
||||
* [Packing List](../pack): Format a list of items for shipping or transfer
|
||||
* [Order List](../order): Order line items
|
||||
!!! info "WeasyPrint"
|
||||
WeasyPrint is an extremely powerful and flexible reporting library. Refer to the [WeasyPrint docs](https://weasyprint.readthedocs.io/en/stable/) for further information.
|
||||
|
||||
## Template Formats
|
||||
### Stylesheets
|
||||
|
||||
Report templates can be written in multiple formats as per the requirement of the user. Uploaded template files are passed through the django/jinja rendering framework, and as such accept the same variable template strings as any other django template file.
|
||||
Templates are rendered using standard HTML / CSS - if you are familiar with web page layout, you're ready to go!
|
||||
|
||||
### Template Language
|
||||
|
||||
Uploaded report template files are passed through the [django template rendering framework](https://docs.djangoproject.com/en/dev/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.
|
||||
|
||||
### Variables
|
||||
|
||||
Each report template is provided a set of *context variables* which can be used when rendering the template.
|
||||
|
||||
For example, rendering the name of a part (which is available in the particular template context as *part*) is as follows:
|
||||
|
||||
*The name of the part is **\{\{ part.name \}\}**.*
|
||||
```html
|
||||
{% raw %}
|
||||
|
||||
<!-- Template variables use {{ double_curly_braces }} -->
|
||||
<h2>Part: {{ part.name }}</h3>
|
||||
<p><i>
|
||||
Description:<br>
|
||||
{{ part.description }}
|
||||
</p></i>
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
!!! info "Variables"
|
||||
Templates will have different variables available to them depending on the report type. Read the detail information on each report type for further information.
|
||||
Templates will have different variables available to them depending on the report type. Read the detail information on each report type for further information.
|
||||
|
||||
### HTML
|
||||
### Conditional Rendering
|
||||
|
||||
HTML templating uses the [django-weasyprint](https://github.com/fdemmer/django-weasyprint) engine for rendering templated HTML files to PDF.
|
||||
The django template system allows for conditional rendering, providing conditional flow statements such as `{% raw %}{% if <condition> %}{% endraw %}`, `{% raw %}{% for <item> in <list> %}{% endraw %}`, etc.
|
||||
|
||||
### LaTeX
|
||||
!!! info "Conditionals"
|
||||
Refer to the django documentation for more information.
|
||||
|
||||
LaTeX templating uses the [django-tex](https://github.com/weinbusch/django-tex) engine for rendering templated LaTeX files to PDF. Using LaTeX templates is much more complicated and requires advanced knowledge of configuring a LaTeX install. However it provides a much more powerful framework for generation of publication-quality documents.
|
||||
## Report Options
|
||||
|
||||
!!! info "LaTeX Configuration"
|
||||
To use LaTeX templating, the system where InvenTree is installed must have a LaTeX toolchain accessible from the command line. Installation of such a toolchain is beyond the scope of this documenation.
|
||||
A number of global reporting options are available for customizing InvenTree reports:
|
||||
|
||||
!!! info "Special Characters"
|
||||
Special care must be taken to ensure that the LaTeX template file does not contain any LaTeX control characters that look like jinja template control codes!
|
||||
### Default Page Size
|
||||
|
||||
#### Intepreter Selection
|
||||
The built-in InvenTree report templates (and any reports which are derived from the built-in templates) use the *Page Size* option to set the page size of the generated reports.
|
||||
|
||||
Out of the box, the LaTeX template rendering system is set to use *pdflatex* as the LaTeX interpreter. However this can easily be changed in the *config.yaml* configuration file:
|
||||
{% with id="report_page_size", url="report/report_default_page_size.png", description="Report Page Size" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
``` yaml
|
||||
## LaTeX report rendering
|
||||
## InvenTree uses the django-tex plugin to enable LaTeX report rendering
|
||||
## Ref: https://pypi.org/project/django-tex/
|
||||
latex:
|
||||
## Select the LaTeX interpreter to use for PDF rendering
|
||||
## Note: The intepreter needs to be installed on the system!
|
||||
## e.g. to install pdflatex: apt-get texlive-latex-base
|
||||
interpreter: pdflatex
|
||||
## Extra options to pass through to the LaTeX interpreter
|
||||
options: ''
|
||||
```
|
||||
!!! info "Override Page Size"
|
||||
Custom report templates do not have to make use of the *Page Size* option, although it is made available to the template context.
|
||||
|
||||
### Debug Mode
|
||||
|
||||
As templates are rendered directly to a PDF object, it can be difficult to debug problems when the PDF does not render exactly as expected.
|
||||
|
||||
Setting the *Debug Mode* option renders the template as raw HTML instead of PDF, allowing the rendering output to be introspected. This feature allows template designers to understand any issues with the generated HTML (before it is passed to the PDF generation engine).
|
||||
|
||||
{% with id="report_debu_mode", url="report/report_debug_mode.png", description="Report Debug Mode" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
!!! warning "HTML Rendering Limitations"
|
||||
When rendered in debug mode, @page attributes (such as size, etc) will **not** be observed. Additionally, any asset files stored on the InvenTree server will not be rendered. Debug mode is not intended to produce "good looking" documents!
|
||||
|
||||
## Uploading Templates
|
||||
|
||||
Custom report templates can be uploaded using the [Admin Interface](../../admin/admin). Only users with admin access can upload and/or edit report template files.
|
||||
Custom report templates can be uploaded using the [Admin Interface](../../admin/admin). Only users with admin access can upload and/or edit report template files.
|
||||
|
||||
## Report Assets
|
||||
|
||||
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 uploaded via the admin interface.
|
||||
|
||||
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.
|
||||
|
||||
## 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 re-used 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.
|
||||
|
||||
Similar to assets files, snippet template files are uploaded via the admin interface.
|
||||
|
||||
Snippets are included in a template as follows:
|
||||
|
||||
```
|
||||
{% raw %}{% include 'snippets/<snippet_name.html>' %}{% endraw %}
|
||||
```
|
||||
|
||||
For example, consider a 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` is as follows:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
<!-- stock_row snippet -->
|
||||
<tr>
|
||||
<td>{{ item.part.full_name }}</td>
|
||||
<td>{{ item.quantity }}</td>
|
||||
</tr>
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
## Report Types
|
||||
|
||||
InvenTree supports the following reporting functionality:
|
||||
|
||||
### Test Report
|
||||
|
||||
[Test Report](../test): Format results of a test report against for a particular StockItem
|
||||
|
||||
### Packing List
|
||||
[Packing List](../pack): Format a list of items for shipping or transfer
|
||||
|
||||
### Build Report
|
||||
|
||||
Build Report: TODO
|
||||
|
||||
### Purchase Order
|
||||
[Purchase Order report](../order): Order line items
|
||||
|
||||
### Sales Order
|
||||
Sales Order: TODO
|
||||
|
||||
### Stocktake
|
||||
Stocktake Report: TODO
|
||||
|
||||
@ -148,13 +148,6 @@ The default behaviour of the database backup is to generate backup files for dat
|
||||
|
||||
Alternatively this location can be specified with the `INVENTREE_BACKUP_DIR` environment variable.
|
||||
|
||||
### LaTeX Support
|
||||
|
||||
To enable genration of [LaTeX](https://en.wikipedia.org/wiki/LaTeX) reports, latex support must be enabled here.
|
||||
|
||||
- **enabled** : Set to True to enable LaTeX support
|
||||
- **interpreter** : Select the LaTeX interpreter to be used (must be installed on the local machine!)
|
||||
|
||||
### Authentication Backends
|
||||
|
||||
Custom authentication backends can be used by specifying them here
|
||||
|
||||
@ -52,3 +52,19 @@ inv import-records -f data.json
|
||||
|
||||
!!! warning "Character Encoding"
|
||||
If the character encoding of the data file does not exactly match the target database, the import operation may not succeed. In this case, some manual editing of the database JSON file may be required.
|
||||
|
||||
### Backup and Restore
|
||||
|
||||
To backup your database data and media files, first define a [Backup Location](../config/#backup-location) in your configuration file.
|
||||
|
||||
Then run the following command to backup the data:
|
||||
```
|
||||
inv backup
|
||||
```
|
||||
|
||||
It should create two separate backup files in the [Backup Location](../config/#backup-location) folder: one for the database data and one for the media files (part pictures, etc.)
|
||||
|
||||
To restore your data from a backup, use the following command:
|
||||
```
|
||||
inv restore
|
||||
```
|
||||
|
||||
@ -70,11 +70,12 @@ nav:
|
||||
- Purchase Orders: companies/po.md
|
||||
- Sales Orders: companies/so.md
|
||||
- Report:
|
||||
- Labels: report/labels.md
|
||||
- Templates: report/report.md
|
||||
- Test Reports: report/test.md
|
||||
- Packing List: report/pack.md
|
||||
- Order: report/order.md
|
||||
- Reports:
|
||||
- Test Reports: report/test.md
|
||||
- Packing List: report/pack.md
|
||||
- Order: report/order.md
|
||||
- Labels: report/labels.md
|
||||
- Admin:
|
||||
- Admin Interface: admin/admin.md
|
||||
- User Permissions: admin/permissions.md
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user