Materialize templates
======================

AlekSIS frontend uses the `MaterializeCSS`_ framework and the `django-material`_ library.

Internationalization
--------------------

Load the ``i18n`` template tag and start translating strings in templates with
the following template tags::

    {% blocktrans %}String{% endblocktrans %}
    {% trans "String" %}

``{% blocktrans %}`` is mostly used for multiple words or multiline, while ``{%
trans %}`` is used for single words.

Title and headlines
-------------------

To add a main headline or browser title to your template, you can add the
following blocks to your template::

    {% block browser_title %}Title{% endblock %}
    {% block page_title %}Headline{% endblock %}

To fully remove page or browser title, use these template tags::

    {% block no_browser_title %}{% endblock %}
    {% block no_page_title %}{% endblock %}


Extended navbar
---------------

The top navbar with the site title and the login status can be extended by an additional tab bar, for example.

To add normal Materialize tabs without icons, you can use a snippet like described in `Extended Navbar with Tabs`_:

.. code-block:: html+django

    {% block nav_content %}
        <ul class="tabs tabs-transparent">
            <li class="tab"><a href="#test1">Test 1</a></li>
            <li class="tab"><a class="active" href="#test2">Test 2</a></li>
            <li class="tab disabled"><a href="#test3">Disabled Tab</a></li>
            <li class="tab"><a href="#test4">Test 4</a></li>
        </ul>
    {% endblock %}

Furthermore, you can use tabs with integrated icons that are higher, but more compact in width:

.. code-block:: html+django

    {% block nav_content %}
        <ul class="tabs tabs-transparent tabs-icons tabs-fixed-width">
            <li class="tab">
                <a href="#test1">
                    <i class="material-icons">speaker_notes</i>
                    Test 1
                </a>
            </li>
            <li class="tab">
                <a href="#test2">
                    <i class="material-icons">people</i>
                    Test 2
                </a>
            </li>
        </ul>
    {% endblock %}


.. warning::

    Don't define the ``nav_content`` block within the ``content`` block – that won't work.

Forms in templates
------------------

The django MaterializeCSS integrations provides support for forms in
template.

You just have to load the ``material_form`` templatetag in the ``{% load %}``
block.

The following snippet generates the form::

    <form method="post" enctype="multipart/form-data">
        {% csrf_token %}
        {% form form=edit_person_form %}{% endform %}
        {% include "core/partials/save_button.html" %}
    </form>

``edit_person_form`` is the variable name of the form in your ``context``.

``{% include "core/partials/save_button.html" %}`` includes a template snippet
from AlekSIS core.  You can modify the buttons icon and translatable caption
like this::

    {% trans "Edit" as caption %}
    {% include "core/partials/save_button.html" with caption=caption, icon="person" %}


In your ``forms.py`` you can configure the layout of the fields like in the EditPersonForm::

    class EditPersonForm(ExtensibleForm):
    """Form to edit an existing person object in the frontend."""

    layout = Layout(
        Fieldset(
            _("Base data"),
            "short_name",
            Row("user", "primary_group"),
            Row("first_name", "additional_name", "last_name"),
        ),
        Fieldset(_("Address"), Row("street", "housenumber"), Row("postal_code", "place")),
        Fieldset(_("Contact data"), "email", Row("phone_number", "mobile_number")),
        Fieldset(
            _("Advanced personal data"), Row("sex", "date_of_birth"), Row("photo"), "guardians",
        ),
    )

Tables in templates
-------------------

To display tables generated by ``django-tables2`` in your template, you have to load the ``render_table`` template tag from ``django_tables2``::

    {% load render_table from django_tables2 %}

After you've loaded the template tag, you can simply generate the table like this::

    {% render_table persons_table %}

``persons_table`` is the variable name of the table in your ``context``.

.. _MaterializeCSS: https://materializecss.com/
.. _django-material: https://pypi.org/project/django-material/
.. _Extended Navbar with Tabs: https://materializecss.com/navbar.html#navbar-tabs