===========================
Custom report template
===========================

:term:`Submission report` html template can be customized by modifying the :class:`~dashboard_widgets.models.Dashboard` object.
A customized template can override the default template's HTML, and use built-in template tags.

.. seealso::
    `Django Template language reference <https://docs.djangoproject.com/en/3.2/ref/templates/language/>`_
    contains detailed documentation with examples how to write django templates.


Example
=========

.. code-block:: html+django

    <div class="report_link">
        {% load megforms_extras %}
        <div class="non-responsive-container">
            <h2>Custom Public Report: {{ current_form.name }}</h2>
            This is a report using a custom template

            <h3>by: {{ auditors.first|capfirst }}</h3>
            <h3>Time: {{ start_time }} to {{ end_time }}</h3>
            <h3>Group: {{ institution.group }}</h3>
            <h3>Institution: {{ institution }}</h3>
            <h3>wards: {{ wards.as_string }}</h3>
            <h3>Observations:</h3>

            <ul>
                {% for obs in observations %}
                <li>{{ obs }}</li>
                {% endfor %}
            </ul>
            <h3>Answer Comments: {% answer_comments observations.0 "field_name" %}</h3>
            {% include "print_controls.html" %}
            {{ widgets }}
        </div>
    </div>

Variables
==========
Variables can be rendered in the report by using Django's variable syntax: ``{{ variable-name }}``.

You can further use the variables to:

* Access their properties/members (e.g. ``{{ institution.name }}``)
* Call instance methods that don't require any arguments (e.g. ``{{ audit_form.get_config }}``)
* Pass the variable into a filter (e.g. ``{{ start_date|date }}``)
* Combine all of the above  (e.g. ``{{ audit_form.get_config.enable_qip|yesno }}``).

    This example accesses :term:`form config` object to check if :term:`QIP` is enabled and uses
    `yesno <https://docs.djangoproject.com/en/3.2/ref/templates/builtins/#yesno>`_ template filter to render the value as "yes" if enabled.

The following variables are available in submission report:

``{{ widgets }}``
    Contains all the widgets.

``{{ start_time }}``, ``{{ end_time }}``
    Start/End time of the audit session. You can use template filter to display only date. For example ``{{ end_time|date }}``

``{{ auditors }}``
    List of :term:`users <auditor>` involved in the audit. Typically it will be only one user,
    but if report is generated for multiple submissions, it may contain multiple different auditors.
    Because the type of this value is a :class:`QuerySet`, you can call a queryset method to render auditors
    as a comma-separated list: ``{{ auditors.as_string }}``.

``{{ institution }}``
    :term:`Institution` where this audit is submitted to (based on :term:`ward`).
    This value stores only one (first) institution, even if there are multiple institutions related to the submission.

``{{ institutions }}``
    Institutions where this audit is submitted to (based on :term:`ward`). This value can store multiple institutions.

``{{ wards }}``
    One or multiple :term:`wards <ward>` the :term:`observations<observation>` were submitted to.

``{{ observations }}``
    The :term:`observations<observation>` within the submission. You can iterate the observations to render details of each one:

    .. code-block:: html+django

        <ul>
            {% for obs in observations %}
            <li>Ward: {{ obs.ward.name }}</li>
            <li>User: {{ obs.auditor }}</li>
            <li>Form: {{ obs.audit_form }}</li>
            <li>Answers: {{ obs.custom_answers }}</li>
            <li>Comments: {{ obs.generic_comments|join:", " }}</li>
            {% endfor %}
        </ul>

    If the :term:`observations<observation>` have :term:`sub-forms <subform>` they can be used via accessors on the :term:`observation<observation>` object as such:

    .. code-block:: html+django
        :caption: Example when used on a form with "other" and "numbers" subforms with bool and number field each

        <ul>
            {% for obs in observations %}
            <li>Ward: {{ obs.ward.name }}</li>
            <li>User: {{ obs.auditor }}</li>
            <li>Form: {{ obs.audit_form }}</li>
            <li>Subform bool field value: {{ obs.subform_other_observations.0.custom_answers.bool }}</li>
            <li>Subform numbers field value: {{ obs.subform_numbers_observations.0.custom_answers.number }}</li>
            <li>Comments: {{ obs.generic_comments|join:", " }}</li>
            {% endfor %}
        </ul>


``{{ single_observation }}``
    If submission consists of just one :term:`observation`, this value will store the observation.
    If there's more than one observation, the value will be empty.

``{{ current_form }}``
    The :term:`form`. Represents :class:`~megforms.models.AuditForm` instance.

Template tags
==============

You can use any template tags from Django, or custom tags implemented by the project.
Some tags need to be imported at the top of the template (e.g. ``{% load template-library %}``).

.. important::
    Internationalization tags will not work in custom templates if the string is not already a part of project's string library.
    Use of ``{% translate %}`` and ``{% blocktranslate %}`` tags is therefore discouraged.

.. seealso::
    `Django built-in template tags <https://docs.djangoproject.com/en/3.2/ref/templates/builtins/>`_

    If you're running project in development mode, you can view exhaustive list of available template tags:
    :url:`/meg-admin/doc/tags/`