Label Printing Mixin

LabelPrintingMixin

The LabelPrintingMixin class allows plugins to provide custom label printing functionality. The specific implementation of a label printing plugin is quite flexible, allowing for the following functions (as a starting point):

• Printing a single label to a file, and allowing user to download
• Combining multiple labels onto a single page
• Supporting proprietary label sheet formats
• Offloading label printing to an external printer

Entry Point

When printing labels against a particular plugin, the entry point is the print_labels method. The default implementation of this method iterates over each of the provided items, renders a PDF, and calls the print_label method for each item, providing the rendered PDF data.

Both the print_labels and print_label methods may be overridden by a plugin, allowing for complex functionality to be achieved.

For example, the print_labels method could be reimplemented to merge all labels into a single larger page, and return a single page for printing.

Return Type

The print_labels method must return a JsonResponse object. If the method does not return such a response, an error will be raised by the server.

File Generation

If the label printing plugin generates a real file, it should be stored as a LabelOutput instance in the database, and returned in the JsonResponse result under the 'file' key.

For example, the built-in InvenTreeLabelPlugin plugin generates a PDF file which contains all the provided labels concatenated together. A snippet of the code is shown below (refer to the source code for full details):

# Save the generated file to the database
output = LabelOutput.objects.create(
    label=output_file,
    user=request.user
)

return JsonResponse({
    'file': output.label.url,
    'success': True,
    'message': f'{len(items)} labels generated'
})

Background Printing

For some label printing processes (such as offloading printing to an external networked printer) it may be preferable to utilize the background worker process, and not block the front-end server. The plugin provides an easy method to offload printing to the background thread.

Simply override the class attribute BLOCKING_PRINT as follows:

class MyPrinterPlugin(LabelPrintingMixin, InvenTreePlugin):
    BLOCKING_PRINT = False

If the print_labels method is not changed, this will run the print_label method in a background worker thread.

Example Plugin

Check out the inventree-brother-plugin which provides native support for the Brother QL and PT series of networked label printers

Custom Code

If your plugin overrides the print_labels method, you will have to ensure that the label printing is correctly offloaded to the background worker. Look at the offload_label method of the plugin mixin class for how this can be achieved.

Printing options

A printing plugin can define custom options as a serializer class called PrintingOptionsSerializer that get shown on the printing screen and get passed to the print_labels/print_label function as a kwarg called printing_options. This can be used to e.g. let the user dynamically select the orientation of the label, the color mode, ... for each print job. The following simple example shows how to implement an orientation select. For more information about how to define fields, refer to the django rest framework (DRF) documentation.

from rest_framework import serializers

class MyLabelPrinter(LabelPrintingMixin, InvenTreePlugin):
    ...

    class PrintingOptionsSerializer(serializers.Serializer):
        orientation = serializers.ChoiceField(choices=[
            ("landscape", "Landscape"),
            ("portrait", "Portrait"),
        ])

    def print_label(self, **kwargs):
        print(kwargs["printing_options"]) # -> {"orientation": "landscape"}
        ...

Dynamically return a serializer instance

If your plugin wants to dynamically expose options based on the request, you can implement the get_printing_options_serializer function which by default returns an instance of the PrintingOptionsSerializer class if defined.

Helper Methods

The plugin class provides a number of additional helper methods which may be useful for generating labels:

Method	Description
render_to_pdf	Render label template to an in-memory PDF object
render_to_html	Render label template to a raw HTML string
render_to_png	Convert PDF data to an in-memory PNG image

Use the Source

These methods are available for more complex implementations - refer to the source code for more information!

Merging Labels

To merge (combine) multiple labels into a single output (for example printing multiple labels on a single sheet of paper), the plugin must override the print_labels method and implement the required functionality.

Integration

Web Integration

If label printing plugins are enabled, they are able to be used directly from the InvenTree web interface:

App Integration

Label printing plugins also allow direct printing of labels via the mobile app

Implementation

