.. highlight:: python
   :linenothreshold: 5

Writing an invoice renderer plugin
==================================

An invoice renderer controls how invoice files are built.
The creation of such a plugin is very similar to creating an export output.

Please read :ref:`Creating a plugin <pluginsetup>` first, if you haven't already.

Output registration
-------------------

The invoice renderer API does not make a lot of usage from signals, however, it
does use a signal to get a list of all available invoice renderers. Your plugin
should listen for this signal and return the subclass of ``eventyay.base.invoice.BaseInvoiceRenderer``
that we'll provide in this plugin:

.. code-block:: python

    from django.dispatch import receiver

    from eventyay.base.signals import register_invoice_renderers


    @receiver(register_invoice_renderers, dispatch_uid="output_custom")
    def register_invoice_renderers(sender, **kwargs):
        from .invoice import MyInvoiceRenderer
        return MyInvoiceRenderer


The renderer class
------------------

.. class:: eventyay.base.invoice.BaseInvoiceRenderer

   The central object of each invoice renderer is the subclass of ``BaseInvoiceRenderer``.

   .. py:attribute:: BaseInvoiceRenderer.event

      The default constructor sets this property to the event we are currently
      working for.

   .. py:attribute:: identifier

      A short and unique identifier for this invoice renderer.

      This is an abstract attribute, you **must** override this!

   .. py:attribute:: verbose_name

      A human-readable name for this invoice renderer.

      This is an abstract attribute, you **must** override this!

   .. py:method:: generate(invoice)

      Generate the invoice file.

      :param invoice: The invoice to generate a file for.
      :return: A tuple of (filename, content_type, file_content)

Helper class for reportlab-base renderers
-----------------------------------------

All PDF rendering that ships with eventyay is based on reportlab. We recommend to read the
`reportlab User Guide`_ to understand all the concepts used here.

If you want to implement a renderer that also uses report lab, this helper class might be
convenient to you:


.. class:: eventyay.base.invoice.BaseReportlabInvoiceRenderer

   .. py:attribute:: BaseReportlabInvoiceRenderer.pagesize

   .. py:attribute:: BaseReportlabInvoiceRenderer.left_margin

   .. py:attribute:: BaseReportlabInvoiceRenderer.right_margin

   .. py:attribute:: BaseReportlabInvoiceRenderer.top_margin

   .. py:attribute:: BaseReportlabInvoiceRenderer.bottom_margin

   .. py:attribute:: BaseReportlabInvoiceRenderer.doc_template_class

   .. py:attribute:: BaseReportlabInvoiceRenderer.invoice

   .. py:method:: _init()

      Initialize the renderer.

   .. py:method:: _get_stylesheet()

      Get the reportlab stylesheet.

   .. py:method:: _register_fonts()

      Register custom fonts with reportlab.

   .. py:method:: _on_first_page(canvas, doc)

      Callback for rendering the first page.

   .. py:method:: _on_other_page(canvas, doc)

      Callback for rendering other pages.

   .. py:method:: _get_first_page_frames(doc)

      Get the frames for the first page.

   .. py:method:: _get_other_page_frames(doc)

      Get the frames for other pages.

   .. py:method:: _build_doc(fhandle, story)

      Build the document.

.. _reportlab User Guide: https://www.reportlab.com/docs/reportlab-userguide.pdf