diff --git a/docs/docs/report/assets.md b/docs/docs/report/assets.md new file mode 100644 index 0000000000..52119073c5 --- /dev/null +++ b/docs/docs/report/assets.md @@ -0,0 +1,43 @@ +--- +title: Report Assets +--- + +## 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 %} + +{% load report %} + + + + + + + + + + + + + + + +{% 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 [admin interface](../settings/admin.md) 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. diff --git a/docs/docs/report/helpers.md b/docs/docs/report/helpers.md index 1cde507797..dbbe7306ad 100644 --- a/docs/docs/report/helpers.md +++ b/docs/docs/report/helpers.md @@ -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: diff --git a/docs/docs/report/index.md b/docs/docs/report/index.md index 8f552255a7..59ebc10c72 100644 --- a/docs/docs/report/index.md +++ b/docs/docs/report/index.md @@ -161,89 +161,15 @@ Setting the *Debug Mode* option renders the template as raw HTML instead of PDF, ## 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 %} - -{% load report %} - - - - - - - - - - - - - - - -{% 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 [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server. +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. +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. - -Similar to assets files, snippet template files are uploaded via the admin interface. - -Snippets are included in a template as follows: - -``` -{% raw %}{% include 'snippets/' %}{% 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 %} - - - - - - - {% for item in location.stock_items %} - {% include 'snippets/stock_row.html' with item=item %} - {% endfor %} - - -{% 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 %} - - - - - -{% endraw %} -``` +Refer to the [report snippets](./snippets.md) documentation for further information. ## Security @@ -273,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. diff --git a/docs/docs/report/snippets.md b/docs/docs/report/snippets.md new file mode 100644 index 0000000000..6452d8eba6 --- /dev/null +++ b/docs/docs/report/snippets.md @@ -0,0 +1,50 @@ +--- +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. + +Similar to [assets files](./assets.md), snippet template files are uploaded via the admin interface. + +Snippets are included in a template as follows: + +``` +{% raw %}{% include 'snippets/' %}{% 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 %} + +
{{ item.part.full_name }}{{ item.quantity }}
+ + + + + {% for item in location.stock_items %} + {% include 'snippets/stock_row.html' with item=item %} + {% endfor %} + + +{% 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 %} + + + + + +{% endraw %} +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ca20e704c7..f24d8db82c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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
{{ item.part.full_name }}{{ item.quantity }}