Plugins which implement the LabelPrintingMixin mixin class can be implemented by simply providing a print_label method.

Simple Example

from dummy_printer import printer_backend

class MyLabelPrinter(LabelPrintingMixin, InvenTreePlugin):
    """
    A simple example plugin which provides support for a dummy printer.

    A more complex plugin would communicate with an actual printer!
    """

    NAME = "MyLabelPrinter"
    SLUG = "mylabel"
    TITLE = "A dummy printer"

    # Set BLOCKING_PRINT to false to return immediately
    BLOCKING_PRINT = False

    def print_label(self, **kwargs):
        """
        Send the label to the printer

        kwargs:
            pdf_file: The PDF file object of the rendered label (WeasyTemplateResponse object)
            pdf_data: Raw PDF data of the rendered label
            filename: The filename of this PDF label
            label_instance: The instance of the label model which triggered the print_label() method
            item_instance: The instance of the database model against which the label is printed
            user: The user who triggered this print job
            width: The expected width of the label (in mm)
            height: The expected height of the label (in mm)
            printing_options: The printing options set for this print job defined in the PrintingOptionsSerializer
        """

        width = kwargs['width']
        height = kwargs['height']

        # This dummy printer supports printing of raw image files
        printer_backend.print(png_file, w=width, h=height)

Default Plugin

InvenTree supplies the InvenTreeLabelPlugin out of the box, which generates a PDF file which is then available for immediate download by the user.

The default plugin also features a DEBUG mode which generates a raw HTML output, rather than PDF. This can be handy for tracking down any template rendering errors in your labels.

Builtin plugin for label printing.

This plugin merges the selected labels into a single PDF file, which is made available for download.

Source code in src/backend/InvenTree/plugin/builtin/labels/inventree_label.py

class InvenTreeLabelPlugin(LabelPrintingMixin, SettingsMixin, InvenTreePlugin):
    """Builtin plugin for label printing.

    This plugin merges the selected labels into a single PDF file,
    which is made available for download.
    """

    NAME = 'InvenTreeLabel'
    TITLE = _('InvenTree PDF label printer')
    DESCRIPTION = _('Provides native support for printing PDF labels')
    VERSION = '1.1.0'
    AUTHOR = _('InvenTree contributors')

    BLOCKING_PRINT = True

    SETTINGS = {
        'DEBUG': {
            'name': _('Debug mode'),
            'description': _('Enable debug mode - returns raw HTML instead of PDF'),
            'validator': bool,
            'default': False,
        }
    }

    # Keep track of individual label outputs
    # These will be stitched together at the end of printing
    outputs = []

    def before_printing(self):
        """Reset the list of label outputs."""
        self.outputs = []

    def print_label(self, **kwargs):
        """Print a single label."""
        label = kwargs['label_instance']
        instance = kwargs['item_instance']

        if str2bool(self.get_setting('DEBUG')):
            # In debug mode, return raw HTML output
            output = self.render_to_html(label, instance, None, **kwargs)
        else:
            # Output is already provided
            output = kwargs['pdf_file']

        self.outputs.append(output)

    def get_generated_file(self, **kwargs):
        """Return the generated file, by stitching together the individual label outputs."""
        if len(self.outputs) == 0:
            return None

        if str2bool(self.get_setting('DEBUG')):
            # Simple HTML output
            data = '\n'.join(self.outputs)
            filename = 'labels.html'
        else:
            # Stitch together the PDF outputs
            pages = []

            for output in self.outputs:
                doc = output.get_document()

                for page in doc.pages:
                    pages.append(page)

            data = self.outputs[0].get_document().copy(pages).write_pdf()
            filename = kwargs.get('filename', 'labels.pdf')

        return ContentFile(data, name=filename)

Available Data

The label data are supplied to the plugin in both PDF and PNG formats. This provides compatibility with a great range of label printers "out of the box". Conversion to other formats, if required, is left as an exercise for the plugin developer.

Other arguments provided to the print_label function are documented in the code sample above.