iommi
=====


iommi
=====
.. raw:: html

    <p class="mobile-logo" align="center"><a href="#"><img class="logo" src="https://raw.githubusercontent.com/iommirocks/iommi/master/logo_with_outline.svg" alt="iommi" style="max-width: 200px" width=300></a></p>

    <h3 class="pun">Your first pick for a django power chord</h3>

.. image:: https://img.shields.io/badge/Code_on-GitHub-black
    :target: https://github.com/iommirocks/iommi

.. image:: https://img.shields.io/discord/773470009795018763?logo=discord&logoColor=fff?label=Discord&color=7389d8
    :target: https://discord.gg/ZyYRYhf7Pd

.. image:: https://github.com/iommirocks/iommi/workflows/tests/badge.svg
    :target: https://github.com/iommirocks/iommi/actions?query=workflow%3Atests+branch%3Amaster

.. image:: https://codecov.io/gh/iommirocks/iommi/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/iommirocks/iommi

.. image:: https://readthedocs.org/projects/iommi/badge/?version=latest
    :target: https://docs.iommi.rocks
    :alt: Documentation Status

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

iommi is a toolkit to build web apps faster. It's built on Django but goes a lot further.

It has:

- :doc:`forms <forms>`: that feel familiar, but can handle growing complexity better than Django's forms
- :doc:`tables <tables>`: that are powerful out of the box and scale up to arbitrary complexity
- a system to :doc:`compose parts <pages>`:, like forms, menus, and tables, into bigger pages
- tools that will speed up your development like live edit, jump to code, great feedback for missing select/prefetch related, a profiler, and more.
- great error messages when you make a mistake

.. image:: https://docs.iommi.rocks/README-demo.gif


Example:

.. code-block:: python

    class IndexPage(Page):
        title = html.h1('Supernaut')
        welcome_text = 'This is a discography of the best acts in music!'

        artists = Table(auto__model=Artist, page_size=5)
        albums = Table(
            auto__model=Album,
            page_size=5,
        )
        tracks = Table(auto__model=Album, page_size=5)


    urlpatterns = [
        path('', IndexPage().as_view()),
    ]

This creates a page with three separate tables, a header and some text:

.. image:: https://docs.iommi.rocks/README-screenshot.png

For more examples, see the `examples project <https://github.com/iommirocks/iommi/tree/master/examples/examples>`_.


Getting started
---------------

See :doc:`getting started <getting_started>`.


Running tests
-------------

.. code-block::

    make test
    make test-docs


License
-------

BSD


    :start-line: 4




Finding your way around
=======================

These docs are split by what you need right now:

- **Tutorials** are lessons to work through when you're new. Start here.
- **How-to guides** answer "how do I ...?" when you have a job to do.
- **Reference** is the dry description of every knob iommi has.
- **Explanation** covers the thinking behind iommi, so your code comes out idiomatic.


.. toctree::
   :maxdepth: 2
   :caption: Tutorials

   getting_started
   tutorial

.. toctree::
   :maxdepth: 2
   :caption: How-to guides

   cookbook

.. toctree::
   :maxdepth: 2
   :caption: Reference

   api
   common_config
   views
   dev_tools

.. toctree::
   :maxdepth: 2
   :caption: Explanation

   components
   understanding

.. toctree::
   :maxdepth: 1
   :caption: About the project

   imports
   history
   authors
   contributing

   @github <https://github.com/iommirocks/iommi>
   @discord <https://discord.gg/ZyYRYhf7Pd>
   @pypi <https://pypi.org/project/iommi/>




Indices and tables
==================

* :ref:`genindex`
* :ref:`search`




.. _getting-started:

Getting started
===============

.. note::

    This guide is intended for a reader that is well versed in the Django basics of the ORM,
    urls routing, function based views, and templates.

1. Install
----------

First:

`pip install iommi`.

Add `iommi` to installed apps:

.. code-block:: python

    INSTALLED_APPS = [
        # [...]
        'iommi',
    ]

Add iommi's middleware:

.. code-block:: python

    MIDDLEWARE = [
        # These three are optional, but highly recommended!
        'iommi.live_edit.Middleware',

        # [... Django middleware ...]

        'iommi.sql_trace.Middleware',
        'iommi.profiling.Middleware',

        # [... your other middleware ...]

        'iommi.middleware',
    ]

.. note::

    The iommi middleware must be the last middleware in the list!

By default iommi uses a very basic bootstrap base template. We'll get to how to integrate it into your site later.

2. Your first form
------------------

From this point this guide is aimed at users trying iommi in an existing project. :doc:`The tutorial <tutorial>` is a more in-depth guide to building a full application with iommi from scratch.

Pick a model from your app, and let's build a create form for it! I'm using `Album` here, but you should replace it with your own model. Add this to your `urls.py`:

.. code-block:: python

    from iommi import Form

    # Import any models you need from your models.  Here I'm using Album
    from .models import Album

    urlpatterns = [
        # ...your urls...
        path('iommi-form-test/', Form.create(auto__model=Album).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0e39b00e-a111-4ce3-8b01-eba7d785161d', this)">▼ Hide result</div>
    <iframe id="0e39b00e-a111-4ce3-8b01-eba7d785161d" src="doc_includes/getting_started/test_2__your_first_form.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

3. Your first table
-------------------

Pick a model from your app, and let's build a table for it! Add this to your `urls.py`:

.. code-block:: python

    from iommi import Table

    # Import any models you need from your models.  Here I'm using Album
    from .models import Album

    urlpatterns = [
        # ...your urls...
        path('iommi-table-test/', Table(auto__model=Album).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('879ff937-ba73-421b-8580-45b52dd1f037', this)">▼ Hide result</div>
    <iframe id="879ff937-ba73-421b-8580-45b52dd1f037" src="doc_includes/getting_started/test_3__your_first_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If you want, add a filter for some column:

.. code-block:: python

    urlpatterns = [
        # ...your urls...
        path('iommi-table-test/', Table(
            auto__model=Album,
            columns__name__filter__include=True,  # <--- replace `name` with some field from your model
        ).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a2bea8c5-95b6-4c34-b8be-c7b918af09a5', this)">▼ Hide result</div>
    <iframe id="a2bea8c5-95b6-4c34-b8be-c7b918af09a5" src="doc_includes/getting_started/test_3__your_first_table1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

4. Your first page
------------------

Pages are the method to compose complex pages from parts. Add this to your `views.py`:

.. code-block:: python

    from iommi import Page, Form, Table

    # Import any models you need from your models.  Here I'm using Artist
    from .models import Artist

    class TestPage(Page):
        create_form = Form.create(auto__model=Artist)
        a_table = Table(auto__model=Artist)

        class Meta:
            title = 'An iommi page!'

then hook into `urls.py`:

.. code-block:: python

    urlpatterns = [
        # ...your urls...
        path(
            'iommi-page-test/',
            TestPage().as_view()
        ),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2ebf9279-0036-4c45-a6e4-2fb50ed9150f', this)">▼ Hide result</div>
    <iframe id="2ebf9279-0036-4c45-a6e4-2fb50ed9150f" src="doc_includes/getting_started/test_4__your_first_page.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

5. A simple function based view
-------------------------------

It's often useful to have a function based view around your iommi code to do
some basic setup. So we'll add an example for that too. With iommi's
middleware you can return iommi objects from your view:


`views.py`:

.. code-block:: python

    def iommi_view(request, name):
        return TestPage(title=f'Hello {name}')

`urls.py`:

.. code-block:: python

    urlpatterns = [
        # ...your urls...
        path(
            'iommi-view-test/<name>/',
            iommi_view
        ),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d739f6b5-5e9c-46ff-9a15-c12964a1e46a', this)">▼ Hide result</div>
    <iframe id="d739f6b5-5e9c-46ff-9a15-c12964a1e46a" src="doc_includes/getting_started/test_5__a_simple_function_based_view.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

6. Make iommi pages fit into your projects design
-------------------------------------------------

So far all the views we've created are rendered in plain bootstrap. Let's fit
the iommi views you've already added into the design of your project.

The simplest is to add something like this to your `settings.py`:

.. code-block:: python

    # These imports need to be at the bottom of the file!
    from iommi import Style, Asset
    from iommi.style_bootstrap import bootstrap

    IOMMI_DEFAULT_STYLE = Style(
        bootstrap,
        base_template='my_project/iommi_base.html',
        root__assets=dict(
            my_project_custom_css=Asset.css(attrs__href='/static/custom.css'),
            my_project_custom_js=Asset.js(attrs__src='/static/custom.js'),
        ),
    )

Where `my_project/iommi_base.html` could look something like this:

.. code-block:: html

    {% extends "iommi/base.html" %}

    {% block iommi_top %}
        {% include "my_menu.html" %}
    {% endblock %}

    {% block iommi_bottom %}
        {% include "my_footer.html" %}
    {% endblock %}


After you've set up your base style successfully, all the test pages you made
before (form, table, page, view) are now using your style.



Tutorial
========

.. note::

    This tutorial is intended for a reader that is well versed in the Django basics of the ORM,
    urls routing, function based views, and templates.

    It is also expected that you have already installed iommi in your project. Read section 1 of :ref:`Getting started <getting-started>`.


In this tutorial you will build a discography app. By the end you will have:

- an index page with album artwork
- an artist page, and a page listing artists
- an album page, and a page listing albums
- a tracks page
- the iommi admin, enabled for all of these

Every step shows the code and the page it produces. Type the code in as you go;
each step builds on the one before it.


Set up
------

Put these models in your app's `models.py`:

.. literalinclude:: models.py
    :pyobject: Genre
    :end-before: def __str__

.. literalinclude:: models.py
    :pyobject: Artist
    :end-before: def __str__

.. literalinclude:: models.py
    :pyobject: Album
    :end-before: def __str__

.. literalinclude:: models.py
    :pyobject: Track
    :end-before: def __str__

Create the tables:

.. code-block:: shell

    python manage.py makemigrations
    python manage.py migrate

Now load the same example data used in this tutorial, so your pages look like the
screenshots. Download `big_discography.py`_ into your project and run it:

.. code-block:: shell

    python manage.py shell < big_discography.py

.. _big_discography.py: https://raw.githubusercontent.com/iommirocks/iommi/master/docs/custom/big_discography.py

You're ready to build the first page.



.. code-block:: python

    # Regenerates the example data script that the `Set up` section of this page
    # links to. Nothing is rendered into the docs from here.

Tables
------

Creating a table view of a model in iommi is simple:

.. code-block:: python

    urlpatterns = [
        path('', Table(auto__model=Album).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e7b46a2a-262d-4838-850a-8b3935b4fbd3', this)">▼ Hide result</div>
    <iframe id="e7b46a2a-262d-4838-850a-8b3935b4fbd3" src="doc_includes/tutorial/test_declarative_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You get sorting and pagination by default, and we're using the default bootstrap 5 style. iommi ships with :ref:`more styles <style>` that you can switch to, or you can :ref:`implement your own custom style <style>`.

At this point you might think "Hold on! Where is the template?". There isn't one. We don't need a template. iommi works at a higher level of abstraction. Don't worry, you can drop down to templates if you need to. There are examples of this in the :ref:`table cookbook <cookbook-tables>`, and much more. One of the most important concepts is to include or exclude columns using includes: `auto__include=['name', 'artist']`, or using excludes: `auto__exclude=['artist', 'year']`.

Pages
-----

So far we’ve just created a single table, but often you want something a little more complex, especially for your index page. iommi has a concept of a :ref:`Page <pages>` that is used to build up a bigger page from smaller building blocks. Let’s build out our simple web app to have separate pages for albums, artists and tracks:

.. code-block:: python

    urlpatterns = [
        path('albums/', Table(auto__model=Album).as_view()),
        path('artists/', Table(auto__model=Artist).as_view()),
        path('tracks/', Table(auto__model=Track).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c9a531a1-4296-4344-b8dd-42bd1dddddaf', this)">► Show result</div>
    <iframe id="c9a531a1-4296-4344-b8dd-42bd1dddddaf" src="doc_includes/tutorial/test_pages.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('09b73d87-bc5b-4832-be81-81df8272db0b', this)">► Show result</div>
    <iframe id="09b73d87-bc5b-4832-be81-81df8272db0b" src="doc_includes/tutorial/test_pages1.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('93f7db50-98d1-4618-8aa4-0650969cebe8', this)">► Show result</div>
    <iframe id="93f7db50-98d1-4618-8aa4-0650969cebe8" src="doc_includes/tutorial/test_pages2.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

and an index page with three tables, a header and some text:

.. code-block:: python

    class IndexPage(Page):
        title = html.h1('Supernaut')
        welcome_text = 'This is a discography of the best acts in music!'

        artists = Table(auto__model=Artist, page_size=5)
        albums = Table(auto__model=Album, page_size=5)
        tracks = Table(auto__model=Track, page_size=5)

    urlpatterns = [
        path('', IndexPage().as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5932a9ad-4370-4a28-a892-515cae2c7e2a', this)">▼ Hide result</div>
    <iframe id="5932a9ad-4370-4a28-a892-515cae2c7e2a" src="doc_includes/tutorial/test_pages3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`html` is a little fragment builder to make it easier and faster to build small html parts. `html.div('foo')` is just a more convenient way to write `Fragment(tag='div', children__text='foo')`. Fragments are used internally throughout iommi, because they allow you to define a small bit of html that can be customized later. Let’s look at an example:

.. code-block:: pycon

    >>> class MyPage(Page):
    ...    title = html.h1('Supernaut')

    >>> MyPage().bind().__html__()
    '<h1>Supernaut</h1>'

    >>> MyPage(parts__title__attrs__class__foo=True).bind().__html__()
    '<h1 class="foo">Supernaut</h1>'

This is used throughout iommi to provide good defaults that can be customized easily when needed.

A `Page` can contain any `Part` (like `Fragment`, `Table`, `Form`, `Menu`, etc), plain strings or Django `Template` objects even. Escaping is handled like you’d expect from Django where strings are escaped, and you can use `format_html`/`mark_safe` to send your raw html straight through.

Path decoding
-------------

We’ll also introduce a page for an individual artist. We will use iommi's :doc:`path` here.

First we register the path component we want to decode (in your `AppConfig` `ready`):

.. code-block:: python

    register_path_decoding(
        artist_name=Artist.name,
    )

Then we define our page. Notice the lambdas we use to dynamically get the parameters to retrieve the correct data.

.. code-block:: python

    class ArtistPage(Page):
        title = html.h1(lambda artist, **_: artist.name)

        albums = Table(
            auto__model=Album,
            rows=lambda artist, **_: Album.objects.filter(artist=artist),
        )
        tracks = Table(
            auto__model=Track,
            rows=lambda artist, **_: Track.objects.filter(album__artist=artist),
        )

    urlpatterns = [
        path('artist/<artist_name>/', ArtistPage().as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('3992414c-0de1-47bd-888a-98f4da00a78d', this)">▼ Hide result</div>
    <iframe id="3992414c-0de1-47bd-888a-98f4da00a78d" src="doc_includes/tutorial/test_path_decoding.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Path decoders in iommi can be more convenient compared to Django path
decoders, as instead of writing `<artist:artist>` everywhere, you can instead
write `<artist_name>` or `<artist_pk>`. They are also easier to set up and 
give you hook points for access control if needed.

Customize the table
-------------------

Change how a value is displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Add `get_absolute_url` to your `Album` and `Artist` models, then let's make the
album name link to the album page. `cell__url` turns a cell into a link:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__cell__url=lambda row, **_: row.get_absolute_url(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('27803a36-eeec-4ad6-9eac-64910cfcc6e8', this)">▼ Hide result</div>
    <iframe id="27803a36-eeec-4ad6-9eac-64910cfcc6e8" src="doc_includes/tutorial/test_table_customization.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Notice that the *artist* column became a link too, without you asking for it:
for a `ForeignKey` column iommi does this by default when the target model has
`get_absolute_url`.

`columns__name__cell__url` reads as `columns.name.cell.url`. iommi uses `__` to
step down into nested configuration, because `.` isn't valid in a keyword
argument. You'll see this everywhere from here on;
:ref:`dunder-dict-equivalence` explains it properly.

When you need to build the displayed string yourself rather than just link it,
use `cell__format`:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__artist__cell__format=lambda value, **_:
            format_html('<a href="/artist/{}/">{}</a>', value, value)
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('396899cf-5e1c-4e52-a057-c32c52826ac3', this)">▼ Hide result</div>
    <iframe id="396899cf-5e1c-4e52-a057-c32c52826ac3" src="doc_includes/tutorial/test_table_customization1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There is a ladder of hooks here, and you reach for the lowest one that does the
job: `attr` picks which attribute is read, `value` computes the value, `format`
turns the value into a string, and `template` replaces the cell's rendering
outright, `td` tag included. Rows have a `template` too.

Add filtering
~~~~~~~~~~~~~

Tables also have built in filtering. To enable a filter make sure `include` is `True` for the `filter` of a column.

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__filter__include=True,
        columns__year__filter__include=True,
        columns__year__filter__field__include=False,
        columns__artist__filter__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7a853b03-5518-4732-936a-19b908f1005a', this)">▼ Hide result</div>
    <iframe id="7a853b03-5518-4732-936a-19b908f1005a" src="doc_includes/tutorial/test_table_customization2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`columns__year__filter__field__include=False` means we turn off the `Field` in
the form that is created, but we can still search for the year in the
advanced search language. 

To handle selecting from a choice field that is backed by a `QuerySet` that
can contain thousands or millions of rows, iommi by default uses a select2
filter control with an automatic ajax endpoint. The automatic endpoint is handled by iommi on the
same url as the view. An advantage to this approach is that we only need
to be sure our view has the correct permission checks and then we also know
the select box (or ajax endpoint) has the same checks. This makes it easy to
reason about the security of the product. 

The advanced filter means users can write queries like `year>1960 and title:war`
to find albums published after 1960 and that contain the word "war".

Add buttons, and edit/delete links for staff
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An `Action` in iommi is a link or a button. Let's add a create button, plus edit
and delete columns, and show all three only to staff. `Column.edit` and
`Column.delete` are prebuilt shortcuts for the link columns:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        actions__create_album=Action(
            attrs__href='/albums/create/',
            include=lambda request, **_: request.user.is_staff,
        ),
        columns__edit=Column.edit(
            after=0,
            include=lambda request, **_: request.user.is_staff,
        ),
        columns__delete=Column.delete(
            include=lambda request, **_: request.user.is_staff,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('736dfb52-89bd-4fe4-bbd1-54e06b22c349', this)">▼ Hide result</div>
    <iframe id="736dfb52-89bd-4fe4-bbd1-54e06b22c349" src="doc_includes/tutorial/test__foo.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

For non-staff the "Create album" button isn't shown, neither are the edit and delete columns:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('6475d452-f345-418f-8fe5-943873d3d9e8', this)">▼ Hide result</div>
    <iframe id="6475d452-f345-418f-8fe5-943873d3d9e8" src="doc_includes/tutorial/test__foo1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Show album art in a column
~~~~~~~~~~~~~~~~~~~~~~~~~~

Now that we have a basic app, let's make the index page look better. A plain
table of text doesn't look very cool, so we'll add the album covers.

Add a column that has no model field behind it (`attr=None`) and give it a
template that renders an image:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__album_art=Column(
            attr=None,
            cell__template=Template('''
                <td>
                    <img 
                        height="30"
                        src="../../album_art/{{ row.artist }}/{{ row.name }}.jpg">
                </td>
            '''),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7b597094-93b8-49f3-ba6b-434737e24c01', this)">▼ Hide result</div>
    <iframe id="7b597094-93b8-49f3-ba6b-434737e24c01" src="doc_includes/tutorial/test__foo2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

That's a start, but we want something more showy, so let's get rid of the html
table entirely.

Turn the rows into cards
~~~~~~~~~~~~~~~~~~~~~~~~

`row__template` replaces the rendering of a whole row, `tr` tag included. Render
the table as a `div` instead of a `table`, turn off the header, and make each row
a card:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        tag='div',
        header__template=None,
        row__template=Template("""
            <div class="card" style="width: 15rem; display: inline-block;" {{ cells.attrs }}>
                <img class="card-img-top" src="../../album_art/{{ row.artist }}/{{ row.name|urlencode }}.jpg">
                <div class="card-body text-center">
                    <h5>{{ cells.name }}</h5>
                    <p class="card-text">
                        {{ cells.artist }}
                    </p>
                </div>
            </div>
        """),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5fb75b76-90e4-4918-815d-800f0e30196a', this)">▼ Hide result</div>
    <iframe id="5fb75b76-90e4-4918-815d-800f0e30196a" src="doc_includes/tutorial/test__foo3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You can specify the name of a template file here instead of writing the
template inline like this. This way is nicer for small things and quick prototypes though.


Admin
-----

With these high level abstractions we've seen so far (pages, tables, queries, 
forms, fragments) we can easily build more powerful components. Which is what
we've done with the administration interface built into iommi. Installing it
is as simple as:

.. code-block:: python

    class MyAdmin(Admin):
        class Meta:
            pass

.. code-block:: python

    urlpatterns = [
        path('iommi-admin/', include(MyAdmin.urls())),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d9a4ee83-bf6a-43cc-912a-25e0b076f0a0', this)">▼ Hide result</div>
    <iframe id="d9a4ee83-bf6a-43cc-912a-25e0b076f0a0" src="doc_includes/tutorial/test__foo4.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Customization is easy with `IOMMI_DEBUG` on (default on if `DEBUG` is on), 
here's how to use the pick tool:

.. raw:: html

    <video controls style="max-width: 100%"><source src="iommi-admin-customization.mp4"></video>

You can override an entire field rendering with `template`, the template 
of the label with `label__template`, the name of a field with `display_name`,
add a CSS class to the label tag with `label__attrs__class__foo=True`, and 
much more. Customization is at all levels, and in all these cases you can
supply a callable for even more flexibility.

Forms
-----

iommi also comes with a library for forms. This can look very much like the
forms library built into Django, but is different in some crucial ways. Let's
take a simple example of a `ModelForm`:

.. code-block:: python

    from django import forms

    class AlbumForm(forms.ModelForm):
        class Meta:
            model = Album
            fields = ['name', 'artist']

.. code-block:: html

    {% extends "base.html" %}
    {% block content %}

    <form action="/your-name/" method="post">
        {% csrf_token %}
        {{ form }}
        <input type="submit" value="Submit">
    </form>

    {% endblock %}

In iommi the same can be written as:

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'artist']

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f130bdd6-b0ca-4e83-9665-766aebbe6456', this)">▼ Hide result</div>
    <iframe id="f130bdd6-b0ca-4e83-9665-766aebbe6456" src="doc_includes/tutorial/test_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

No template needed, and this is the view too with `Form.edit` or `Form.create`.

In iommi you always get a form encoding specified on the form, so they all work
with file uploads. Missing form encoding on the form tag is a very common 
stumbling block for beginners. You also get a submit action by default which
you can configure via `actions__submit`:

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'artist']
            actions__submit__display_name = 'Save'

Everything you put in `class Meta` is passed to the constructor, and only valid
constructor arguments are accepted there -- so a misspelled setting is an error,
not silence. :doc:`equivalency` covers what that buys you.

There are many more customization options available, you can find more
in the :ref:`form cookbook <cookbook-forms>` and the docs for `Field`.


Automatic views
~~~~~~~~~~~~~~~

iommi goes a step further than Django forms, by supplying full views that can
be used from either a declarative form or an auto generated form. An example
is to have a create view for an `Artist`:

.. code-block:: python

    urlpatterns = [
        path('create/', Form.create(auto__model=Artist).as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9cf91939-b29c-4f10-bcbf-05a662b4ec5d', this)">▼ Hide result</div>
    <iframe id="9cf91939-b29c-4f10-bcbf-05a662b4ec5d" src="doc_includes/tutorial/test_forms1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There are four built in forms/views like this: `create`, `edit`, `create_and_edit` and `delete`.
The `delete` view is a read only form with some styling for the submit button
and a submit handler that deletes the object. We find this to be really nice as
a confirmation page because you can see what you are about to delete.

Wrap up
-------

I'm glad you read this far! This has been a very shallow introduction, but
it has touched on all the major parts in some way, and there is a lot of
material to cover. We hope you want to give iommi a try.



Cookbook
=============

Recipes for getting a specific job done. Each entry is a question you might
have, and the shortest answer that works.

If you are new to iommi, work through :doc:`getting_started` and the
:doc:`tutorial` first: these recipes assume you already have iommi running.

Per component
-------------

.. toctree::
   :maxdepth: 2

   cookbook_general
   cookbook_parts_pages
   cookbook_forms
   cookbook_tables
   cookbook_edit_tables
   cookbook_queries
   cookbook_main_menu
   cookbook_calendar

Fitting iommi into your project
-------------------------------

.. toctree::
   :maxdepth: 2

   styles
   path
   access_control
   admin
   testing
   production_use
   legacy_fbv
   cookbook_porting




General
-------

How do I find the path to a parameter?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Navigating the namespaces can sometimes feel a bit daunting. To help with
this iommi has a special debug mode that can help a lot. By default it's
set to settings.DEBUG, but to set it explicitly put this in your settings:

.. code-block:: python

    IOMMI_DEBUG = True

Now iommi will output `data-iommi-path` attributes in the HTML that will
help you find the path to stuff to configure. E.g. in the kitchen
sink table example a cell looks like this:

.. code-block:: html

    <td data-iommi-path="columns__e__cell">explicit value</td>

To customize this cell you can pass for example
`columns__e__cell__format=lambda value, **_: value.upper()`. 

Instead of looking at the DOM, you can use the "pick" tool where you can get
the path by clicking on the item you want. You will also get a link to the 
right place into the API docs for the thing you clicked on. 

Another nice way to find what is available is to append `?/debug_tree` in the
url of your view. You will get a table of available paths with the ajax
endpoint path, and their types with links to the appropriate documentation.

If `IOMMI_DEBUG` is on you will also get the iommi debug toolbar on your pages.
`Code` will jump to the code for the current view
in PyCharm. You can configure the URL builder to make it open your favored
editor by setting `IOMMI_DEBUG_URL_BUILDER` in settings:

.. code-block:: python

    IOMMI_DEBUG_URL_BUILDER = lambda filename, lineno: f'my_editor://{filename}:{lineno}'

Visual Studio Code example:

.. code-block:: python

    IOMMI_DEBUG_URL_BUILDER = lambda filename, lineno: f"vscode://file/{filename}:{lineno}:0"

The `Tree` link will open the `?/debug_tree` page mentioned above.

How do I access a sibling component?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let's say we have a `Page` with a form and a custom template, and we want
to access the form, we can do that via the `root` object:

.. code-block:: python

    class MyPage(Page):
        edit_album = Form.edit(auto__model=Album, instance=album)
        view_album = Template('''
            {{ root.parts.edit_album.fields.name.value }}
        ''')

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('cb5564bc-7525-4116-bbf9-8484b0ea6adb', this)">▼ Hide result</div>
    <iframe id="cb5564bc-7525-4116-bbf9-8484b0ea6adb" src="doc_includes/cookbook_general/test_access_other_component.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-member-class:

How do I use a custom class for the columns/fields/filters of a component?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.member_class
.. uses EditTable.member_class
.. uses Form.member_class
.. uses Query.member_class
.. uses Page.member_class
.. uses Table.form_class
.. uses EditTable.form_class
.. uses Query.form_class
.. uses Table.query_class
.. uses EditTable.query_class

A `Table` creates `Column` instances, a `Form` creates `Field` instances and a
`Query` creates `Filter` instances. If you have a custom subclass that you want
iommi to use instead when it auto-generates members from a model, set
`member_class`:

.. code-block:: python

    class MyColumn(Column):
        pass

    class MyTable(Table):
        class Meta:
            member_class = MyColumn

    table = MyTable(auto__model=Album)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0e709a97-8ce0-4b10-97f1-6ca13b380cac', this)">▼ Hide result</div>
    <iframe id="0e709a97-8ce0-4b10-97f1-6ca13b380cac" src="doc_includes/cookbook_general/test_how_do_i_use_a_custom_class_for_the_members_of_a_component.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

A `Table` also has a nested `Form` (used for bulk editing and create) and a nested
`Query` (used for filtering). Swap those out with `form_class` and `query_class`, and
the `Form` that a `Query` builds for its filters with `form_class`:

.. code-block:: python

    class MyField(Field):
        pass

    class MyForm(Form):
        class Meta:
            member_class = MyField

    class MyFilter(Filter):
        pass

    class MyQuery(Query):
        class Meta:
            member_class = MyFilter
            form_class = MyForm

    class MyTable2(Table):
        class Meta:
            member_class = MyColumn
            form_class = MyForm
            query_class = MyQuery

.. uses Form.action_class
.. uses Form.page_class

The same pattern applies to the other parts a component builds. A `Form` uses
`action_class` for its actions and `page_class` for when it is rendered as a
standalone page:

.. code-block:: python

    class MyAction(Action):
        pass

    class MyForm2(Form):
        class Meta:
            action_class = MyAction





Parts & Pages
-------------

.. _override-part-of-page:

How do I override part of a part/page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Page.parts
.. uses Fragment.children
.. Attrs

This is all just *standard* iommi declarative magic, but as you are likely new to it
this might take a while to get used to. Let's say you created yourself a master template
for your site.

.. code-block:: python

    class BasePage(Page):
        title = html.h1('My awesome webpage')
        subtitle = html.h2('It rocks')

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c32b66ec-259a-45d0-b563-b26f1d7a8e39', this)">▼ Hide result</div>
    <iframe id="c32b66ec-259a-45d0-b563-b26f1d7a8e39" src="doc_includes/cookbook_parts_pages/test_how_do_i_override_part_of_a_part_page.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Which you can use like this:

.. code-block:: python

    class IndexPage(BasePage):
        body = 'body'

    index = IndexPage(parts__subtitle__children__child='Still rocking...').as_view()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8060fc91-ebf2-4eec-ab53-c6b3278cc9b0', this)">▼ Hide result</div>
    <iframe id="8060fc91-ebf2-4eec-ab53-c6b3278cc9b0" src="doc_includes/cookbook_parts_pages/test_how_do_i_override_part_of_a_part_page1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

or as a function based view:

.. code-block:: python

    def index(request):
        return IndexPage(parts__subtitle__children__child='Still rocking...')

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('43042cbd-da65-46a8-b7a3-a9aa41d9b292', this)">► Show result</div>
    <iframe id="43042cbd-da65-46a8-b7a3-a9aa41d9b292" src="doc_includes/cookbook_parts_pages/test_how_do_i_override_part_of_a_part_page2.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Here you can see that `Part` s (`Page` s are themselves `Part` s) form a tree and the direct children are gathered in the `parts` namespace. Here we overwrote a leaf of
an existing namespace, but you can also add new elements or replace bigger
parts (and most of the time it doesn't matter if you use the `class Meta` or the
keyword arguments to init syntax):

.. code-block:: python

    class IndexPage(BasePage):
        title = html.img(
            attrs=dict(
                src='https://docs.iommi.rocks/_static/logo_with_outline.svg',
                alt='iommi logo',
                width='70px',
            ),
        )

    index = IndexPage(parts__subtitle=None)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a2d8abbd-4da0-48de-a3f9-e7ea57feb05c', this)">▼ Hide result</div>
    <iframe id="a2d8abbd-4da0-48de-a3f9-e7ea57feb05c" src="doc_includes/cookbook_parts_pages/test_how_do_i_override_part_of_a_part_page3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

In the above we replaced the title and removed the subtitle element completely. The
latter of which shows one of the gotchas as only `str`, `Part` and the django
template types are gathered into the parts structure when a `Part` class definition
is processed. As `None` is not an instance of those types, you can remove things
by setting their value to `None`.

.. _title-of-page:

How do I set the title of my page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Page.title

The title of a the page is text shown in the browser tab.

.. code-block:: python

    Page(title='The title in the browser')

Note that this is different from:

.. code-block:: python

    class MyPage(Page):
        title = Header('A header element in the dom')

    MyPage()

Which is equivalent to:

.. code-block:: python

    Page(parts__title=Header('A header element in the dom'))

.. _context-of-page:

How do I specify the context used when a Template is rendered?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Page.context

.. code-block:: python

    class MyPage(Page):
        body = Template("""A django template was rendered on {{today}}.""")


    def index(request):
        context = {'today': date.today()}

        return MyPage(context=context)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('dd3d3187-18d9-48a6-8f75-eefe7a22f782', this)">▼ Hide result</div>
    <iframe id="dd3d3187-18d9-48a6-8f75-eefe7a22f782" src="doc_includes/cookbook_parts_pages/test_how_do_i_specify_the_context_used_when_a_template_is_rendered.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You can also insert items in the context via the declaration. This
not only makes the above shorter, but also makes it easy to write abstractions that
can be extended later:

.. code-block:: python

    my_page = Page(
        parts__body=Template("""A django template was rendered on {{today}}."""),
        context__today=lambda **_: date.today(),
    ).as_view()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('befce4e9-e30a-44f7-82ed-1431cc3241ad', this)">▼ Hide result</div>
    <iframe id="befce4e9-e30a-44f7-82ed-1431cc3241ad" src="doc_includes/cookbook_parts_pages/test_how_do_i_specify_the_context_used_when_a_template_is_rendered1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _cookbook-menu:

How do I make a menu?
~~~~~~~~~~~~~~~~~~~~~

.. uses Menu.sub_menu
.. uses Menu.items_container
.. uses Menu.sort
.. uses MenuItem.url
.. uses MenuItem.sub_menu
.. uses MenuItem.regex
.. uses MenuItem.group
.. uses MenuItem.sort
.. uses MenuItem.a
.. uses MenuItem.active_class
.. uses MenuItem.active_class_on_item

A `Menu` is built from `MenuItem` s in its `sub_menu`. Each item's `url` defaults
to ``/<name>/``, and the item whose `regex` matches the current URL gets the
`active_class` (put that class on the item itself instead of its link with
`active_class_on_item`). Nest items by giving a `MenuItem` its own `sub_menu`. By
default items keep their declared order; set `sort=True` to sort them by name. The
``<a>`` tag of an item is configured via `a`, and the element wrapping the whole
list of items via `items_container`:

.. code-block:: python

    menu = Menu(
        sub_menu=dict(
            root=MenuItem(url='/', display_name='Home'),
            albums=MenuItem(),
            artists=MenuItem(
                active_class_on_item=True,
                sub_menu=dict(
                    black_sabbath=MenuItem(),
                    ozzy=MenuItem(),
                ),
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('73e99453-1250-431b-b07f-48a64823a797', this)">▼ Hide result</div>
    <iframe id="73e99453-1250-431b-b07f-48a64823a797" src="doc_includes/cookbook_parts_pages/test_how_do_i_make_a_menu.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-endpoint:

How do I add a custom endpoint?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Endpoint.func
.. uses Endpoint.http_methods

Any `Part` can have custom endpoints under `endpoints`. Give an endpoint a `func`
that returns the response - an `HttpResponse`, a `Part` (which is rendered for
you), or anything JSON-serializable. It answers ``?/<name>``. Allow POST by setting
`http_methods`:

.. code-block:: python

    page = Page(
        parts__h1=html.h1('Hi!'),
        endpoints__echo__func=lambda value, **_: value,
    )

.. _custom-assets:

How do I add CSS or JavaScript assets to a page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Asset.children
.. uses Asset.in_body

Add `Asset` s under `assets` (on any `Part`, or in your `Style`). An `Asset` is a
`Fragment`, so you set its tag and `children` like any other fragment. By default
assets render in the ``<head>``; set `in_body=True` to render them at the end of
the ``<body>`` instead, which is handy for scripts:

.. code-block:: python

    page = Page(
        assets__custom_css=Asset.css(attrs__href='/static/custom.css'),
        assets__custom_script=Asset(
            tag='script',
            children__text='console.log("hi");',
            in_body=True,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0f661e66-13d2-441e-8bec-fc2c0e9ea029', this)">▼ Hide result</div>
    <iframe id="0f661e66-13d2-441e-8bec-fc2c0e9ea029" src="doc_includes/cookbook_parts_pages/test_how_do_i_add_css_or_js_assets.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _fragment-children:

How do I set the content of a fragment-like part?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Action.children
.. uses Header.children
.. uses Container.children

Many parts are `Fragment` s - an HTML tag plus a dict of `children`. `Action`,
`Header` and a table's `container` all work this way, so you build up their
contents through `children`:

.. code-block:: python

    page = Page(
        parts__heading=Header(
            children__text='Albums',
            children__count=html.span(' (2)'),
        ),
        parts__link=Action(
            children__text='Add album',
            children__icon=html.i(attrs__class={'fa': True, 'fa-plus': True}),
            attrs__href='/albums/create/',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ceb2d59c-14d4-429f-a5c9-b2d3ed8ee430', this)">▼ Hide result</div>
    <iframe id="ceb2d59c-14d4-429f-a5c9-b2d3ed8ee430" src="doc_includes/cookbook_parts_pages/test_how_do_i_set_the_content_of_a_fragment.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _action-group:

How do I group actions together?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Action.group

Give actions the same `group` and they are rendered together (for example in a
dropdown):

.. code-block:: python

    form = Form(
        fields__name=Field(),
        actions__save=Action.submit(group='Manage'),
        actions__reset=Action.button(display_name='Reset', group='Manage'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('09cf4beb-50f2-436c-8792-c02bce9b7c2a', this)">▼ Hide result</div>
    <iframe id="09cf4beb-50f2-436c-8792-c02bce9b7c2a" src="doc_includes/cookbook_parts_pages/test_how_do_i_group_actions_together.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





.. _cookbook-forms:

Forms
-----

.. _show-fields:

How do I specify which fields to show?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.include
.. uses FormAutoConfig.model
.. uses FormAutoConfig.include
.. uses FormAutoConfig.exclude
.. uses FormAutoConfig.default_included

Pass `include=False` to hide the field or `include=True` to show it. By default fields are shown, except the primary key field that is by default hidden. You can also pass a callable here like so:

.. code-block:: python

    Form.create(
        auto__model=Album,
        fields__name__include=
            lambda request, **_: request.GET.get('some_parameter') == 'hello!',
    )

This will show the field `name` only if the GET parameter `some_parameter` is set to `hello!`.

To be more precise, `include` turns off the entire field. See :ref:`field-non-editable` and :ref:`field-hidden`

Use `auto__include` to specify the complete list of fields you want:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__include=['name', 'artist'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('37199d44-2abf-46eb-a277-19b1b2c10196', this)">▼ Hide result</div>
    <iframe id="37199d44-2abf-46eb-a277-19b1b2c10196" src="doc_includes/cookbook_forms/test_how_do_i_specify_which_fields_to_show.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Instead of using `auto__include`, you can also use `auto__exclude` to just exclude the fields you don't want:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__exclude=['year'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('64b01f58-b2cf-416e-8e6a-f47381ecefbc', this)">▼ Hide result</div>
    <iframe id="64b01f58-b2cf-416e-8e6a-f47381ecefbc" src="doc_includes/cookbook_forms/test_how_do_i_specify_which_fields_to_show1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There is also a config option `default_included` which is by default `True`, which is where iommi's default behavior of showing all fields comes from. If you set it to `False` fields are now opt-in:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__default_included=False,
        # Turn on only the name field
        fields__name__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9db36f08-5452-4637-b365-72c1b9762525', this)">▼ Hide result</div>
    <iframe id="9db36f08-5452-4637-b365-72c1b9762525" src="doc_includes/cookbook_forms/test_how_do_i_specify_which_fields_to_show2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _supply-custom-parser-field:

How do I supply a custom parser for a field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.parse

Pass a callable to the `parse` member of the field:

.. code-block:: python

    form = Form(
        auto__model=Track,
        fields__index__parse=lambda field, string_value, **_: int(string_value[:-3]),
    )

.. _field-non-editable:

How do I make a field non-editable?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.editable
.. uses Field.parsed_data

There are two cases: A) non-editable and you want to show the value to the
user, or B) non-editable but do not show it ("hardcoded").

A) Show the value
^^^^^^^^^^^^^^^^^

Pass a callable or `bool` to the `editable` member of the field:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__editable=lambda request, **_: request.user.is_staff,
        fields__artist__editable=False,
    )

For a normal user:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8b18eef6-272d-4d6a-b256-724bf8a5f1ef', this)">▼ Hide result</div>
    <iframe id="8b18eef6-272d-4d6a-b256-724bf8a5f1ef" src="doc_includes/cookbook_forms/test_how_do_i_make_a_field_non_editable.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

For a staff user:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ff17cac6-43de-4dff-9f3e-bc4375621bd7', this)">▼ Hide result</div>
    <iframe id="ff17cac6-43de-4dff-9f3e-bc4375621bd7" src="doc_includes/cookbook_forms/test_how_do_i_make_a_field_non_editable1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-hardcoded:

B) Hardcode the value
^^^^^^^^^^^^^^^^^^^^^

A common use case is to navigate to some object, then create a sub-object.
In this example we have a url like `/artists/Black Sabbath/`, where the
artist name is parsed into an `Artist` instance by an iommi path decoder.

Then under that we have `/artists/Black Sabbath/create_album/`, and in this
form, we don't want to make the user choose Black Sabbath again. We
accomplish this with the `hardcoded` shortcut:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        fields__artist=Field.hardcoded(
            parsed_data=lambda params, **_: params.artist,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ae1ee7e4-c55d-4649-8af5-8f0226b8ef43', this)">▼ Hide result</div>
    <iframe id="ae1ee7e4-c55d-4649-8af5-8f0226b8ef43" src="doc_includes/cookbook_forms/test_how_do_i_make_a_field_non_editable2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _form-non-editable:

How do I make an entire form non-editable?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Form.editable
.. uses FormAutoConfig.instance

This is a very common case so there's a special syntax for this: pass a `bool` to the form:

.. code-block:: python

    form = Form.edit(
        auto__instance=album,
        editable=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2ea2371c-69f6-4904-a5b9-cf16621aefdd', this)">▼ Hide result</div>
    <iframe id="2ea2371c-69f6-4904-a5b9-cf16621aefdd" src="doc_includes/cookbook_forms/test_how_do_i_make_an_entire_form_non_editable.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-validator:

How do I supply a custom validator?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.is_valid

Pass a callable that has the arguments `form`, `field`, and `parsed_data`. Return a tuple `(is_valid, 'error message if not valid')`.

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__include=['name'],
        fields__name__is_valid=lambda form, field, parsed_data, **_: (
            parsed_data == 'only this value is valid',
            'invalid!',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('b836404c-cd49-413a-a65b-a16677577fe2', this)">▼ Hide result</div>
    <iframe id="b836404c-cd49-413a-a65b-a16677577fe2" src="doc_includes/cookbook_forms/test_how_do_i_supply_a_custom_validator.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You can also raise `ValidationError`:

.. code-block:: python

    def name_is_valid(parsed_data, **_):
        if parsed_data != 'only this value is valid':
            raise ValidationError('invalid!')
        return True, ''

    form = Form.create(
        auto__model=Album,
        auto__include=['name'],
        fields__name__is_valid=name_is_valid,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9b9a3fb2-61d4-48ed-b5f2-94ec1a62ce0b', this)">▼ Hide result</div>
    <iframe id="9b9a3fb2-61d4-48ed-b5f2-94ec1a62ce0b" src="doc_includes/cookbook_forms/test_how_do_i_supply_a_custom_validator1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _validate-multiple-fields-together:

How do I validate multiple fields together?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.is_valid
.. uses Form.post_validation
.. uses Field.post_validation

Refine the `post_validation` hook on the `form`. It is run after all the individual fields validation
has run, so you can read the parsed `value` of each field and call `form.add_error()` to report a
problem that spans more than one field. Note that it is run even if the individual fields validation
was not successful.

.. code-block:: python

    def post_validation(form, **_):
        if form.fields.password.value != form.fields.password_confirm.value:
            form.add_error('The passwords do not match')

    form = Form(
        fields__password=Field.password(),
        fields__password_confirm=Field.password(display_name='Confirm password'),
        post_validation=post_validation,
        actions__submit__post_handler=lambda form, **_: None,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('59a90e41-d279-4f1a-921a-f4c387c02e9c', this)">▼ Hide result</div>
    <iframe id="59a90e41-d279-4f1a-921a-f4c387c02e9c" src="doc_includes/cookbook_forms/test_how_do_i_validate_multiple_fields_together.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There is a matching `post_validation` hook on each `Field` if you only need to look at a single field
after it has been parsed and validated.

How do I exclude a field?
~~~~~~~~~~~~~~~~~~~~~~~~~

See `How do I say which fields to include when creating a form from a model?`_

.. _include-exclude-fields:

How do I say which fields to include when creating a form from a model?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.auto
.. uses Field.include

`Form()` has four methods to select which fields are included in the final form:

1. the `auto__include` parameter: this is a list of strings for members of the model to use to generate the form.
2. the `auto__exclude` parameter: the inverse of `include`. If you use this the form gets all the fields from the model excluding the ones with names you supply in `exclude`.
3. for more advanced usages you can also pass the `include` parameter to a specific field like `fields__my_field__include=True`. Here you can supply either a `bool` or a callable like `fields__my_field__include=lambda request, **_: request.user.is_staff`.
4. you can also add fields that are not present in the model by passing configuration like `fields__foo__attr='bar__baz'` (this means create a `Field` called `foo` that reads its data from `bar.baz`). You can either pass configuration data like that, or pass an entire `Field` instance.

.. _field-initial-value:

How do I supply a custom initial value?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.initial

Pass a value or callable to the `initial` member:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__initial='Paranoid',
        fields__year__initial=lambda field, form, **_: 1970,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('dfd5e23a-5e81-45ce-862c-f9c10d45676c', this)">▼ Hide result</div>
    <iframe id="dfd5e23a-5e81-45ce-862c-f9c10d45676c" src="doc_includes/cookbook_forms/test_how_do_i_supply_a_custom_initial_value.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If there are `GET` parameters in the request, iommi will use them to fill in the appropriate fields. This is very handy for supplying links with partially filled in forms from just a link on another part of the site.

.. _field-required:

How do I set if a field is required?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.required

Normally this will be handled automatically by looking at the model definition, but sometimes you want a form to be more strict than the model. Pass a `bool` or a callable to the `required` member:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        fields__name__required=True,
        fields__year__required=lambda field, form, **_: True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('30c7bb87-e305-49e5-95c3-092adcbcbfbf', this)">▼ Hide result</div>
    <iframe id="30c7bb87-e305-49e5-95c3-092adcbcbfbf" src="doc_includes/cookbook_forms/test_how_do_i_set_if_a_field_is_required.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

To show the field as required before posting, you can add a CSS class rendering to your style definition:

.. code-block:: python

    IOMMI_DEFAULT_STYLE = Style(
        bootstrap,
        Field__attrs__class__required=lambda field, **_: field.required,
    )

...and this CSS added to your site's custom style sheet:

.. code-block:: css

    .required label:after {
        content: " *";
        color: red;
    }

For the following result:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0c12f3da-1b61-432b-abee-3d3ad9589d71', this)">▼ Hide result</div>
    <iframe id="0c12f3da-1b61-432b-abee-3d3ad9589d71" src="doc_includes/cookbook_forms/test_how_do_i_set_if_a_field_is_required1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

See the style docs for more information on defining a custom style for your project.

.. _field-order:

How do I change the order of the fields?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.after

You can change the order in your model definitions as this is what iommi uses. If that's not practical you can use the `after` member. It's either the name of a field or an index. There is a special value `LAST` to put a field last.

.. code-block:: python

    from iommi import LAST

    form = Form(
        auto__model=Album,
        fields__name__after=LAST,
        fields__year__after='artist',
        fields__artist__after=0,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fcba0bf1-d9a0-4ee1-b787-0a8cf32f318a', this)">▼ Hide result</div>
    <iframe id="fcba0bf1-d9a0-4ee1-b787-0a8cf32f318a" src="doc_includes/cookbook_forms/test_how_do_i_change_the_order_of_the_fields.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

This will make the field order `artist`, `year`, `name`.

If there are multiple fields with the same index or name the order of the fields will be used to disambiguate.

.. _field-search-fields:

How do I specify which model fields the search of a choice_queryset uses?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.search_fields

`Form.choice_queryset` uses the registered search fields for filtering and ordering.
See `Registrations <registrations.html>`_ for how to register one. If present it will default
to a model field `name`.


In special cases you can override which attributes it uses for
searching by specifying `search_fields`:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__search_fields=('name', 'year'),
    )

This last method is discouraged though, because it will mean searching behaves
differently in different parts of your application for the same data.

.. _field-related-multi-select:

How do I make a foreign key field a multi-select?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.related
.. uses Field.multi_choice_queryset

A foreign key uses the `related` shortcut, which renders as a single-value
select. Pass `multi_select=True` to render it as a multi-select
(`multi_choice_queryset`) instead:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__artist__multi_select=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c5dc57a6-5719-4461-b0e8-fc6ac0a130c0', this)">▼ Hide result</div>
    <iframe id="c5dc57a6-5719-4461-b0e8-fc6ac0a130c0" src="doc_includes/cookbook_forms/test_how_do_i_make_a_foreign_key_field_multi_select.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I insert a CSS class or HTML attribute?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See :doc:`Attrs`.

.. _field-template:

How do I override rendering of an entire field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.template

Pass a template name:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__template='my_template.html',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('bebbf65e-7028-4b2e-8735-b688c3cd9476', this)">▼ Hide result</div>
    <iframe id="bebbf65e-7028-4b2e-8735-b688c3cd9476" src="doc_includes/cookbook_forms/test_how_do_i_override_rendering_of_an_entire_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

or a `Template` object:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__template=Template('This is from the inline template'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('166123fd-aef5-474e-a3fd-074d65b10dec', this)">▼ Hide result</div>
    <iframe id="166123fd-aef5-474e-a3fd-074d65b10dec" src="doc_includes/cookbook_forms/test_how_do_i_override_rendering_of_an_entire_field1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-input-template:

How do I override rendering of the input field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.input
.. uses Fragment.template

Pass a template name or a `Template` object to the `input` namespace:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__input__template='my_template.html',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8a6e4a6e-5cf7-4162-90a0-f937fd0de1f0', this)">▼ Hide result</div>
    <iframe id="8a6e4a6e-5cf7-4162-90a0-f937fd0de1f0" src="doc_includes/cookbook_forms/test_how_do_i_override_rendering_of_the_input_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__input__template=Template('This is from the inline template'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a282c9ef-b1cd-41b4-83b3-7565526482ba', this)">▼ Hide result</div>
    <iframe id="a282c9ef-b1cd-41b4-83b3-7565526482ba" src="doc_includes/cookbook_forms/test_how_do_i_override_rendering_of_the_input_field1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _project-wide-field-rendering:

How do I change how fields are rendered everywhere in my project?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Style

Define a custom style and override the appropriate fields. For
example here is how you could change `Field.date` to use a text
based input control (as opposed to the date picker that `input type='date'`
uses).

.. code-block:: python

    my_style = Style(bootstrap, Field__shortcuts__date__input__attrs__type='text')

When you do that you will get English language relative date parsing
(e.g. "yesterday", "3 days ago") for free, because iommi used to use a
text based input control and the parser is applied no matter what
(it's just that when using the default date picker control it will
always only see ISO-8601 dates).

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('458fc9ce-67c2-4d89-9403-6afe647aede9', this)">▼ Hide result</div>
    <iframe id="458fc9ce-67c2-4d89-9403-6afe647aede9" src="doc_includes/cookbook_forms/test_how_do_i_change_how_fields_are_rendered_everywhere_in_my_project.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _form-redirect:

How do I change where the form redirects to after completion?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses FormAutoConfig.instance
.. uses Form.extra

iommi by default redirects to `..` after edit/create/delete. You can
override this via two methods:

- `extra__redirect_to`: a string with the url to redirect to. Relative URLs also work.
- `extra__redirect`: a callable that gets at least the keyword arguments `request`, `redirect_to`, `form`.

Form that after create redirects to the edit page of the object:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        extra__redirect=lambda form, **_: HttpResponseRedirect(form.instance.get_absolute_url() + 'edit/'),
    )

Form that after edit stays on the edit page:

.. code-block:: python

    form = Form.edit(
        auto__instance=album,
        extra__redirect_to='.',
    )

.. _dependent-fields:

How do I make a fields choices depend on another field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.choices
.. uses Form.fields

The contents of the form is sent with any AJAX requests, so we can
access the value of the other fields to do the filtering:

.. code-block:: python

    def album_choices(form, **_):
        if form.fields.artist.value:
            return Album.objects.filter(artist=form.fields.artist.value)
        else:
            return Album.objects.all()

.. code-block:: python

    Form(
        auto__model=Track,
        fields__artist=Field.choice_queryset(
            attr=None,
            choices=Artist.objects.all(),
            after=0,
        ),
        fields__album__choices=album_choices,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4421ab88-41b4-46f0-80a3-67aa58799463', this)">▼ Hide result</div>
    <iframe id="4421ab88-41b4-46f0-80a3-67aa58799463" src="doc_includes/cookbook_forms/test_how_do_I_make_a_fields_choices_depend_on_another_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _reverse-fk-form:

How do I enable a reverse foreign key relationship?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Form.auto
.. uses FormAutoConfig.instance

By default reverse foreign key relationships are hidden. To turn it on, pass `include=True` to the field. Note that these are read only, because the semantics of hijacking another models foreign keys would be quite weird.

.. code-block:: python

    f = Form(
        auto__instance=black_sabbath,
        fields__albums__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('1f809b6c-4622-4179-b4a9-beb644522e37', this)">▼ Hide result</div>
    <iframe id="1f809b6c-4622-4179-b4a9-beb644522e37" src="doc_includes/cookbook_forms/test_form_with_foreign_key_reverse.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _non-rendered-field:

How do I set an initial value on a field that is not in the form?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.non_rendered
.. uses Field.editable
.. uses Field.initial

You do have to include the field, but you can make it not rendered by using
the `non_rendered` shortcut and setting `initial`.

.. code-block:: python

    f = Form.create(
        auto__model=Album,
        fields__artist=Field.non_rendered(initial=black_sabbath),
        fields__year=Field.non_rendered(initial='1980'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7cdae4d6-61fe-42ca-8cb9-bcdddef75e8a', this)">▼ Hide result</div>
    <iframe id="7cdae4d6-61fe-42ca-8cb9-bcdddef75e8a" src="doc_includes/cookbook_forms/test_non_rendered.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If you post this form you will get this object:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('38e4dc0a-29d2-4e9c-a92c-02cdd94df734', this)">▼ Hide result</div>
    <iframe id="38e4dc0a-29d2-4e9c-a92c-02cdd94df734" src="doc_includes/cookbook_forms/test_non_rendered1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

By default this will be non-editable, but you can allow editing (via the
URL `GET` parameters) by setting `editable=True`.

.. code-block:: python

    f = Form.create(
        auto__model=Album,
        fields__artist=Field.non_rendered(initial=black_sabbath),
        fields__year=Field.non_rendered(
            initial='1980',
            editable=True,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('876559b0-7c23-4894-907d-5eefebceede3', this)">► Show result</div>
    <iframe id="876559b0-7c23-4894-907d-5eefebceede3" src="doc_includes/cookbook_forms/test_non_rendered2.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Accessing this create form with `?year=1999` in the URL will create this object on submit:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d95f6a13-8c9a-4938-8efe-b23e40a7faf8', this)">▼ Hide result</div>
    <iframe id="d95f6a13-8c9a-4938-8efe-b23e40a7faf8" src="doc_includes/cookbook_forms/test_non_rendered3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _group-fields:

How do I group fields?
~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.group
.. uses Form.field_group

Use the `group` parameter. Adjacent fields with the same `group` are wrapped
together; customize how that wrapper renders via the form's `field_group`
namespace:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__group='metadata',
        fields__artist__group='metadata',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('12c393d0-49df-43ae-9502-033152c51be0', this)">▼ Hide result</div>
    <iframe id="12c393d0-49df-43ae-9502-033152c51be0" src="doc_includes/cookbook_forms/test_grouped_fields.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

The wrapper around each group is a `field_group` fragment, so you can style it via
its `attrs`. For example, to put a red border around the group:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__year__group='metadata',
        fields__artist__group='metadata',
        field_group__attrs__style={
            'border': '1px solid red',
            'padding': '0.5rem',
        },
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7ad1a6ff-9dfc-4155-8800-41d2a9aad179', this)">▼ Hide result</div>
    <iframe id="7ad1a6ff-9dfc-4155-8800-41d2a9aad179" src="doc_includes/cookbook_forms/test_grouped_fields1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-reverse-m2m:

How do I show a reverse many-to-many relationship?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.include

By default reverse many-to-many relationships are hidden. To turn it on, pass `include=True` to the field:

.. code-block:: python

    form = Form(
        auto__model=Genre,
        instance=heavy_metal,
        fields__albums__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d5099708-b09f-42b8-b182-053b1fc78329', this)">▼ Hide result</div>
    <iframe id="d5099708-b09f-42b8-b182-053b1fc78329" src="doc_includes/cookbook_forms/test_form_with_m2m_key_reverse.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _nested-forms:

How do I nest multiple forms?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.fields
.. uses save_nested_forms
.. uses Action.post_handler
.. uses Form.read_nested_form_from_instance
.. uses Form.write_nested_form_to_instance

You need to use the ``save_nested_forms`` post handler to have a single save button for all the nested forms and edit tables.

When a nested form is bound to an instance, iommi reads the nested instance via
`read_nested_form_from_instance` and writes it back via
`write_nested_form_to_instance`. Override these if a nested form's instance isn't
simply an attribute of the parent's instance:

.. code-block:: python

    from iommi.form import save_nested_forms

    class MyNestedForm(Form):
        edit_ozzy = Form.edit(
            auto__model=Artist,
            instance=lambda **_: Artist.objects.get(name='Ozzy Osbourne'),
        )
        create_artist = Form.create(auto__model=Artist)
        edit_albums = EditTable(
            auto__model=Album,
            auto__include=['name', 'year'],
            columns__name__field__include=True,
        )

        class Meta:
            actions__submit__post_handler = save_nested_forms

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('cf84610a-9ffa-4841-8f0a-9a661568356f', this)">▼ Hide result</div>
    <iframe id="cf84610a-9ffa-4841-8f0a-9a661568356f" src="doc_includes/cookbook_forms/test_nested_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _fields-templates:

How do I use templates for fields?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Form.fields_template

Sometimes field groups just aren't enough and you may want to use a template to make your forms pretty:

.. code-block:: python

    class CommentForm(Form):
        class Meta:
            # language=html
            fields_template = Template(
                {{ fields.album.input }}
                <div class="row">
                    <div class="col">
                        {{ fields.name }}
                    </div>
                    <div class="col">
                        {{ fields.email }}
                    </div>
                </div>
                {{ fields.comment }}
            )

        name = Field()
        email = Field()
        comment = Field.textarea()
        album = Field.hardcoded(parsed_data=lambda **_: Album.objects.get(name='Heaven & Hell'))

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fbf06069-ce99-4a9b-811b-2f51bc626e97', this)">▼ Hide result</div>
    <iframe id="fbf06069-ce99-4a9b-811b-2f51bc626e97" src="doc_includes/cookbook_forms/test_fields_template.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _dependent-fields2:

How do I make a field that depends on the choice in another field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.choices

This only works for cases when the choices are fetched via ajax, but this is also the common case:

.. code-block:: python

    def album_choices(form, **_):
        if form.fields.artist.value:
            return Album.objects.filter(artist=form.fields.artist.value)
        else:
            return Album.objects.all()

    form = Form(
        auto__model=Track,
        # First choose an artist
        fields__artist=Field.choice_queryset(
            attr=None,
            choices=Artist.objects.all(),
            after=0,
        ),
        # Then choose an album
        fields__album__choices=album_choices,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4bcc5ba9-778f-4de1-ac06-d440ead017aa', this)">▼ Hide result</div>
    <iframe id="4bcc5ba9-778f-4de1-ac06-d440ead017aa" src="doc_includes/cookbook_forms/test_dependent_fields.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _create-or-edit-forms:

How do I make a create or edit form?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.editable
.. uses Form.create_or_edit
.. uses Form.instance
.. uses FormAutoConfig.type

If you don't know until runtime if you want `Form.create` or `Form.edit`,
you can use the `Form.create_or_edit` shortcut. If the `instance` is `None`
it will become a create form, otherwise an edit form:

.. code-block:: python

    form = Form.create_or_edit(
        auto__model=Album,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('47d0ae39-5186-4770-9cf4-ca2cb26bab6f', this)">▼ Hide result</div>
    <iframe id="47d0ae39-5186-4770-9cf4-ca2cb26bab6f" src="doc_includes/cookbook_forms/test_how_do_i_make_a_form_to_create_or_edit.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Using a lambda for a create form:

.. code-block:: python

    form = Form.create_or_edit(
        auto__model=Album,
        instance=lambda **_: None,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5db4eaae-4467-488c-a133-7af5d75e39b3', this)">▼ Hide result</div>
    <iframe id="5db4eaae-4467-488c-a133-7af5d75e39b3" src="doc_includes/cookbook_forms/test_how_do_i_make_a_form_to_create_or_edit1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Now an edit form:

.. code-block:: python

    form = Form.create_or_edit(
        auto__model=Album,
        instance=lambda **_: Album.objects.first(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8fb1b389-7748-422e-8242-d507f671c28e', this)">▼ Hide result</div>
    <iframe id="8fb1b389-7748-422e-8242-d507f671c28e" src="doc_includes/cookbook_forms/test_how_do_i_make_a_form_to_create_or_edit2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-hidden:

How do I create a hidden field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.hidden

Use the `Field.hidden` shortcut:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        fields__artist=Field.hidden(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('be2ccde4-1ea3-4314-8959-02f38b268575', this)">▼ Hide result</div>
    <iframe id="be2ccde4-1ea3-4314-8959-02f38b268575" src="doc_includes/cookbook_forms/test_how_do_i_create_a_hidden_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I access errors?
~~~~~~~~~~~~~~~~~~~~~~~
.. uses Form.errors
.. uses Field.errors

Forms render errors automatically, but sometimes it's useful to programmatically access the errors. There is `Form.get_errors` for all errors, and `Field.get_errors` for individual fields.

.. code-block:: python

    def post_validation(**_):
        raise ValidationError('Hardcoded error on the form')

    form = Form.create(
        auto__model=Album,
        fields__name__is_valid=lambda **_: (False, 'Hardcoded error on the field'),
        post_validation=post_validation,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('aaa63b35-7bab-4d69-ae8a-a7a4b5f12d0c', this)">► Show result</div>
    <iframe id="aaa63b35-7bab-4d69-ae8a-a7a4b5f12d0c" src="doc_includes/cookbook_forms/test_how_do_i_access_errors.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`Form.get_errors` returns this dictionary:

.. code-block:: python

    {
        'fields': {
            'artist': {
                'This field is required',
            },
            'name': {
                'Hardcoded error on the field',
            },
            'year': {
                'This field is required',
            },
        },
        'global': {
            'Hardcoded error on the form',
        },
    }

You can get the errors on a given `Field` like this (note that you get a `set`!):

.. code-block:: python

    form.fields.name.get_errors()

.. code-block:: python

    {"Hardcoded error on the field"}

.. _field-write-to-instance:

How do I customize how a field value is written to the instance?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Field.write_to_instance

Sometimes you need to customize how a field value is written to a model instance. The `write_to_instance` callback gives you full control over this process. It receives the field, instance, and value as parameters.

Here are some common use cases:

Password fields
^^^^^^^^^^^^^^^

Django's password fields require special handling with `set_password()`:

.. code-block:: python

    def write_password(form, instance, value, **_):
        if form.is_valid():
            instance.set_password(value)
            instance.save()

    form = Form.edit(
        auto__model=User,
        auto__include=['password'],
        fields__password__write_to_instance=write_password,
    )

Data transformation
^^^^^^^^^^^^^^^^^^^

Transform the data before saving (e.g., uppercase, calculations):

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        fields__name__write_to_instance=lambda field, instance, value, **_: setattr(instance, field.attr, value.upper()),
    )

Many-to-many relationships
^^^^^^^^^^^^^^^^^^^^^^^^^^

Many-to-many fields use `.set()` instead of direct assignment:

.. code-block:: python

    def genre_write_to_instance(instance, value, **_):
        instance.genres.set(value or [])

    form = Form.edit(
        auto__model=Album,
        auto__include=['genres'],
        fields__genres__write_to_instance=genre_write_to_instance,
    )

The default implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to extend the default behavior rather than replace it:

.. code-block:: python

    def log_and_write(field, instance, value, **kwargs):
        # Custom logic before writing
        print(f"Writing {value} to {field.attr}")

        # Call the default implementation
        Field.write_to_instance(field=field, instance=instance, value=value, **kwargs)

        # Custom logic after writing
        print(f"Successfully wrote to {instance}")

    form = Form.edit(
        auto__model=Album,
        auto__include=['name'],
        fields__name__write_to_instance=log_and_write,
    )

.. _complex-layouts-forms:

How do I make complex layouts for forms?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.layout
.. uses Form.layout_template
.. uses Form.layout_render_unused_fields
.. uses Panel.children
.. uses Panel.col
.. uses Panel.col_class
.. uses Panel.fieldset_legend
.. uses Panel.nested_path
.. uses Panel._parent_form
.. uses PanelCol.children

You can have more complex layout using the `panel` system. Set `layout` to a
`Panel` describing how the fields are arranged. By default any field you didn't
place in the layout raises an error; set `layout_render_unused_fields=True` to
render them after the layout instead, and point `layout_template` at your own
template to control the surrounding markup.

The pieces of a layout are `Panel` shortcuts: `Panel.row` lays out its `children`
side by side (each wrapped in a `col`, whose class is `col_class`), `Panel.field`
places a single field, and `Panel.fieldset` groups children under a
`fieldset_legend`. iommi links each `Panel` field to the matching `Form` field for
you - it tracks the owning form in `_parent_form` and uses `nested_path` to reach
fields of nested forms - and checks that every field is placed exactly once:

.. code-block:: python

    class UserForm(Form):
        class Meta:
            auto__model = User
            auto__exclude = ["password", "user_permissions"]

            layout = Panel(dict(
                p_main=Panel.card(
                    dict(
                        p_access=Panel.row(dict(
                            username=Panel.field(col__attrs__class__foo=True),  # test also custom col attrs
                            change_password_btn=Panel.part(
                                Fragment(
                                    text="Change password form is somewhere else",
                                    tag="div",
                                ),
                                include=lambda form, **_: form.editable and form.instance,
                            ),
                        )),
                        p_fullname=Panel.row(dict(
                            first_name=Panel.field(),
                            last_name=Panel.field(),
                        )),
                        email=Panel.field(),
                        is_active=Panel.field(),
                        p_dates=Panel.row(dict(
                            last_login=Panel.field(),
                            date_joined=Panel.field(),
                        )),
                        p_permissions=Panel.fieldset(
                            dict(
                                p_roles=Panel.row(dict(
                                    is_superuser=Panel.field(),
                                    is_staff=Panel.field(),
                                )),
                                groups=Panel.field(),
                            ),
                            legend=gettext_lazy("Permissions")
                        ),
                        p_error=Panel.alert("Error!", level="error"),
                    ),
                    header=lambda form, **_: form.instance.username if form.instance is not None else "New user",
                    footer=Template("<i>Let's put something in the footer</i>"),
                ),
            ))

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f77d88cd-db2b-4715-b7b2-998c25ba7307', this)">▼ Hide result</div>
    <iframe id="f77d88cd-db2b-4715-b7b2-998c25ba7307" src="doc_includes/cookbook_forms/test_layout_with_panels.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`Panel` fields are mapped to their corresponding `Form` fields automatically, and checked. That means that
if you create a complex layout and forget a field you will get an error, and vice versa.

The same way you can also use layouts for filter forms via `Table.query__form__layout`

.. _dropfile-dropimage:

How to make cool drag&drop file or image fields?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you don't want a regular file-inputs, you can use `Field.dropfile` and `Field.dropimage`:

.. code-block:: python

    form = Form.create(
        fields__my_document=Field.dropfile(display_name="My document"),
        fields__my_image=Field.dropimage(display_name="My image"),
        fields__existing_files=Field.dropfile(
            display_name="Existing multiple files",
            is_list=True,
            initial=existing_files,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fd49d387-2922-4473-b295-a62eb917964f', this)">▼ Hide result</div>
    <iframe id="fd49d387-2922-4473-b295-a62eb917964f" src="doc_includes/cookbook_forms/test_dropfile_dropimage_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

And of course you can also use `registrations </registrations.html#django-custom-fields>`__ to enable drag&drop for all file/image fields:

.. code-block:: python

    register_field_factory(FileField, shortcut_name='dropfile')
    register_field_factory(ImageField, shortcut_name='dropimage')

.. _form-actions:

How do I customize a form's buttons?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.actions
.. uses Form.actions_template

A form's buttons live in `actions`. Add, rename or restyle them there, and point
`actions_template` at your own template to control how the row of buttons is laid
out:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        actions__submit__display_name='Save album',
        actions__back=Action(display_name='Back', attrs__href='/'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('b629bb72-d1e3-4fed-b149-47d77b474570', this)">▼ Hide result</div>
    <iframe id="b629bb72-d1e3-4fed-b149-47d77b474570" src="doc_includes/cookbook_forms/test_how_do_i_customize_a_forms_actions.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _form-model-introspection:

How do I read the model information iommi found for a form?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.model
.. uses Field.model
.. uses Field.model_field
.. uses Field.model_field_name

When you build a form with `auto__model`, iommi sets `model` on the form and
`model_field`/`model_field_name` on each field for you. You rarely set these
yourself, but reading them lets you write field logic that adapts to the model.
Here `is_valid` reads the Django field's `verbose_name` off `model_field` to build
an error message that stays in sync with the model:

.. code-block:: python

    def year_is_valid(field, parsed_data, **_):
        if parsed_data is not None and parsed_data < 1900:
            return False, f'The {field.model_field.verbose_name} must be 1900 or later'
        return True, ''

    form = Form.create(
        auto__model=Album,
        fields__year__is_valid=year_is_valid,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('60f81364-4e94-4367-ba17-5272e79ec8c0', this)">▼ Hide result</div>
    <iframe id="60f81364-4e94-4367-ba17-5272e79ec8c0" src="doc_includes/cookbook_forms/test_how_do_i_read_the_model_information_of_a_form.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _customize-choices-display:

How do I customize how choices are displayed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.choice_display_name_formatter
.. uses Field.choice_id_formatter
.. uses Field.choice_to_optgroup
.. uses Field.empty_label
.. uses Field.is_list
.. uses Field.is_boolean

For a `Field.choice` (and the multi-select `Field.multi_choice`, which sets
`is_list`), control how each choice is shown with `choice_display_name_formatter`,
which value identifies it with `choice_id_formatter`, and how the options are
grouped with `choice_to_optgroup`. `empty_label` sets the text of the blank option
of a non-required choice. Boolean fields set `is_boolean`:

.. code-block:: python

    form = Form(
        fields__color=Field.choice(
            choices=['red', 'green', 'blue'],
            required=False,
            choice_display_name_formatter=lambda choice, **_: choice.upper(),
            empty_label='(pick a color)',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('68b9d4be-61ba-4035-8513-7afbda1fe354', this)">▼ Hide result</div>
    <iframe id="68b9d4be-61ba-4035-8513-7afbda1fe354" src="doc_includes/cookbook_forms/test_how_do_i_customize_how_choices_are_displayed.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-label-help:

How do I customize a field's label and help text?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.label
.. uses Field.help
.. uses Field.help_text

Set `display_name` for the label text (or configure the `label` fragment for its
markup). `help_text` sets the help string - it defaults to the Django model
field's help text - and `help` is the fragment that renders it:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__display_name='Album title',
        fields__name__help_text='The name as printed on the cover',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('306d58e8-df02-4d11-8a99-e1c84ff8e46e', this)">▼ Hide result</div>
    <iframe id="306d58e8-df02-4d11-8a99-e1c84ff8e46e" src="doc_includes/cookbook_forms/test_how_do_i_customize_the_label_and_help_text.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-raw-data:

How do I control how a field's input is read and rendered?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.raw_data
.. uses Field.strip_input
.. uses Field.parse_empty_string_as_none
.. uses Field.render_value
.. uses Field.render_value_on_error
.. uses Field.non_editable_input

Several hooks control the round trip between the raw request string and the value
shown to the user:

- `strip_input` (default `True`) runs `.strip()` on the incoming string.
- `parse_empty_string_as_none` (default `True`) turns an empty string into `None` before parsing.
- `render_value` turns the parsed value back into a string for display.
- `render_value_on_error` decides what to show when parsing failed (defaults to the raw input).
- `raw_data` is the unparsed string from the request.
- `non_editable_input` is the fragment used to render the value when the field is not editable.

For example, to always display the value upper-cased:

.. code-block:: python

    form = Form(
        fields__foo=Field(
            initial='hello',
            render_value=lambda form, field, value, **_: value.upper(),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('87bc8d11-4881-4e4e-b321-349a30e1679f', this)">▼ Hide result</div>
    <iframe id="87bc8d11-4881-4e4e-b321-349a30e1679f" src="doc_includes/cookbook_forms/test_how_do_i_control_how_input_is_parsed_and_rendered.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _field-read-from-instance:

How do I change how a field reads its value from the instance?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Field.read_from_instance

By default a field reads its value as `getattr_path(instance, field.attr)`.
Override `read_from_instance` to compute the value some other way (the matching
write hook is `write_to_instance`):

.. code-block:: python

    form = Form.edit(
        auto__model=Album,
        instance=album,
        fields__name__read_from_instance=lambda field, instance, **_: instance.name.upper(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d763294d-f22c-40ed-bef8-678a952687ab', this)">▼ Hide result</div>
    <iframe id="d763294d-f22c-40ed-bef8-678a952687ab" src="doc_includes/cookbook_forms/test_how_do_i_change_how_a_field_reads_from_the_instance.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _form-save-hooks:

How do I hook into saving a create/edit form?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Form.extra
.. uses Form.instance
.. uses FormAutoConfig.model

If all you want is to set a value that isn't in the form, use
:ref:`Field.hardcoded <field-hardcoded>` instead: it's simpler and it keeps the
value visible in the form definition.

For anything else, `Form.create` and `Form.edit` expose a callback per step of
the save. To supply a value the form doesn't collect, build the object yourself
in `extra__new_instance`:

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__exclude=['artist'],
        extra__new_instance=lambda form, **_: Album(artist=black_sabbath),
    )

.. note::

    On `Form.create` the instance is saved *twice*, because Django has to have a
    pk before related fields can be written. That means `extra__pre_save` runs
    after the first insert, so it is too late to fill in a `NOT NULL` column. Use
    `extra__new_instance` or `extra__pre_save_all_but_related_fields` for that.
    On `Form.edit` there is only one save and `extra__pre_save` runs before it.

The full list of callbacks, and the order they run in, is documented under
:ref:`Save callbacks <form-save-callbacks>` on `Form`.

The one to be careful with is `extra__save`. It receives the object to save as
`model_object` (**not** `instance`), and it is called once per model when the
form spans more than one, so always check which model you got before doing
anything model specific:

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'artist__name']

            @staticmethod
            def extra__save(model_object, **_):
                if isinstance(model_object, Album):
                    model_object.save()
                else:
                    # this also gets called for saving artist.name
                    model_object.save()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4efcea16-cf90-484f-b0e1-b9b206e55457', this)">▼ Hide result</div>
    <iframe id="4efcea16-cf90-484f-b0e1-b9b206e55457" src="doc_includes/cookbook_forms/test_how_do_i_hook_into_saving.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





.. _cookbook-tables:

Tables
------

How do I customize the rendering of a table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Table rendering can be customized on multiple levels. You pass a template with the `template` argument, which
is either a template name or a `Template` object.

Customize the HTML attributes of the table tag via the `attrs` argument. See :ref:`attrs <attributes>`.

To customize the row, see `How do I customize the rendering of a row?`_

To customize the cell, see `How do I customize the rendering of a cell?`_

To customize the rendering of the table, see `table-as-div`_

.. _turn-off-pagination:

How do you turn off pagination?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.page_size
.. uses EditTable.page_size
.. uses TableAutoConfig.model

Specify `page_size=None`:

.. code-block:: python

    table = Table(
        auto__model=Album,
        page_size=None,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('b03d4b19-cf7d-4854-928a-32f41e12f827', this)">▼ Hide result</div>
    <iframe id="b03d4b19-cf7d-4854-928a-32f41e12f827" src="doc_includes/cookbook_tables/test_how_do_you_turn_off_pagination.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Or in the declarative style:

.. code-block:: python

    class MyTable(Table):
        name = Column()

        class Meta:
            page_size = None

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c58e1f96-3200-4d45-ab0e-9589cb16249f', this)">▼ Hide result</div>
    <iframe id="c58e1f96-3200-4d45-ab0e-9589cb16249f" src="doc_includes/cookbook_tables/test_how_do_you_turn_off_pagination1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. uses Table.parts
.. uses EditTable.parts

The paginator itself is a `part` of the table named `page`, so you can configure
it through the `parts` namespace, e.g. `parts__page__title='Page'`.

.. _customize-table-cell-render:

How do I customize the rendering of a cell?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Attrs
.. uses Cell.attrs
.. uses Cell.template
.. uses Cell.url
.. uses EditCell.attrs
.. uses EditCell.template
.. uses EditCell.url
.. uses Column.cell
.. uses EditColumn.cell

You can customize the :doc:`Cell` rendering in several ways:

- You can modify the html attributes via `cell__attrs`. See :ref:`attrs <attributes>`.

- Use `cell__template` to specify a template. You can give a string and it will be interpreted as a template name, or you can pass a `Template` object.

- Pass a url (or callable that returns a url) to `cell__url` to make the cell a link (see next question).

.. _cell-link:

How do I make a link in a cell?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Cell.url
.. uses EditCell.url
.. uses Column.cell
.. uses EditColumn.cell
.. uses Table.columns
.. uses TableAutoConfig.model

This is such a common case that there's a special case for it: pass the `url` and `url_title` parameters to the `cell`:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__cell__url='http://example.com',
        columns__name__cell__url_title='go to example',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a2bb6389-76c6-4d08-875f-d38a555fd569', this)">▼ Hide result</div>
    <iframe id="a2bb6389-76c6-4d08-875f-d38a555fd569" src="doc_includes/cookbook_tables/test_how_do_i_make_a_link_in_a_cell.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _column-computed-data:

How do I create a column based on computed data (i.e. a column not based on an attribute of the row)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Cell.value
.. uses Cell.format
.. uses EditCell.value
.. uses EditCell.format
.. uses Column.cell
.. uses EditColumn.cell
.. uses Table.columns
.. uses EditTable.columns
.. uses TableAutoConfig.model

Let's say we have a model like this:

.. code-block:: python

    class Foo(models.Model):
        value = models.IntegerField()

And we want a computed column `square` that is the square of the value, then we can do:

.. code-block:: python

    table = Table(
        auto__model=Foo,
        columns__square=Column(
            # computed value:
            cell__value=lambda row, **_: row.value * row.value,
        )
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0d220f4a-11a5-489b-ac22-160a5876e67c', this)">▼ Hide result</div>
    <iframe id="0d220f4a-11a5-489b-ac22-160a5876e67c" src="doc_includes/cookbook_tables/test_how_do_i_create_a_column_based_on_computed_data_.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

or we could do:

.. code-block:: python

    Table(
        auto__model=Foo,
        columns__square=Column(
            attr='value',
            cell__format=lambda value, **_: value * value,
        )
    )

This only affects the formatting when we render the cell value. Which might make more sense depending on your situation but for the simple case like we have here the two are equivalent.

How do I get iommi tables to understand my Django ModelField subclasses?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See :doc:`registrations`.

.. _reorder-columns:

How do I reorder columns?
~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Column.after
.. uses EditColumn.after
.. uses Table.columns
.. uses TableAutoConfig.model

By default the columns come in the order defined so if you have an explicit table defined, just move them around there. If the table is generated from a model definition, you can also move them in the model definition if you like, but that might not be a good idea. So to handle this case we can set the ordering on a column by giving it the `after` argument. Let's start with a simple model:

.. code-block:: python

    class Foo(models.Model):
        a = models.IntegerField()
        b = models.IntegerField()
        c = models.IntegerField()

If we just do `Table(auto__model=Foo)` we'll get the columns in the order a, b, c. But let's say I want to put c first, then we can pass it the `after` value `-1`:

.. code-block:: python

    table = Table(auto__model=Foo, columns__c__after=-1)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e69784b6-3729-4770-a76a-bd1b9d921067', this)">▼ Hide result</div>
    <iframe id="e69784b6-3729-4770-a76a-bd1b9d921067" src="doc_includes/cookbook_tables/test_how_do_i_reorder_columns.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`-1` means the first, other numbers mean index. We can also put columns after another named column like so:

.. code-block:: python

    table = Table(auto__model=Foo, columns__c__after='a')

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('464c9329-eaf7-4329-8e36-55c8098dfadc', this)">▼ Hide result</div>
    <iframe id="464c9329-eaf7-4329-8e36-55c8098dfadc" src="doc_includes/cookbook_tables/test_how_do_i_reorder_columns1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

this will put the columns in the order a, c, b.

There is a special value `LAST` (import from `iommi.declarative`) to put something last in a list:

.. code-block:: python

    table = Table(auto__model=Foo, columns__a__after=LAST)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('71e83340-b2ba-426d-9fb2-91e051d52f2f', this)">▼ Hide result</div>
    <iframe id="71e83340-b2ba-426d-9fb2-91e051d52f2f" src="doc_includes/cookbook_tables/test_how_do_i_reorder_columns2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-column:

How do I enable searching/filter on columns?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Column.filter
.. uses EditColumn.filter
.. uses Filter.include
.. uses TableAutoConfig.model

Pass the value `filter__include=True` to the column, to enable searching
in the advanced query language.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__filter__include=True,
    )

The `filter` namespace here is used to configure a :doc:`Filter` so you can
configure the behavior of the searching by passing parameters here.

The `filter__field` namespace is used to configure the :doc:`Field`, so here you
can pass any argument to `Field` here to customize it.

If you just want to have the filter available in the advanced query language,
you can turn off the field in the generated form by passing
`filter__field__include=False`:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5940c949-1642-4448-b2a9-0303a27631af', this)">▼ Hide result</div>
    <iframe id="5940c949-1642-4448-b2a9-0303a27631af" src="doc_includes/cookbook_tables/test_how_do_i_enable_searching_filter_on_columns.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _freetext-column:

How do I make a freetext search field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Filter.freetext
.. uses Column.filter
.. uses TableAutoConfig.model

If you want to filter based on a freetext query on one or more columns we've got a nice little feature for this:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__filter=dict(
            freetext=True,
            include=True,
        ),
        columns__year__filter__freetext=True,
        columns__year__filter__include=True,
    )

This will display one search box to search both `year` and `name` columns:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5f4577bc-ad0c-48a3-81c7-304c38f3a69d', this)">▼ Hide result</div>
    <iframe id="5f4577bc-ad0c-48a3-81c7-304c38f3a69d" src="doc_includes/cookbook_tables/test_how_do_i_make_a_freetext_search_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I customize HTML attributes, CSS classes or CSS style specifications?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.attrs
.. uses Form.attrs
.. uses Field.attrs

The `attrs` namespace has special handling to make it easy to customize. There are three main cases:

First the straight forward case where a key/value pair is rendered in the output:

.. code-block:: pycon

    >>> from iommi.attrs import render_attrs
    >>> from iommi.declarative.namespace import Namespace
    >>> render_attrs(Namespace(foo='bar'))
    ' foo="bar"'

Then there's a special handling for CSS classes:

.. code-block:: pycon

    >>> render_attrs(Namespace(class__foo=True, class__bar=True))
    ' class="bar foo"'

Note that the class names are sorted alphabetically on render.

Lastly there is the special handling of `style`:

.. code-block:: pycon

    >>> render_attrs(Namespace(style__font='Arial'))
    ' style="font: Arial"'

If you need to add a style with `-` in the name you have to do this:


.. code-block:: pycon

    >>> render_attrs(Namespace(**{'style__font-family': 'sans-serif'}))
    ' style="font-family: sans-serif"'


Everything together:

.. code-block:: pycon

    >>> render_attrs(
    ...     Namespace(
    ...         foo='bar',
    ...         class__foo=True,
    ...         class__bar=True,
    ...         style__font='Arial',
    ...         **{'style__font-family': 'serif'}
    ...     )
    ... )
    ' class="bar foo" foo="bar" style="font-family: serif; font: Arial"'

.. _customize-rendering-row:

How do I customize the rendering of a row?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.row
.. uses EditTable.row
.. uses RowConfig.attrs
.. uses RowConfig.template

You can customize the row rendering in two ways:

- You can modify the html attributes via `row__attrs`. See :ref:`attrs <attributes>`.

- Use `row__template` to specify a template. You can give a string and it will be interpreted as a template name, or you can pass a `Template` object.

In templates you can access the raw row via `row`. This would typically be one of your model objects. You can also access the cells of the table via `cells`. A naive template for a row would be `<tr>{% for cell in cells %}<td>{{ cell }}{% endfor %}</tr>`. You can access specific cells by their column names like `{{ cells.artist }}`.

To customize the cell, see `How do I customize the rendering of a cell?`_

.. _customize-header:

How do I customize the rendering of a header?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.header
.. uses EditColumn.header

You can customize headers in two ways:

- You can modify the html attributes via `header__attrs`. See :ref:`attrs <attributes>`.

- Use `header__template` to specify a template. You can give a string and it will be interpreted as a template name, or you can pass a `Template` object.

.. _turn-off-header:

How do I turn off the header?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.header
.. uses EditTable.header

Set `header__template` to `None`.

How do I add fields to a table that is generated from a model?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See the question `column-computed-data`_

.. _show-columns:

How do I specify which columns to show?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.include
.. uses EditColumn.include
.. uses Column.render_column
.. uses EditColumn.render_column
.. uses TableAutoConfig.model
.. uses TableAutoConfig.include
.. uses TableAutoConfig.exclude
.. uses TableAutoConfig.default_included

Pass `include=False` to hide the column or `include=True` to show it. By default columns are shown, except the primary key column that is by default hidden. You can also pass a callable here like so:

.. code-block:: python

    Table(
        auto__model=Album,
        columns__name__include=
            lambda request, **_: request.GET.get('some_parameter') == 'hello!',
    )

This will show the column `name` only if the GET parameter `some_parameter` is set to `hello!`.

To be more precise, `include` turns off the entire column. Sometimes you want to have the searching turned on, but disable the rendering of the column. To do this use the `render_column` parameter instead. This is useful for example to turn on filtering for a column, but not render it:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__year__render_column=False,
        columns__year__filter__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('941ea0ca-3021-48af-a58c-b09e3186002f', this)">▼ Hide result</div>
    <iframe id="941ea0ca-3021-48af-a58c-b09e3186002f" src="doc_includes/cookbook_tables/test_how_do_i_specify_which_columns_to_show.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Use `auto__include` to specify the complete list of columns you want:

.. code-block:: python

    table = Table(
        auto__model=Album,
        auto__include=['name', 'artist'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('487c7921-b547-4b17-be88-ce253245ab99', this)">▼ Hide result</div>
    <iframe id="487c7921-b547-4b17-be88-ce253245ab99" src="doc_includes/cookbook_tables/test_how_do_i_specify_which_columns_to_show1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Instead of using `auto__include`, you can also use `auto__exclude` to just exclude the columns you don't want:

.. code-block:: python

    table = Table(
        auto__model=Album,
        auto__exclude=['year'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8bc1e759-3909-4aff-b37d-5d20adc9a441', this)">▼ Hide result</div>
    <iframe id="8bc1e759-3909-4aff-b37d-5d20adc9a441" src="doc_includes/cookbook_tables/test_how_do_i_specify_which_columns_to_show2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There is also a config option `default_included` which is by default `True`, which is where iommi's default behavior of showing all columns comes from. If you set it to `False` columns are now opt-in:

.. code-block:: python

    table = Table(
        auto__model=Album,
        auto__default_included=False,
        # Turn on only the name column
        columns__name__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('02b7ba22-a33e-47de-8e3e-554a82458935', this)">▼ Hide result</div>
    <iframe id="02b7ba22-a33e-47de-8e3e-554a82458935" src="doc_includes/cookbook_tables/test_how_do_i_specify_which_columns_to_show3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _programmatic-table-data-access:

How do I access table data programmatically (like for example to dump to json)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.cells_for_rows
.. uses EditTable.cells_for_rows

Here's a simple example that prints a table to stdout:

.. code-block:: python

    def print_table(table):
        for row in table.cells_for_rows():
            for cell in row:
                print(cell.render_formatted(), end=' ')
            print()

    table = Table(auto__model=Album).bind(request=req('get'))
    print_table(table)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fdcce49e-ec4d-4c77-b440-33021db9c149', this)">▼ Hide result</div>
    <iframe id="fdcce49e-ec4d-4c77-b440-33021db9c149" src="doc_includes/cookbook_tables/test_how_do_i_access_table_data_programmatically_.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _fk-related-data-access:

How do I access foreign key related data in a column?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.attr
.. uses Table.auto
.. uses EditColumn.attr
.. uses EditTable.auto

Let's say we have two models:

.. code-block:: python

    class Foo(models.Model):
        a = models.IntegerField()

.. code-block:: python

    class Bar(models.Model):
        b = models.IntegerField()
        c = models.ForeignKey(Foo, on_delete=models.CASCADE)

we can build a table of `Bar` that shows the data of `a` like this:

.. code-block:: python

    table = Table(
        auto__model=Bar,
        columns__a=Column(attr='c__a'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('17e10d08-bf2e-466a-9a2d-c4d97107d1da', this)">▼ Hide result</div>
    <iframe id="17e10d08-bf2e-466a-9a2d-c4d97107d1da" src="doc_includes/cookbook_tables/test_how_do_i_access_foreign_key_related_data_in_a_column.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Or like this:

.. code-block:: python

    table = Table(
        auto__model=Bar,
        include=['b', 'c__a'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('be18e903-1729-4faa-9e47-73df4d573559', this)">▼ Hide result</div>
    <iframe id="be18e903-1729-4faa-9e47-73df4d573559" src="doc_includes/cookbook_tables/test_how_do_i_access_foreign_key_related_data_in_a_column1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

iommi will do automatic `select_related` and/or `prefetch_related` as appropriate in many cases too, so you mostly don't need to worry about that.

.. _table-sorting:

How do I turn off sorting? (on a column or table wide)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.sortable
.. uses Column.sortable
.. uses EditTable.sortable
.. uses EditColumn.sortable

To turn off sorting on a column pass it `sortable=False` (you can also use a lambda here!):

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__sortable=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e976f537-0bbe-49e5-ba4f-0b06c9c6ad30', this)">▼ Hide result</div>
    <iframe id="e976f537-0bbe-49e5-ba4f-0b06c9c6ad30" src="doc_includes/cookbook_tables/test_how_do_i_turn_off_sorting.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

and to turn it off on the entire table:

.. code-block:: python

    table = Table(
        auto__model=Album,
        sortable=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('44f55f04-fda1-46c8-ba80-aa345b64a74c', this)">▼ Hide result</div>
    <iframe id="44f55f04-fda1-46c8-ba80-aa345b64a74c" src="doc_includes/cookbook_tables/test_how_do_i_turn_off_sorting1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _header-title:

How do I specify the title of a header?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.display_name
.. uses EditColumn.display_name

The `display_name` property of a column is displayed in the header.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__display_name='header title',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9831c3c7-8121-4797-bcb7-8816ee17ea02', this)">▼ Hide result</div>
    <iframe id="9831c3c7-8121-4797-bcb7-8816ee17ea02" src="doc_includes/cookbook_tables/test_how_do_i_specify_the_title_of_a_header.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _sort-direction:

How do I set the default sort direction of a column to be descending instead of ascending?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.sort_default_desc
.. uses EditColumn.sort_default_desc

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__sort_default_desc=True,  # or a lambda!
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fa07175c-e001-44d2-a296-9ad86ac1e2b8', this)">► Show result</div>
    <iframe id="fa07175c-e001-44d2-a296-9ad86ac1e2b8" src="doc_includes/cookbook_tables/test_how_do_i_set_the_default_sort_order_of_a_column_to_be_descending_instead_of_ascending.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _default-sort-order:

How do I set the default sorting column of a table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.default_sort_order
.. uses EditTable.default_sort_order

Tables are sorted by default on the order specified in the models `Meta` and then on `pk`. Set `default_sort_order` to set another default ordering:

.. code-block:: python

    table = Table(
        auto__model=Album,
        default_sort_order='year',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f959c450-f600-43d7-994e-a695c3712ab2', this)">▼ Hide result</div>
    <iframe id="f959c450-f600-43d7-994e-a695c3712ab2" src="doc_includes/cookbook_tables/test_how_do_i_set_the_default_sort_order_on_a_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Or reversed:

.. code-block:: python

    table = Table(
        auto__model=Album,
        default_sort_order='-year',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('bcc00156-d256-4ef0-8cf7-d86c29a10657', this)">▼ Hide result</div>
    <iframe id="bcc00156-d256-4ef0-8cf7-d86c29a10657" src="doc_includes/cookbook_tables/test_how_do_i_set_the_default_sort_order_on_a_table1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    table = Table(
        auto__model=Album,
        default_sort_order='artist',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('eeb613f5-9943-4bed-bd45-daf202a3b962', this)">▼ Hide result</div>
    <iframe id="eeb613f5-9943-4bed-bd45-daf202a3b962" src="doc_includes/cookbook_tables/test_how_do_i_set_the_default_sort_order_on_a_table2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _group-columns:

How do I group columns?
~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.group
.. uses EditColumn.group
.. uses TableAutoConfig.model

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__group='foo',
        columns__artist__group='bar',
        columns__year__group='bar',
    )

The grouping only works if the columns are next to each other, otherwise you'll get multiple groups. The groups are rendered by default as a second header row above the normal header row with colspans to group the headers.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('aac3a110-4fed-48ca-84c8-2b61c9faed02', this)">▼ Hide result</div>
    <iframe id="aac3a110-4fed-48ca-84c8-2b61c9faed02" src="doc_includes/cookbook_tables/test_how_do_i_group_columns.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _group-rows:

How do I group rows?
~~~~~~~~~~~~~~~~~~~~
.. uses Column.row_group
.. uses EditColumn.row_group
.. uses TableAutoConfig.rows

Use `row_group`. By default this will output a `<th>` tag. You can configure it like any other fragment if you want to change that to a `<td>`. Note that the order of the columns in the table is used for grouping. This is why in the example below the `year` column is moved to index zero: we want to group on year first.

.. code-block:: python

    table = Table(
        auto__rows=Album.objects.order_by('year', 'artist', 'name'),
        columns__artist=dict(
            row_group__include=True,
            render_column=False,
        ),
        columns__year=dict(
            after=0,
            render_column=False,
            row_group=dict(
                include=True,
                template=Template('''
                <tr>
                    {{ row_group.iommi_open_tag }}
                        {{ value }} in our hearts
                    {{ row_group.iommi_close_tag }}
                </tr>
                '''),
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('921d59ba-2059-4a45-a731-908be32f8838', this)">▼ Hide result</div>
    <iframe id="921d59ba-2059-4a45-a731-908be32f8838" src="doc_includes/cookbook_tables/test_how_do_i_group_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _rowspan:

How do I get rowspan on a table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.auto_rowspan
.. uses EditColumn.auto_rowspan

You can manually set the rowspan attribute via `row__attrs__rowspan` but this is tricky to get right because you also have to hide the cells that are "overwritten" by the rowspan. We supply a simpler method: `auto_rowspan`. It automatically makes sure the rowspan count is correct and the cells are hidden. It works by checking if the value of the cell is the same, and then it becomes part of the rowspan.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__year__auto_rowspan=True,
        columns__year__after=0,  # put the column first
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7bf2a2e6-7927-4a61-b168-e66f24738724', this)">▼ Hide result</div>
    <iframe id="7bf2a2e6-7927-4a61-b168-e66f24738724" src="doc_includes/cookbook_tables/test_how_do_i_get_rowspan_on_a_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _bulk-edit:

How do I enable bulk editing?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.bulk
.. uses EditColumn.bulk

Editing multiple items at a time is easy in iommi with the built in bulk
editing. Enable it for a column by passing `bulk__include=True`:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__year__bulk__include=True,
    )

The bulk namespace here is used to configure a `Field` for the GUI so you
can pass any parameter you can pass to `Field` there to customize the
behavior and look of the bulk editing for the column.

The `select` column, used to pick the rows to bulk edit, is shown
automatically when bulk editing is enabled.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8fddbff2-250f-4a1c-ba58-68377d8ffa07', this)">▼ Hide result</div>
    <iframe id="8fddbff2-250f-4a1c-ba58-68377d8ffa07" src="doc_includes/cookbook_tables/test_how_do_i_enable_bulk_editing.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _bulk-delete:

How do I enable bulk delete?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.bulk
.. uses EditTable.bulk

.. code-block:: python

    table = Table(
        auto__model=Album,
        bulk__actions__delete__include=True,
    )

To enable the bulk delete, enable the `delete` action.

The `select` column, used to pick the rows to delete, is shown
automatically when a bulk action is enabled.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fcfab03c-aa96-4a26-b27a-e526999f4511', this)">▼ Hide result</div>
    <iframe id="fcfab03c-aa96-4a26-b27a-e526999f4511" src="doc_includes/cookbook_tables/test_how_do_i_enable_bulk_delete.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-bulk-action:

How do I make a custom bulk action?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.bulk
.. uses EditTable.bulk

Define a submit `Action` with a post handler. The `select` column, used to
pick the rows to operate on, is shown automatically when a bulk action is
enabled:

.. code-block:: python

    def my_action_post_handler(table, request, **_):
        queryset = table.bulk_queryset()
        queryset.update(name='Paranoid')
        return HttpResponseRedirect(request.META['HTTP_REFERER'])

    t = Table(
        auto__model=Album,
        bulk__actions__my_action=Action.submit(
            post_handler=my_action_post_handler,
        )
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e7973a7b-4629-4d53-b568-5476c9260008', this)">▼ Hide result</div>
    <iframe id="e7973a7b-4629-4d53-b568-5476c9260008" src="doc_includes/cookbook_tables/test_how_do_i_make_a_custom_bulk_action.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _attr-name-diff:

What is the difference between `attr` and `_name`?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.attr
.. uses Column.name
.. uses EditColumn.attr
.. uses EditColumn.name
.. uses Column.cell
.. uses EditColumn.cell

`attr` is the attribute path of the value iommi reads from a row. In the simple case it's just the attribute name, but if you want to read the attribute of an attribute you can use `__`-separated paths for this: `attr='foo__bar'` is functionally equivalent to `cell__value=lambda row, **_: row.foo.bar`. Set `attr` to `None` to not read any attribute from the row.

`_name` is the name used internally. By default `attr` is set to the value of `_name`. This name is used when accessing the column from `Table.columns` and it's the name used in the GET parameter to sort by that column. This is a required field.

.. _reverse-fk-table:

How do I show a reverse foreign key relationship?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.include
.. uses EditColumn.include

By default reverse foreign key relationships are hidden. To turn it on, pass `include=True` to the column:

.. code-block:: python

    t = Table(
        auto__model=Artist,
        columns__albums__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('caaf737b-0aad-45a5-bf52-934a2c415a73', this)">▼ Hide result</div>
    <iframe id="caaf737b-0aad-45a5-bf52-934a2c415a73" src="doc_includes/cookbook_tables/test_table_with_foreign_key_reverse.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _reverse-m2m:

How do I show a reverse many-to-many relationship?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.include
.. uses EditColumn.include

By default reverse many-to-many relationships are hidden. To turn it on, pass `include=True` to the column:

.. code-block:: python

    t = Table(
        auto__model=Genre,
        columns__albums__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('3f507598-94ba-4e5b-9501-4080e6d8045d', this)">▼ Hide result</div>
    <iframe id="3f507598-94ba-4e5b-9501-4080e6d8045d" src="doc_includes/cookbook_tables/test_table_with_m2m_key_reverse.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _arbitrary-html:

How do I insert arbitrary html into a Table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.container
.. uses Table.outer
.. uses EditTable.container
.. uses EditTable.outer

Sometimes you want to insert some extra html, css, or `Part` into a
`Table`. You can do this with the `container` or `outer` namespaces.

For `container`, by default items are added after the table but you
can put them above with `after=0`.

For `outer`, you can put content before the `h` tag even.

.. code-block:: python

    t = Table(
        auto__model=Genre,
        container__children__foo='Foo',
        container__children__bar=html.div('Bar', after=0),
        outer__children__bar=html.div('Baz', after=0),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8082242c-5c8b-443f-99a4-458c4b9452a6', this)">▼ Hide result</div>
    <iframe id="8082242c-5c8b-443f-99a4-458c4b9452a6" src="doc_includes/cookbook_tables/test_insert_arbitrary_html.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-actions:

How do I add custom actions/links to a table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.actions
.. uses Cell.url
.. uses Column.link
.. uses EditTable.actions
.. uses EditCell.url
.. uses EditColumn.link

For the entire table:

.. code-block:: python

    t = Table(
        auto__model=Album,
        actions__link=Action(attrs__href='/'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('20526108-3f5c-45b2-972c-62bc88e92a7c', this)">▼ Hide result</div>
    <iframe id="20526108-3f5c-45b2-972c-62bc88e92a7c" src="doc_includes/cookbook_tables/test_custom_actions.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Or as a column:

.. code-block:: python

    t = Table(
        auto__model=Album,
        columns__link=Column.link(attr=None, cell__url='/', cell__value='Link'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('707d1477-71f0-4987-a936-24affccd5c64', this)">▼ Hide result</div>
    <iframe id="707d1477-71f0-4987-a936-24affccd5c64" src="doc_includes/cookbook_tables/test_custom_actions1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _additional-rows:

How do I render additional rows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.rows
.. uses EditTable.rows
.. uses RowConfig.template

Using `row__template` you can render the default row with `{{ cells.render }}` and then your own custom data:

.. code-block:: python

    t = Table(
        auto__model=Album,
        row__template=Template('''
            {{ cells.render }}
            <tr>
                <td style="text-align: center" colspan="{{ cells|length }}">🤘🤘</td>
            </tr>
        '''),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('34f3f729-e894-46cb-aeee-75ab5fc71b72', this)">▼ Hide result</div>
    <iframe id="34f3f729-e894-46cb-aeee-75ab5fc71b72" src="doc_includes/cookbook_tables/test_render_additional_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _initial-filter:

How do I set an initial filter to a table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.query
.. uses EditTable.query
.. uses Query.form

The `Query` of a `Table` has a `Form` where you can set the initial value:

.. code-block:: python

    t = Table(
        auto__model=Album,
        columns__artist__filter__include=True,
        query__form__fields__artist__initial=lambda **_: Artist.objects.get(name='Dio'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ab0bad4d-daf2-4e83-9a1e-5cd0502c136e', this)">▼ Hide result</div>
    <iframe id="ab0bad4d-daf2-4e83-9a1e-5cd0502c136e" src="doc_includes/cookbook_tables/test_initial_filter_on_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _query-from-indexes:

How do I automatically create filters for indexed fields?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.query_from_indexes
.. uses EditTable.query_from_indexes

When you have a model with database indexes, you can use `query_from_indexes=True` to automatically create filters for all the indexed fields. This is useful to quickly get a table with a bunch of filters that you know are performant.

Consider a model where only some fields have database indexes:

.. code-block:: python

    table = Table(
        auto__model=Track,
        query_from_indexes=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('3612d56f-0af3-4d14-92f1-e82769776b04', this)">▼ Hide result</div>
    <iframe id="3612d56f-0af3-4d14-92f1-e82769776b04" src="doc_includes/cookbook_tables/test_query_from_indexes.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Without `query_from_indexes`, you need to manually specify which columns should have filters using `columns__<field>__filter__include=True`.

.. _row-numbers:

How do I show row numbers?
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Cells.row_index
.. uses Cell.value
.. uses EditCells.row_index
.. uses EditCell.value
.. uses Column.cell
.. uses EditColumn.cell

Use `cells.row_index` to get the index of the row in the current rendering.

.. code-block:: python

    t = Table(
        auto__model=Album,
        columns__index=Column(
            after=0,
            cell__value=lambda row, cells, **_: cells.row_index
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ce091fbb-9051-44d2-b2f6-7995a3f01d1a', this)">▼ Hide result</div>
    <iframe id="ce091fbb-9051-44d2-b2f6-7995a3f01d1a" src="doc_includes/cookbook_tables/test_indexed_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _nested-fk:

How do I show nested foreign key relationships?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.auto
.. uses EditTable.auto
.. uses Column.cell
.. uses EditColumn.cell
.. uses TableAutoConfig.include

Say you have a list of tracks and you want to show the album and then from that album, you also want to show the artist:

.. code-block:: python

    t = Table(
        auto__model=Track,
        auto__include=[
            'name',
            'album',
            'album__artist',  # <--
        ]
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7a21f2f2-36c3-4bc8-a9f0-378670353ce0', this)">▼ Hide result</div>
    <iframe id="7a21f2f2-36c3-4bc8-a9f0-378670353ce0" src="doc_includes/cookbook_tables/test_nested_foreign_keys.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

The column created is named `album_artist` (as `__` is reserved for traversing a namespace), so that's the name you need to reference if you need to add more configuration to that column:

.. code-block:: python

    t = Table(
        auto__model=Track,
        auto__include=[
            'name',
            'album',
            'album__artist',
        ],
        columns__album_artist__cell__attrs__style__background='blue',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('b79c268d-f88e-4d99-9d82-189920e2393d', this)">▼ Hide result</div>
    <iframe id="b79c268d-f88e-4d99-9d82-189920e2393d" src="doc_includes/cookbook_tables/test_nested_foreign_keys1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _stop-header-render:

How do I stop rendering the header?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.header
.. uses EditTable.header
.. uses HeaderConfig.include

Use `header__template=None` to not render the header, or
`header__include=False` to remove the processing of the header totally. The
difference being that you might want the header object to access
programmatically for some reason, so then it's appropriate to use the
`template=None` method.

.. code-block:: python

    t = Table(
        auto__model=Album,
        header__include=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('b1f5fb53-8fbf-4a2e-a09f-04a819411a50', this)">▼ Hide result</div>
    <iframe id="b1f5fb53-8fbf-4a2e-a09f-04a819411a50" src="doc_includes/cookbook_tables/test_dont_render_header.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    t = Table(
        auto__model=Album,
        header__template=None,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('10b8377b-6a99-4a46-887d-ea279ae2910d', this)">▼ Hide result</div>
    <iframe id="10b8377b-6a99-4a46-887d-ea279ae2910d" src="doc_includes/cookbook_tables/test_dont_render_header1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-as-div:

How do I render a Table as divs?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.tag
.. uses Table.tbody
.. uses EditTable.tbody
.. uses Table.cell
.. uses EditTable.cell
.. uses CellConfig.tag
.. uses RowConfig.tag
.. uses Table.header
.. uses Header.template

You can render a `Table` as a div with the shortcut `Table.div`:

.. code-block:: python

    table = Table.div(
        auto__model=Album,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8248f83a-69b5-45ef-a6c5-82ca699f82c4', this)">▼ Hide result</div>
    <iframe id="8248f83a-69b5-45ef-a6c5-82ca699f82c4" src="doc_includes/cookbook_tables/test_render_table_as_div.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

This shortcut changes the rendering of the entire table from `<table>` to `<div>` by specifying the `tag` configuration, changes the `<tbody>` to a `<div>` via `tbody__tag`, the row via `row__tag` and removes the header with `header__template=None`.

.. table-preprocess_rows:

How do I do custom processing on rows before rendering?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.preprocess_row
.. uses Table.preprocess_rows
.. uses EditTable.preprocess_row
.. uses EditTable.preprocess_rows

Sometimes it's useful to further process the rows before rendering, by fetching more data, doing calculations, etc. If you can use `QuerySet.annotate()`, that's great, but sometimes that's not enough. This is where `preprocess_row` and `preprocess_rows` come in. The first is called on each row, and the second is called for the entire list as a whole.

Note that this is all done *after* pagination.

Modifying row by row:

.. code-block:: python

    def preprocess_album(row, **_):
        row.year += 1000
        return row

    table = Table(
        auto__model=Album,
        preprocess_row=preprocess_album,
    )

Note that `preprocess_row` requires that you return the object. This is because you can return a different object if you'd like.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('411b94d9-6d91-44e6-a1b0-16784599dd19', this)">▼ Hide result</div>
    <iframe id="411b94d9-6d91-44e6-a1b0-16784599dd19" src="doc_includes/cookbook_tables/test_how_do_i_do_custom_processing_on_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Modifying the entire list:

.. code-block:: python

    def preprocess_albums(rows, **_):
        for i, row in enumerate(rows):
            row.index = i
        return rows

    table = Table(
        auto__model=Album,
        preprocess_rows=preprocess_albums,
        columns__index=Column.number(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('86909c81-eaa8-4857-af93-15606015800e', this)">▼ Hide result</div>
    <iframe id="86909c81-eaa8-4857-af93-15606015800e" src="doc_includes/cookbook_tables/test_how_do_i_do_custom_processing_on_rows1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Note that `preprocess_rows` requires that you return the list. That is because you can also return a totally new list if you'd like.

.. table-empty-message:

How do I set an empty message?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.empty_message
.. uses EditTable.empty_message

By default iommi will render an empty table simply as empty:

.. code-block:: python

    table = Table(
        auto__model=Album,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0c490b83-685c-41ad-bc6d-66d70989452e', this)">▼ Hide result</div>
    <iframe id="0c490b83-685c-41ad-bc6d-66d70989452e" src="doc_includes/cookbook_tables/test_how_do_i_set_an_empty_message.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If you want to instead display an explicit message when the table is empty, you use `empty_message`:

.. code-block:: python

    table = Table(
        auto__model=Album,
        empty_message='Destruction of the empty spaces is my one and only crime',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5a58d14a-509c-4281-8452-8568094d8a9c', this)">▼ Hide result</div>
    <iframe id="5a58d14a-509c-4281-8452-8568094d8a9c" src="doc_includes/cookbook_tables/test_how_do_i_set_an_empty_message1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

This setting is probably something you want to set up in your `Style`, and not per table.

.. _complex-layouts-tables:

How do I make complex layouts for table rows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Cells.layout
.. uses Panel._parent_table
.. uses Panel._parent_table_cells

You can have more complex layout using the `panel` system. Set `row__layout` to a
`Panel` and each row's `Cells` is rendered using it (its `layout`). The
`Panel.cell` entries are linked to the matching table column for each row
automatically - iommi tracks the owning table and row in `_parent_table` and
`_parent_table_cells`:

.. code-block:: python

    class AlbumTable(Table):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'artist', 'year']
            row__layout = Panel.div(
                dict(
                    p_album=Panel.row(dict(
                        name=Panel.cell(**{
                            'col__attrs__class': {
                                'fw-bold': True,
                                'text-decoration-underline': True
                            }
                        }),
                        year=Panel.cell(),
                    )),
                    p_artist=Panel.row(dict(
                        p_artist_test=html.em('Artist:'),
                        artist=Panel.cell(),
                    )),
                ),
                **{
                    'attrs__style__border-bottom': '1px solid #6ea8fe',
                }
            )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ea015236-0cce-4864-b144-2e30b796dbe7', this)">▼ Hide result</div>
    <iframe id="ea015236-0cce-4864-b144-2e30b796dbe7" src="doc_includes/cookbook_tables/test_row_layout_with_panels.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`Panel.cell`'s are mapped to their corresponding `Table` columns automatically, and checked. That means that 
if you create a complex layout and forget a cell you will get an error, and vice versa.

The same way you can also use layouts for `EditTable`.

.. _superheader:

How do I group columns under a superheader?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.superheader
.. uses EditTable.superheader
.. uses Column.superheader
.. uses EditColumn.superheader

Set `group` to the same value on adjacent columns and they get a shared header
cell, a "superheader", that spans them. Customize how that superheader renders
via the table's `superheader` namespace (its `attrs` and `template`):

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__group='Details',
        columns__year__group='Details',
        superheader__attrs__class={'text-center': True},
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('cc066fed-693f-4149-a4e0-5d99204df18c', this)">▼ Hide result</div>
    <iframe id="cc066fed-693f-4149-a4e0-5d99204df18c" src="doc_includes/cookbook_tables/test_how_do_i_group_columns_under_a_superheader.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _custom-sort-key:

How do I change what a column sorts by?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.sort_key
.. uses EditColumn.sort_key
.. uses Table.sorter
.. uses EditTable.sorter

By default a column sorts on its `attr`. Set `sort_key` to sort on something
else, like a field across a relationship:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__artist__sort_key='artist__name',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('127d67c3-c6a5-4a35-8845-ef618cd47dda', this)">▼ Hide result</div>
    <iframe id="127d67c3-c6a5-4a35-8845-ef618cd47dda" src="doc_includes/cookbook_tables/test_how_do_i_change_what_a_column_sorts_by.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If you need to change the actual sorting algorithm (for example to sort a table
built from a plain list in a special way), override the table's `sorter`.

.. _data-retrieval-method:

How do I avoid extra queries for a column across a relationship?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.data_retrieval_method
.. uses EditColumn.data_retrieval_method

When a column reads data across a foreign key, iommi can tell the `QuerySet` to
fetch that data efficiently instead of doing one query per row. Set
`data_retrieval_method` to `select` (a SQL join via `select_related`) or
`prefetch` (a second query via `prefetch_related`):

.. code-block:: python

    from iommi.table import DataRetrievalMethods

    table = Table(
        auto__model=Album,
        columns__artist__data_retrieval_method=DataRetrievalMethods.select,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('321c54a1-e322-4884-ab70-ba64d831e4f6', this)">▼ Hide result</div>
    <iframe id="321c54a1-e322-4884-ab70-ba64d831e4f6" src="doc_includes/cookbook_tables/test_how_do_i_avoid_extra_queries_for_a_column.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _column-choices:

How do I limit the choices for a column?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Column.choices
.. uses EditColumn.choices

`Column.choice` takes a `choices` list. The same list is used to limit the
options offered in the column's filter and bulk editing field:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__year=Column.choice(
            choices=[1980, 1981],
            filter__include=True,
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fd4ac872-e5f3-4137-895c-dffa37b96557', this)">▼ Hide result</div>
    <iframe id="fd4ac872-e5f3-4137-895c-dffa37b96557" src="doc_includes/cookbook_tables/test_how_do_i_limit_the_choices_for_a_column.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-model-introspection:

How do I read the model information iommi found?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.model
.. uses EditTable.model
.. uses Column.model
.. uses EditColumn.model
.. uses Column.model_field
.. uses EditColumn.model_field
.. uses Column.model_field_name
.. uses EditColumn.model_field_name

When you build a table with `auto__model`, iommi introspects the model and fills
in `model` on the table and `model_field`/`model_field_name` on each column for
you. Reading these lets you write generic code that adapts to the model. For a
column based on a foreign key, `model` is the *related* model, so you can build a
link to that object's admin page without hard-coding the model name:

.. code-block:: python

    def admin_url(column, value, **_):
        if value is None:
            return None
        meta = column.model._meta
        return f'/admin/{meta.app_label}/{meta.model_name}/{value.pk}/change/'

    table = Table(
        auto__model=Album,
        columns__artist__cell__url=admin_url,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d800ab42-ccc9-41f4-93a7-8e5ef58ce131', this)">▼ Hide result</div>
    <iframe id="d800ab42-ccc9-41f4-93a7-8e5ef58ce131" src="doc_includes/cookbook_tables/test_how_do_i_read_the_model_information_of_a_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-internal-classes:

How do I use custom classes for a table's internal parts?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.cells_class
.. uses EditTable.cells_class
.. uses Table.page_class
.. uses EditTable.page_class
.. uses Table.action_class
.. uses EditTable.action_class
.. uses Table.row_group_class
.. uses EditTable.row_group_class
.. uses Cells.cell_class

Besides `member_class` (see :ref:`custom-member-class`), a `Table` builds several
other objects that you can swap out by setting the matching `*_class`:
`cells_class` for each rendered row, `action_class` for its actions, `page_class`
for when the table is rendered as a standalone page, and `row_group_class` for
grouped rows. Each `Cells` object in turn builds its individual `Cell` objects
from its own `cell_class`:

.. code-block:: python

    from iommi.table import Cells

    class MyCells(Cells):
        pass

    class MyTable(Table):
        class Meta:
            cells_class = MyCells

    table = MyTable(auto__model=Album)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0a401ce6-8d0c-4360-b0e1-8779a151a353', this)">▼ Hide result</div>
    <iframe id="0a401ce6-8d0c-4360-b0e1-8779a151a353" src="doc_includes/cookbook_tables/test_how_do_i_use_custom_classes_for_a_tables_internal_parts.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _actions-below-table:

How do I render the table actions below the table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.actions_below
.. uses EditTable.actions_below
.. uses Table.actions_template
.. uses EditTable.actions_template

By default a table's actions are rendered above the table. Set
`actions_below=True` to render them below it instead. To take full control of
how the actions are laid out, point `actions_template` at your own template:

.. code-block:: python

    table = Table(
        auto__model=Album,
        actions__foo=Action(display_name='Foo', attrs__href='#'),
        actions_below=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('93141810-33d7-492b-bf60-5b63fad84d02', this)">▼ Hide result</div>
    <iframe id="93141810-33d7-492b-bf60-5b63fad84d02" src="doc_includes/cookbook_tables/test_how_do_i_render_the_actions_below_the_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _post-bulk-edit:

How do I run code after a bulk edit, or limit which rows it touches?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.post_bulk_edit
.. uses EditTable.post_bulk_edit
.. uses Table.bulk_filter
.. uses EditTable.bulk_filter
.. uses Table.bulk_exclude
.. uses EditTable.bulk_exclude
.. uses Table.bulk_container
.. uses EditTable.bulk_container

`post_bulk_edit` is a hook called with the `queryset` and `updates` after a bulk
edit has been saved - handy for logging or to keep a denormalized value in sync.
`bulk_filter` and `bulk_exclude` restrict which rows a bulk operation is allowed to
touch, and the whole bulk form is wrapped in a `bulk_container` fragment you can
configure:

.. code-block:: python

    log = []

    def post_bulk_edit(table, queryset, updates, **_):
        log.append(f'Updated {queryset.count()} album(s): {updates}')

    table = Table(
        auto__model=Album,
        columns__year__bulk__include=True,
        post_bulk_edit=post_bulk_edit,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('863a1ac0-b24c-411b-9084-a4783acd4f7a', this)">▼ Hide result</div>
    <iframe id="863a1ac0-b24c-411b-9084-a4783acd4f7a" src="doc_includes/cookbook_tables/test_how_do_i_run_code_after_a_bulk_edit.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-invalid-form-message:

How do I customize the message shown for an invalid filter?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.invalid_form_message
.. uses EditTable.invalid_form_message

When the filter form has invalid input (for example a value that isn't one of the
valid choices), iommi shows a message above the table. Override its text with
`invalid_form_message`:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__artist__filter__include=True,
        invalid_form_message='Your filter is invalid, please try again.',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('af5e4825-6e27-4679-9838-81b7d2ac2ccc', this)">▼ Hide result</div>
    <iframe id="af5e4825-6e27-4679-9838-81b7d2ac2ccc" src="doc_includes/cookbook_tables/test_how_do_i_customize_the_invalid_form_message_of_a_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-tag-wrapper:

How do I wrap just the table tag (e.g. for responsive scrolling)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Table.table_tag_wrapper
.. uses EditTable.table_tag_wrapper

The `<table>` tag is wrapped in a `Fragment` (separate from the actions and
paginator). Configure it with `table_tag_wrapper`, for example to get Bootstrap's
responsive horizontal scrolling around the table only:

.. code-block:: python

    table = Table(
        auto__model=Album,
        table_tag_wrapper__attrs__class={'table-responsive': True},
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8533f851-b266-4444-9aa0-c3755d98fca2', this)">▼ Hide result</div>
    <iframe id="8533f851-b266-4444-9aa0-c3755d98fca2" src="doc_includes/cookbook_tables/test_how_do_i_wrap_the_table_tag.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _table-as-csv:

How do I let the user download a table as CSV?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Table.extra_evaluated
.. uses EditTable.extra_evaluated
.. uses Column.extra_evaluated
.. uses EditColumn.extra_evaluated
.. uses Table.endpoints
.. uses Table.actions

Every table has a `csv` endpoint, which is turned on by giving the table a report
name via `extra_evaluated__report_name`. Then say which columns to include by
giving each one a header name, also via `extra_evaluated__report_name`. Add an
`Action` pointing at the endpoint to get a download link:

.. code-block:: python

    class AlbumTable(Table):
        class Meta:
            extra_evaluated__report_name = 'Albums'
            actions__download = Action(
                attrs__href=lambda table, **_: '?' + table.endpoints.csv.endpoint_path,
            )
            rows = Album.objects.all()

        name = Column(extra_evaluated__report_name='Name')
        artist = Column(extra_evaluated__report_name='Artist')
        year = Column.number(extra_evaluated__report_name='Year')

    albums = AlbumTable().as_view()

The table renders as normal, but hitting the csv endpoint returns a text file in
CSV format:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7dfe9eb2-1de5-4175-9f39-7bb9adadf5d2', this)">▼ Hide result</div>
    <iframe id="7dfe9eb2-1de5-4175-9f39-7bb9adadf5d2" src="doc_includes/cookbook_tables/test_how_do_i_download_a_table_as_csv.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

To include every column without naming each one, set
`extra__report_columns_all=True` on the table. Each column then uses its own name
as the header, and an explicit `extra_evaluated__report_name` on a column still
wins.

To control the CSV dialect, pass kwargs through to `csv.writer` with
`extra_evaluated__csv_writer_kwargs`, e.g.
`extra_evaluated__csv_writer_kwargs={'delimiter': ';'}`.

.. _table-ajax-timeout:

How do I change the ajax timeout or the error shown when a table fails to load?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Filtering, sorting and paginating a table reloads the table body with an ajax
request. If that request doesn't finish within `ajaxTimeout` milliseconds
(default 5000) it is aborted, and an error overlay with a retry button is
shown over the table. The same overlay is shown if the request fails for
any other reason. The overlay has the CSS class `iommi_table_error`, and the
table container gets the class `iommi_table_error_shown` while it's visible.

Both the timeout and the texts are properties on the JavaScript `iommi`
object. Set them in an `iommi.init.start` event listener, which runs before
iommi wires up any tables:

.. code-block:: html

    <script>
        document.addEventListener('iommi.init.start', (event) => {
            const iommi = event.detail.iommi;
            iommi.ajaxTimeout = 30000;  // or null to never time out
            iommi.messages.tableLoadTimeout = gettext('Loading the table took too long and was cancelled.');
            iommi.messages.tableLoadError = gettext('Loading the table failed.');
            iommi.messages.retry = gettext('Retry');
        });
    </script>

A timed out request fails with a `TimeoutError`, so you can also tell it
apart from other failures in an `iommi.error` event listener via
`event.detail.error.name`.





Edit tables
-----------

.. _edit-table-one-to-one:

How do you edit one-to-one fields in an edit table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditColumn.field
.. uses EditColumn.columns
.. uses EditColumn.auto

Include them in `auto__include`. Say you have a profile model for an artist:

Then you can include the artist name field:

.. code-block:: python

    edit_table = EditTable(
        auto__model=Profile,
        auto__include=['artist__name'],
        columns__artist_name__field__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('de73e978-ff7b-481c-807d-b52d65aaa8b5', this)">▼ Hide result</div>
    <iframe id="de73e978-ff7b-481c-807d-b52d65aaa8b5" src="doc_includes/cookbook_edit_tables/test_how_do_you_edit_one_to_one_in_a_table.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-delete-as-checkbox:

How do I change the delete buttons to checkboxes?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Just add `data-iommi-edit-table-delete-with="checkbox"`:

.. code-block:: python

    edit_table = EditTable(
        auto__model=Profile,
        auto__include=['artist__name'],
        columns__artist_name__field__include=True,
        columns__delete=EditColumn.delete(),
        **{
            'attrs__data-iommi-edit-table-delete-with': 'checkbox',
        }
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('31a2a161-638d-4e00-950b-0e10a55cf2cb', this)">▼ Hide result</div>
    <iframe id="31a2a161-638d-4e00-950b-0e10a55cf2cb" src="doc_includes/cookbook_edit_tables/test_how_do_i_change_delete_to_checkboxes.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-include-field-labels:

How do I include labels for fields?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're using `EditTable` and not `EditTable.div`, then by default you get fields rendered without labels,
because the label text is in the table header. But in case you still want to render labels (e.g. as floating labels),
you can just set `extra_evaluated__input_labels_include = True`:

.. code-block:: python

    edit_table = EditTable(
        auto__model=Profile,
        auto__include=['artist__name'],
        columns__artist_name__field__include=True,
        extra_evaluated__input_labels_include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4d9142f1-c2b3-4dfe-ba5f-e7e9f25a5d3a', this)">▼ Hide result</div>
    <iframe id="4d9142f1-c2b3-4dfe-ba5f-e7e9f25a5d3a" src="doc_includes/cookbook_edit_tables/test_how_do_i_include_labels_for_fields.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-reorderable:

How do I let users drag to reorder rows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditTable.reorderable

The easiest way to make a manually reorderable table is to inherit from `iommi.models.Orderable`.
This gives your model a `sort_order` field, a default `order_by` set on the model to sort on that field,
and that field has the `iommi.model_fields.SortOrderField` which is mapped to the correct column type automatically.
If you do this then set `reorderable=True` on an `EditTable` to get drag-and-drop reordering
of the rows. You can also pass a dict of `SortableJS` options instead of `True`:

.. code-block:: python

    edit_table = EditTable(
        auto__model=FavoriteArtist,
        auto__include=['artist__name', 'comment', 'sort_order'],
        columns__comment__field__include=True,
        reorderable=True,
        sortable=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('12791c05-b10c-4b0a-a92f-a253b7d74589', this)">▼ Hide result</div>
    <iframe id="12791c05-b10c-4b0a-a92f-a253b7d74589" src="doc_includes/cookbook_edit_tables/test_how_do_i_let_users_reorder_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-forms:

How do I configure the edit and create forms of an edit table?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditTable.edit_form
.. uses EditTable.create_form

An `EditTable` builds two forms behind the scenes: `edit_form` for the existing
rows and `create_form` for new rows added via "Add row". Both are configured
through the matching namespaces:

.. code-block:: python

    edit_table = EditTable(
        auto__model=Album,
        columns__name__field__include=True,
        columns__year__field__include=True,
        create_form__title='Add an album',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c8f8c942-7ccd-459b-8ee4-59f27509f1e2', this)">▼ Hide result</div>
    <iframe id="c8f8c942-7ccd-459b-8ee4-59f27509f1e2" src="doc_includes/cookbook_edit_tables/test_how_do_i_configure_the_edit_and_create_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-actions:

How do I customize the Save and Add row actions?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditTable.edit_actions

The buttons below an `EditTable` (`save` and `add_row`) live in the `edit_actions` namespace.
You can rename, restyle, hide or add buttons via this namespace. For example, to hide the "Add row"
button so users can only edit existing rows:

.. code-block:: python

    edit_table = EditTable(
        auto__model=Album,
        columns__name__field__include=True,
        edit_actions__add_row__include=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('14d71ebb-e6f2-48e7-8d73-645bb18761f7', this)">▼ Hide result</div>
    <iframe id="14d71ebb-e6f2-48e7-8d73-645bb18761f7" src="doc_includes/cookbook_edit_tables/test_how_do_i_customize_the_edit_table_actions.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-preprocess-create:

How do I set defaults on newly added rows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditTable.preprocess_row_for_create

When a user adds a row, iommi creates a blank instance for it. Use
`preprocess_row_for_create` to fill in defaults on that instance, for example a
foreign key that isn't one of the editable columns:

.. code-block:: python

    def preprocess_row_for_create(row, **_):
        row.artist = black_sabbath
        return row

    edit_table = EditTable(
        auto__model=Album,
        columns__name__field__include=True,
        columns__year__field__include=True,
        preprocess_row_for_create=preprocess_row_for_create,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8b34ba88-8d2a-46f1-a2d3-3585cf156024', this)">▼ Hide result</div>
    <iframe id="8b34ba88-8d2a-46f1-a2d3-3585cf156024" src="doc_includes/cookbook_edit_tables/test_how_do_i_set_defaults_on_newly_added_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _edit-table-parent-form:

How do I nest an edit table inside a form?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses EditTable.parent_form

Declare an `EditTable` as an attribute of a `Form` and it becomes a nested form.
iommi sets `parent_form` on the edit table for you, and saving the outer form
(with the `save_nested_forms` post handler) saves the edit table too:

.. code-block:: python

    from iommi.form import save_nested_forms

    class AlbumsTable(EditTable):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'year']
            columns__name__field__include = True
            columns__year__field__include = True

    class MyForm(Form):
        albums = AlbumsTable()

        class Meta:
            actions__submit__post_handler = save_nested_forms

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('7fb31a17-96af-4132-af75-9f0d6ea365ad', this)">▼ Hide result</div>
    <iframe id="7fb31a17-96af-4132-af75-9f0d6ea365ad" src="doc_includes/cookbook_edit_tables/test_how_do_i_nest_an_edit_table_in_a_form.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





Queries
-------

.. _override-operator:

How do I override what operator is used for a query?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Filter.query_operator_to_q_operator

The member `query_operator_to_q_operator` for `Filter` is used to convert from e.g. `:`
to `icontains`. You can specify another callable here:

.. code-block:: python

    Table(
        auto__model=Track,
        columns__album__filter__query_operator_to_q_operator=lambda op: 'exact',
    )

The above will force the album name to always be looked up with case
sensitive match even if the user types `album<Paranoid` in the
advanced query language. Use this feature with caution!

See also `How do I control what Q is produced?`_

.. _control-q:

How do I control what Q is produced?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Filter.value_to_q

For more advanced customization you can use `value_to_q`. It is a
callable that takes `filter, op, value_string_or_f` and returns a
`Q` object. The default handles `__`, different operators, negation
and special handling of when the user searches for `null`.

.. code-block:: python

    class AlbumTable(Table):
        class Meta:
            auto__model = Album

            query__form__fields__eighties = Field.boolean(
                display_name="the '80s",
            )

            @staticmethod
            def query__filters__eighties__value_to_q(value_string_or_f, **_):
                if value_string_or_f == "1":
                    return Q(year__gte=1980) & Q(year__lte=1989)
                return Q()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('6115b0cf-3206-4eca-974c-cd80b332be91', this)">▼ Hide result</div>
    <iframe id="6115b0cf-3206-4eca-974c-cd80b332be91" src="doc_includes/cookbook_queries/test_how_do_i_control_what_q_is_produced.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Without the filter selected:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4bf91918-f708-436b-99d2-fdfd7086eed6', this)">► Show result</div>
    <iframe id="4bf91918-f708-436b-99d2-fdfd7086eed6" src="doc_includes/cookbook_queries/test_how_do_i_control_what_q_is_produced1.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I control the name used in the advanced query?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.query_name

By default the names of filters are derived from the name you specify or from the model field name.
For deeply nested names, double underscores are replaced with single underscores, and those names
can become a bit unwieldy. You can then override this with `query_name`:

.. code-block:: python

    track_table = Table(
        auto__model=Track,
        auto__include=['name', 'album', 'album__artist__name'],
        columns__album_artist_name__filter=dict(
            include=True,
            query_name='artist',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a1d10c21-cf9b-4c27-afd7-f4ed2e267ae9', this)">▼ Hide result</div>
    <iframe id="a1d10c21-cf9b-4c27-afd7-f4ed2e267ae9" src="doc_includes/cookbook_queries/test_how_do_I_set_the_name_for_a_filter.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I filter on the thing itself?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.attr
.. uses Filter.

Filtering a table on the thing itself is sometimes useful, but can be a bit unintuitive:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        auto__include=['name', 'artist', 'year'],

        query__filters__album=Filter.choice_queryset(
            attr=None,
            choices=Album.objects.all(),
            value_to_q=lambda value_string_or_f, **_: Q(pk=value_string_or_f) if value_string_or_f else Q(),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f4a3e862-d547-43d6-8ad3-f7a4b35e87ba', this)">▼ Hide result</div>
    <iframe id="f4a3e862-d547-43d6-8ad3-f7a4b35e87ba" src="doc_includes/cookbook_queries/test_how_do_I_filter_on_the_thing_itself.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I style the query container?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.attrs
.. uses Query.tag
.. uses Query.form_container

The `Query` component renders a container element that wraps the filter form.
You can configure its tag and attributes directly. The simple (GUI) form itself
is wrapped in `form_container`, which you can configure the same way:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        auto__include=['name', 'artist', 'year'],
        columns__name__filter__include=True,
        query__attrs__style__border='2px solid red',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5f18480c-47f0-433b-8bc3-43e6b626c563', this)">▼ Hide result</div>
    <iframe id="5f18480c-47f0-433b-8bc3-43e6b626c563" src="doc_includes/cookbook_queries/test_how_do_i_style_the_query_container.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _query-filter-rows:

How does a query filter the rows, and how do I post-process them?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.filter
.. uses Query.filters
.. uses Query.rows
.. uses Query.model
.. uses Query.postprocess

A `Query` holds a set of `filters` and the `rows` (and `model`) it filters. When
bound it builds a `Q` from the request, and its `filter` method applies that to
the `rows`. Use `postprocess` to operate on the resulting rows afterwards. A
`Query` is usually created for you by a `Table`, but you can declare and use one
on its own:

.. code-block:: python

    class AlbumQuery(Query):
        name = Filter()
        year = Filter.integer()

    query = AlbumQuery(rows=Album.objects.all())

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('443dea12-b5cf-4b1a-ac66-0bf5f4f5dc88', this)">▼ Hide result</div>
    <iframe id="443dea12-b5cf-4b1a-ac66-0bf5f4f5dc88" src="doc_includes/cookbook_queries/test_how_does_a_query_filter_the_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _query-auto-config:

How do I choose which filters are generated from a model?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses QueryAutoConfig.model
.. uses QueryAutoConfig.exclude
.. uses QueryAutoConfig.default_included
.. uses QueryAutoConfig.rows

Like tables and forms, a `Query` can introspect a model. Pass `auto__model` (or
`auto__rows`) and pick the filters with `auto__include`/`auto__exclude`, or flip
the default with `auto__default_included`:

.. code-block:: python

    query = Query(
        auto__model=Album,
        auto__exclude=['year'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('49489927-cc8b-405a-b062-f7d97e895418', this)">▼ Hide result</div>
    <iframe id="49489927-cc8b-405a-b062-f7d97e895418" src="doc_includes/cookbook_queries/test_how_do_i_choose_which_filters_are_generated.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-gui-field:

How do I configure a filter's GUI field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.field
.. uses Filter.choices
.. uses Filter.search_fields

Each filter has a GUI form field, configured through the filter's `field`
namespace. For choice filters `choices` is the list of options, and
`search_fields` controls which model fields the autocomplete of a
`choice_queryset` filter searches:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__year__filter=dict(
            include=True,
            field__include=True,
        ),
        columns__artist__filter=dict(
            include=True,
            search_fields=['name'],
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0529a2f1-a0c3-49db-b4c1-e6fc43f8bc82', this)">▼ Hide result</div>
    <iframe id="0529a2f1-a0c3-49db-b4c1-e6fc43f8bc82" src="doc_includes/cookbook_queries/test_how_do_i_configure_a_filters_gui_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-matching:

How do I customize how a single filter matches?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.query_operator_for_field
.. uses Filter.unary
.. uses Filter.parse
.. uses Filter.is_valid_filter
.. uses Filter.pk_lookup_to_q
.. uses Filter.model
.. uses Filter.model_field
.. uses Filter.model_field_name

Lower-level hooks change how an individual filter behaves:

- `query_operator_for_field` is the operator used for the simple (GUI) form, e.g. `=` for exact-ish matching or `:` for "contains".
- `parse` parses the user's input string into a value.
- `unary` marks a filter as usable without a value in the advanced query language.
- `is_valid_filter` decides whether a filter is allowed to be part of a query at all.
- `pk_lookup_to_q` controls how a lookup by primary key is turned into a `Q`.

Filters generated from a model also carry `model`, `model_field` and
`model_field_name` (the same introspection you get on columns and fields), so a
custom hook can read the Django field's metadata when it needs to.

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__filter=dict(
            include=True,
            query_operator_for_field=':',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ce0d0154-5b30-4054-845d-29be94946eae', this)">▼ Hide result</div>
    <iframe id="ce0d0154-5b30-4054-845d-29be94946eae" src="doc_includes/cookbook_queries/test_how_do_i_customize_how_a_filter_matches.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _advanced-query:

How do I customize the advanced query language area?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.advanced

A `Query` with filters offers an "advanced" free-text query language alongside
the GUI form, with a link to toggle between them. Configure that toggle (and the
advanced area) through the `advanced` namespace:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__filter__include=True,
        query__advanced__toggle__attrs__class__advanced_toggle=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a60944b3-f820-4602-8ac0-f461239c0023', this)">▼ Hide result</div>
    <iframe id="a60944b3-f820-4602-8ac0-f461239c0023" src="doc_includes/cookbook_queries/test_how_do_i_customize_the_advanced_query_toggle.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-multi-select:

How do I let a filter match several values at once?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.related
.. uses Filter.multi_choice_queryset

A filter on a foreign key (the `related` shortcut, which is what you get by
default for an `album` or `artist` column) normally lets the user pick a
single value in the GUI. Pass `multi_select=True` to turn it into a
multi-select where the chosen values are OR:ed together:

.. code-block:: python

    tracks = Table(
        auto__model=Track,
        auto__include=['name', 'album'],
        columns__album__filter__include=True,
        columns__album__filter__multi_select=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('19276f13-962c-4609-91f1-dd483defd7be', this)">▼ Hide result</div>
    <iframe id="19276f13-962c-4609-91f1-dd483defd7be" src="doc_includes/cookbook_queries/test_how_do_i_let_a_filter_select_multiple_values.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Selecting two albums now produces a query like ``album__pk=1 OR album__pk=2``
instead of forcing the user to choose just one.





.. _cookbook-main-menu:

Main menu
---------



How do I control which menu items are shown for a user?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.include

Using `include` you can control which menu items are shown for a given user. This also controls access, so you can know that your menu and your access control are always in sync.

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
            ),
            artists=M(
                view=artists_view,
                include=lambda user, **_: user.is_staff,
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('11845c71-a337-4a80-a659-81a8d583bbd0', this)">▼ Hide result</div>
    <iframe id="11845c71-a337-4a80-a659-81a8d583bbd0" src="doc_includes/cookbook_main_menu/test_include.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8e08c4fc-ac79-4069-8b67-f0f05f9413ea', this)">▼ Hide result</div>
    <iframe id="8e08c4fc-ac79-4069-8b67-f0f05f9413ea" src="doc_includes/cookbook_main_menu/test_include1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I control the display name of a menu item?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.display_name

By default the display name is derived from the `name` of the `M` object. So given:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(view=albums_view),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2a4e21c5-e580-4893-b696-9e69b7841ba8', this)">▼ Hide result</div>
    <iframe id="2a4e21c5-e580-4893-b696-9e69b7841ba8" src="doc_includes/cookbook_main_menu/test_display_name.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

The `name` would be "albums", and the display name is automatically derived as "Albums". The translation from `name` to `display_name` replaces `_` with space, runs `gettext_lazy()` on the result, and then capitalizes that.

If you want to do something else, pass the `display_name` parameter:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
                display_name=gettext_lazy('Discography'),
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('1f7c0428-a5e8-4ecc-b96f-4236c4209047', this)">▼ Hide result</div>
    <iframe id="1f7c0428-a5e8-4ecc-b96f-4236c4209047" src="doc_includes/cookbook_main_menu/test_display_name1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Note that `display_name` can be a function too.

How do I add sub-paths for a menu item?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.paths

Since the menu system can control access, it is useful to nest path mappings under a specific menu item without showing them in the menu. This is done with the `paths` argument:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
                paths=[
                    path('<album_pk>/edit/', edit_album_view),
                ],
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('32c4697f-b5dd-49ed-80ca-c41ed015700c', this)">► Show result</div>
    <iframe id="32c4697f-b5dd-49ed-80ca-c41ed015700c" src="doc_includes/cookbook_main_menu/test_paths.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I add external links in the menu?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.url
.. uses EXTERNAL

Use the special value `EXTERNAL` for the `view` argument, and use `url` argument:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=EXTERNAL,
                url='https://docs.iommi.rocks',
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('95af1616-4d09-4498-8486-0cc76e9e0e62', this)">▼ Hide result</div>
    <iframe id="95af1616-4d09-4498-8486-0cc76e9e0e62" src="doc_includes/cookbook_main_menu/test_external_links.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Note the icon added by default for an external link. This is configurable via the `icon_formatter` on your `Style`.

How do I nest menu items?
~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.items
.. uses M.open

You can create a menu hierarchy with the `items` argument, which produces expandable sections. iommi will open the menu items that match the current URL by default. You can also force a submenu to be open with the `open` argument:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            things=M(
                view=things_view,
                open=True,  # force open
                items=dict(
                    albums=M(
                        view=albums_view,
                    ),
                    artists=M(
                        view=artists_view,
                    )
                ),
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('768008f9-f457-4da9-b46c-a2c2aea8bc77', this)">▼ Hide result</div>
    <iframe id="768008f9-f457-4da9-b46c-a2c2aea8bc77" src="doc_includes/cookbook_main_menu/test_nesting.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

The `open` argument can be a callable.

How do I put arbitrary html in the menu?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.template

With the `template` argument you can put arbitrary html into menu items:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=EXTERNAL,
                template=Template('''
                <li style="margin-left: 1rem">
                    <span style="display: inline-block; width: 1.5rem; background: red; border-radius: 50%">&nbsp;</span>
                    <span style="display: inline-block; width: 1.5rem; background: orange; border-radius: 50%">&nbsp;</span>
                    <span style="display: inline-block; width: 1.5rem; background: yellow; border-radius: 50%">&nbsp;</span>
                    <span style="display: inline-block; width: 1.5rem; background: green; border-radius: 50%">&nbsp;</span>
                    <span style="display: inline-block; width: 1.5rem; background: blue; border-radius: 50%">&nbsp;</span>
                </li>
                ''')
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f8f7af9b-b572-4da2-994a-362ceb0189fe', this)">▼ Hide result</div>
    <iframe id="f8f7af9b-b572-4da2-994a-362ceb0189fe" src="doc_includes/cookbook_main_menu/test_template.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Note that you want to include the `<li>` tag.

You can also override the base template via your `Style`.

How do I show which specific object I am on in the menu?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.path
.. uses M.url
.. uses M.params

If you have a list of objects and you click into one of them, you might want to show that item in the menu, and potentially also sub-pages for that item. You do that by using iommi path decoders, and mapping everything together with `display_name`, `path`, `params` and `url`:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
                items=dict(
                    album=M(
                        view=album_view,
                        display_name=lambda album, **_: str(album),
                        path='<album_pk>/',
                        params={'album'},
                        url=lambda album, **_: f'/albums/{album.pk}/',
                    ),
                )
            ),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e42630fe-90c3-4741-a9fe-2e27163fefe2', this)">▼ Hide result</div>
    <iframe id="e42630fe-90c3-4741-a9fe-2e27163fefe2" src="doc_includes/cookbook_main_menu/test_drill_down.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I make a data driven dynamic submenu?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.items

There can be cases where you want a dynamic submenu where the items come from the database. To do this, specify `items` as a callable. Note that urls here can't be mapped to paths, as paths need to be known at startup.

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
                items=lambda **_: {
                    f'album_{album.pk}': M(
                        view=EXTERNAL,
                        display_name=str(album),
                        url=album.get_absolute_url(),
                    )
                    for album in Album.objects.all()
                }
            )
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e1a08ea2-5565-4b81-ae5f-4bae6d8fceab', this)">▼ Hide result</div>
    <iframe id="e1a08ea2-5565-4b81-ae5f-4bae6d8fceab" src="doc_includes/cookbook_main_menu/test_dynamic_submenu.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I use the menu for access control and path mapping without rendering into the menu?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses M.render

The access control and path mapping of `M` items is very handy, but sometimes you don't want
to show some URL in the sidebar menu. Use `render` to accomplish this:

.. code-block:: python

    menu = MainMenu(
        items=dict(
            albums=M(
                view=albums_view,
                render=False,
            )
        ),
    )





.. _cookbook-calendar:

Calendar
--------

.. note::

    The `Calendar` component is experimental. The API may change in future versions.

.. _calendar-from-model:

How do I make a calendar from a model?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Calendar.model
.. uses Calendar.rows
.. uses Calendar.year
.. uses Calendar.month
.. uses Calendar.event

Point `auto__model` at a model and tell the calendar which date field to place
events on with `event__attr`. By default the calendar shows the current month;
pass `year` and `month` to show a specific one. Each row of the queryset becomes an
`event`. You can also pass `rows` (or `auto__rows`) directly instead of a model:

.. code-block:: python

    calendar = Calendar(
        auto__model=Album,
        event__attr='published_date',
        event__display_name=lambda event, **_: event.name,
        year=1983,
        month=11,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c46b2f2e-1f20-4843-805d-10ad49baadde', this)">▼ Hide result</div>
    <iframe id="c46b2f2e-1f20-4843-805d-10ad49baadde" src="doc_includes/cookbook_calendar/test_how_do_i_make_a_calendar_from_a_model.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _calendar-cell-styling:

How do I style the calendar's cells?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Calendar.day
.. uses Calendar.day_number
.. uses Calendar.weekday
.. uses Calendar.today
.. uses Calendar.other_month
.. uses Calendar.weekend

Each kind of cell has its own config namespace where you can set `attrs`, a `tag`
and so on: `day` for a day cell, `day_number` for the date number inside it,
`weekday` for the weekday header row, and `today`, `weekend` and `other_month` for
those special days:

.. code-block:: python

    calendar = Calendar(
        auto__model=Album,
        event__attr='published_date',
        year=1983,
        month=11,
        today__attrs__class={'bg-warning': True},
        weekend__attrs__class={'bg-light': True},
        other_month__attrs__style__opacity='0.5',
        weekday__attrs__class={'fw-bold': True},
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('83e8bc88-dc2d-4535-9e60-47f2d304cef3', this)">▼ Hide result</div>
    <iframe id="83e8bc88-dc2d-4535-9e60-47f2d304cef3" src="doc_includes/cookbook_calendar/test_how_do_i_style_the_calendar_cells.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _calendar-navigation:

How do I customize the calendar navigation and actions?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Calendar.navigation
.. uses Calendar.actions

The previous/next month navigation row is configured through `navigation`, and you
can add your own buttons or links via `actions`, just like on a table or form:

.. code-block:: python

    calendar = Calendar(
        auto__model=Album,
        event__attr='published_date',
        year=1983,
        month=11,
        navigation__attrs__class={'bg-light': True},
        actions__today=Action(display_name='Today', attrs__href='?'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('129f2570-613a-42be-9635-bdfa2a2f83c3', this)">▼ Hide result</div>
    <iframe id="129f2570-613a-42be-9635-bdfa2a2f83c3" src="doc_includes/cookbook_calendar/test_how_do_i_customize_calendar_navigation_and_actions.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





.. _style:

Style
=====

iommi has the goal to be easy to integrate into your existing code base,
in addition to being great for developing new products. In order to
accomplish both these goals we need to be able to plug in to whatever
CSS framework you have. By default iommi uses a bootstrap style, but
it also ships with a few other style definitions, and you can define your
own. Styles in iommi do more than just apply CSS classes: you can target
any configuration in iommi with style definitions. This means not just
how things look, but also how they work.

The styles iommi ships with are:

- bootstrap
- bootstrap5
- bulma
- daisyui
- foundation
- semantic_ui
- water
- uikit
- us_web_design_system
- vanilla_css
- django_admin

There are also some internal styles, most notably `base` which is used for
common style data for all styles, and `test` which is used for the tests.

You can change which style your app uses by default by setting
`IOMMI_DEFAULT_STYLE` to the name of your style in the Django settings.

You can also specify style on an individual component via the `iommi_style`
parameter. :ref:`See below <switching_style_for_a_single_part>` for more.

Creating a custom style
-----------------------

When creating a new style there are two steps: define the style by creating a
`Style` object, and register your style with `register_style('my_style', my_style)`.
A good place to do that is in your `AppConfig.ready()`.

When defining a style you can start from an existing style, just start from
`base`, or totally from scratch. Totally from scratch is a lot more work, so
we recommend one of the other options if you can. Styles contain some basic
concepts:

- basing your style on one or more styles (you can base a style on a style object that isn't registered)
- assets
- `base_template`/`content_block`
- targeting a class for styling
- targeting a shortcut for styling

Things you will most likely want to target with a style are:

- tag
- attrs (especially `attrs__class`)
- template (try to avoid this as it can make upgrading iommi versions more brittle)

Add a call to `validate_styles()` in your test suite to get errors for style rules that aren't valid.

Basing on another style
~~~~~~~~~~~~~~~~~~~~~~~

To base a style on one or more styles, you pass the style objects positionally.
The order is significant as later styles can override previous definitions. A
simple example might be `my_style = Style(bootstrap)` which is just a new style
based on bootstrap. Note that style objects don't need to be registered to be
used like this, so you can use this to compose parts that make sense to keep
separate for readability or reuse.

Assets
~~~~~~

You can define assets on either the root (for common assets you want on all
pages, like the CSS framework), or on specific classes or shortcuts to
conditionally include them if that component is present on the page. Assets
from all components and the style root are collected and rendered in the
`<head>` tag.

Defining an asset on the root:

.. code-block:: python

    Style(
        root__assets__my_design_system_css=Asset.css(
            attrs=dict(
                href='https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css',
                integrity='sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh',
                crossorigin='anonymous',
            ),
        ),
    )

There is also a useful shortcut for JavaScript assets: `Asset.js(attrs__src='url')`.
You can put script and css literals (or anything really) there if you want:

.. code-block:: python

    Asset(tag='style', text='body { font-color: blue; }')

Adding an asset on a specific shortcut:

.. code-block:: python

    Style(
        Field__shortcuts__multi_choice__assets__foo=Asset.css(
            attrs__href='https://cdn.jsdelivr.net/npm/select2@4.0.12/dist/css/select2.min.css',
        ),
    )

Adding an asset on a specific class:

.. code-block:: python

    Style(
        Field__assets__foo=Asset.css(
            attrs__href='https://cdn.jsdelivr.net/npm/select2@4.0.12/dist/css/select2.min.css',
        ),
    )

base_template/content_block
~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default iommi uses `iommi/base.html` to render pages. For simple projects
this works very well, but for more complex sites you might need something
more complex. So you can define your base template in a style definition:

.. code-block:: python

    Style(
        base_template='base.html',
    )

If you do this, you will have to make sure to render the iommi assets in the
`<head>` tag:

.. code-block:: html

    {% for asset in assets.values %}
        {{ asset }}
    {% endfor %}

By default iommi will render the iommi page contents into the "content" block,
to override this you can define `content_block`:

.. code-block:: python

    Style(
        base_template='base.html',
        content_block='body',
    )

Targeting a class for styling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can apply style definitions via the class name:

.. code-block:: python

    Style(
        Field__attrs__class__foo=True,
    )

The style system will look at the full class hierarchy when it looks at what
definitions to apply. It will also match on the name of the class only,
the package name doesn't matter.

Targeting a shortcut for styling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can apply style definitions on shortcut names:

.. code-block:: python

    Style(
        MyClass__shortcuts__my_shortcut__attrs__class__foo=True,
    )

The style system will look at the full shortcut hierarchy when it looks at what
definitions to apply. So for example the shortcut `Field.choice_queryset` is
based on `Field.choice` so it will get the style configuration for
`Field.choice` in addition to the definitions for `Field.choice_queryset`.

The shortcut definitions are applied after the class definitions, as they
are more specific.

.. _switching_style_for_a_single_part:

Changing style for a single part
--------------------------------

You can change the style for a single part by passing the `iommi_style`. The
`iommi_style` parameter can either be the name of a registered style, or a `Style`
instance:

.. code-block:: python

    page = Page(
        # Default, will use IOMMI_DEFAULT_STYLE
        parts__foo=Form(
            fields__foo=Field(),
            actions__submit=Action.primary(),
        ),

        # Using my_style
        parts__bar=Form(
            iommi_style='my_style',
            fields__foo=Field(),
            actions__submit=Action.primary(),
        ),

        # Explicit style object
        parts__baz=Form(
            iommi_style=Style(
                bootstrap,  # based on the bootstrap style
                Action__attrs__style__background='red',
            ),
            fields__foo=Field(),
            actions__submit=Action.primary(),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('dfdc7fae-0ad3-42ff-88e4-938e5e90fb5f', this)">▼ Hide result</div>
    <iframe id="dfdc7fae-0ad3-42ff-88e4-938e5e90fb5f" src="doc_includes/styles/test_switching_style_for_a_single_part.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





Path decoding
=============

Path decoding for Django function based views is simple and elegant. Declare your function:

.. code-block:: python

    def album_view(request, album_pk):
        album = get_object_or_404(Album, pk=album_pk)
        ...

Then declare your path mapping:

.. code-block:: python

    urlpatterns = [
        path('<album_pk>/', album_view),
    ]

For class based views it's a little more awkward with `self.kwargs`, but
mostly the same. In iommi we have another approach that we think is more
elegant and faster to develop with:

URLConf and iommi
-----------------

The url parameters, or path components, are available in iommi under the `params` namespace and also as keyword arguments directly. A simple example is:

.. code-block:: python

    class MyPage(Page):
        hello = html.div(
            lambda name, **_: f'Hello {name}',
        )

    urlpatterns = [
        path('<name>/', MyPage().as_view()),
    ]

This simple view will take the `name` path parameter and print it on the page. This is sometimes useful, but it's more common to need some more complex lookup on our parameters, so that leads us to path decoders:

iommi path decoders
-------------------

In iommi we have a powerful and easy to use system for path decoding that also
works smoothly with iommi views. It builds on top of the params feature
described above. Let's look at an example:

Register your models:

.. code-block:: python

    register_path_decoding(
        artist_name=Artist.name,
        artist_pk=Artist,
        album_pk=Album,
    )

Now in your path mapping you can write:

.. code-block:: python

    urlpatterns = [
        path('<artist_name>/<album_pk>/', MyPage().as_view()),
    ]

...and you will get an `Artist` instance as `artist` (also in `params.artist`) and an `Album`
instance in `album`. The name lookup
assumes your name field is called `name` on the model. There's an advanced
registration system for more complex lookups, but this should cover most
usages.


Use iommi decoders on a function based view
-------------------------------------------

You can use the iommi path decoders on a normal FBV too:

.. code-block:: python

    @decode_path
    def my_view(request, artist, album):
        return artist, album

If you want to get any of the raw values before they are decoded you can access them
via `request.iommi_view_params` which has both the undecoded and the decoded parameters.

Advanced path decoders
----------------------

For cases where you want to decode something other than a pk or name you need the advanced path decoders. Here's a simple example:

.. code-block:: python

    register_path_decoding(
        user_pk=User,
        user_username=User.username,
        user_email=User.email,
        track_foo=lambda string, request, decoded_kwargs, kwargs, **_: Track.objects.get(name__iexact=string.strip())
    )

This will allow you to do `<user_pk>`, `<user_username>`, `<user_email>` in your url pattern for the `User` model, and `track_foo` for the `Track` model.

The first example just maps `pk`, `username` and `email` one to one to the model. So for an email lookup it will run `User.objects.get(email=params.email)` to get the `User` object.

The second example is for more complex use cases. As you have access to `request`, `decoded_kwargs` and `kwargs` in addition to the model you can perform path decoding that is not possible with Django path decoders.

Path decoders for access control
--------------------------------

Access control on path decoder level can be very powerful if you have row-level access rules. Let's say that only staff users can edit Black Sabbath albums:

.. code-block:: python

    def album_pk_decoder(string, request, **_):
        album = Album.objects.get(pk=string)
        if album.artist.name == 'Black Sabbath' and not request.user.is_staff:
            raise PermissionError('Only staff can edit Black Sabbath albums')
        return album

.. code-block:: python

    register_path_decoding(album_pk=PathDecoder(decode=album_pk_decoder, name='album'))

The beauty of this approach is that if you do this consistently in your product, all views get decoded objects that are safe to use without further checks.



Access control
==============

The iommi admin only allows access to users with the `is_staff` flag. Other than that iommi doesn't enforce any access control on its own. If you need any you have to implement it yourself for your specific use case. That being said, here are a few ideas:

- Middleware that checks URL of requests coming in, limiting certain paths (or all paths) to logged in users, users belonging to certain groups, etc. This is the easiest to get right as it's in one place and is easy to reason about. It can't handle many common cases, but it can be a good base to stand on.
- Path decoders in iommi can be used for access control if the object being decoded has access semantics. For example `/company/1/` could validate that the user is a member of the company with pk 1.
- You can generalize path decoder logic to call a `has_access` method on the model you decode.
- The `LoginRequiredMiddleware <https://docs.djangoproject.com/en/5.1/ref/middleware/#django.contrib.auth.middleware.LoginRequiredMiddleware>`_ can be used to default URLs to denied, where you have to mark allowed URLs with the `@login_not_required` decorator.



Minimal example for path decoding access control
------------------------------------------------

.. code-block:: python

    class AccessDeniedException(Exception):
        pass

    def has_access_decoder(model):
        def has_access_decoder_inner(string, request, **_):
            obj = model.objects.get(pk=string.strip())
            if not obj.has_access(request.user):
                raise AccessDeniedException()
            return obj
        return has_access_decoder_inner

.. code-block:: python

    register_path_decoding(
        track_pk=has_access_decoder(Track),
    )

.. code-block:: python

    urlpatterns = [
        path('<track_pk>/', Page().as_view()),
    ]





Admin
=====

The powerful abstractions of iommi enable us to build an admin interface
that is automagically created based on your models, while retaining the full
feature set of iommi.

Index page (with configuration to show `Artist`, `Album` and `Track` models):

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0987eb9c-7f3f-4ff8-8095-b654d0d494c9', this)">▼ Hide result</div>
    <iframe id="0987eb9c-7f3f-4ff8-8095-b654d0d494c9" src="doc_includes/admin/test_admin.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Displaying albums:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('54516c93-b33d-428d-bdfb-a1db7c71969e', this)">▼ Hide result</div>
    <iframe id="54516c93-b33d-428d-bdfb-a1db7c71969e" src="doc_includes/admin/test_admin1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Editing an album:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2bc768e4-98b7-43ba-9ff8-4c481d2162a6', this)">▼ Hide result</div>
    <iframe id="2bc768e4-98b7-43ba-9ff8-4c481d2162a6" src="doc_includes/admin/test_admin2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Delete page for an album:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9bbe13b3-14be-4871-aeed-6cb12eb35681', this)">▼ Hide result</div>
    <iframe id="9bbe13b3-14be-4871-aeed-6cb12eb35681" src="doc_includes/admin/test_admin3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Installation
------------

First declare a subclass of `Admin`:

.. code-block:: python

    from iommi.admin import Admin

    class MyAdmin(Admin):
        pass

This is the place you will put global configuration. If you don't need any you
can skip this step. Next plug it into your urls:

.. code-block:: python

    urlpatterns = [
        # ...

        path('iommi-admin/', include(MyAdmin.urls())),
    ]

Now you have the iommi admin GUI for your app!

Customization
-------------

Add a model to the admin
~~~~~~~~~~~~~~~~~~~~~~~~

You can add an app to your admin from your global config like this:

.. code-block:: python

    class MyAdmin(Admin):
        class Meta:
            apps__myapp_mymodel__include = True

This is especially useful for adding config to a third party app that doesn't have built-in iommi admin configuration.

You can also add the config in the app, by creating an `iommi_admin.py` file in your app, and putting the configuration there:

.. code-block:: python

    class Meta:
        apps__myapp_mymodel__include = True

Remove a model from the admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default iommi displays the built in Django `User` and `Group` models. You can override this like:

.. code-block:: python

    class MyAdmin(Admin):
        class Meta:
            apps__auth_user__include = False

This turns off the admin of the `User` table in the `auth` app. Your global config always has priority.

Permissions
~~~~~~~~~~~

By default staff users have access to the admin. You can change this by
overriding `has_permission`:

.. code-block:: python

    from iommi.admin import Admin

    class MyAdmin(Admin):
        @staticmethod
        def has_permission(request, operation, model=None, instance=None):
            # This is the default implementation
            return request.user.is_staff

`operation` is one of `create`, `edit`, `delete`, `list` and `all_models`. The
`model` parameter will be given for create/edit/delete/list, and instance will
be supplied in edit/delete.

HTML attributes
~~~~~~~~~~~~~~~

You can configure attributes in the admin similarly to the rest of iommi, on
the `Meta` class:

.. code-block:: python

    class MyAdmin(Admin):
        class Meta:
            parts__list_docs_album__columns__name__header__attrs__style__background = 'yellow'

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8d102987-5d8d-4dce-89d9-87b4fb9e51f9', this)">▼ Hide result</div>
    <iframe id="8d102987-5d8d-4dce-89d9-87b4fb9e51f9" src="doc_includes/admin/test_html_attributes.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

The easiest way to find the path for configuration is to have
`settings.IOMMI_DEBUG` turned on (by default on if `DEBUG` is on), and use
the pick feature and click on the element. You'll get the path and also
the type so you can click your way to the documentation for that class.

In the example above the `data-iommi-path` would be
`parts__all_models__columns__model_name__cell` and `data-iommi-type` is
:doc:`Cell`. In the docs for `Cell` you can find that cells have `attrs`.

Change grouping of models
~~~~~~~~~~~~~~~~~~~~~~~~~

By default iommi groups models in the admin by the app they belong to. You can override this with the `group` argument:

.. code-block:: python

    class MyAdmin(Admin):
        class Meta:
            apps__docs_album__group = 'The endless search for where you are'

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a6af2ea2-65af-4f42-b62f-546dd4a4b162', this)">▼ Hide result</div>
    <iframe id="a6af2ea2-65af-4f42-b62f-546dd4a4b162" src="doc_includes/admin/test_change_grouping.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





.. _testing:

Testing
=======

iommi ships with a small set of helpers in `iommi.test_helpers` to make it
easy to test your own frontend. The most important of these is `do_post`,
which simulates a user filling out a form and submitting it.

do_post
-------

Testing a form by hand is tedious: a real POST has to include the CSRF token,
the hidden post target, and the current value of every field, not just the
one value you care about. `do_post` takes care of all of that for you.

It renders the form, extracts the default post data, merges the keyword
arguments you pass on top, and binds the form to a matching POST request:

.. code-block:: python

    class AlbumForm(Form):
        name = Field()
        year = Field.integer()

    form = do_post(AlbumForm.create(), name='Bringing It All Back Home', year='1965')

The returned form is already bound to the POST request, so you can assert on
validation and on the parsed values:

.. code-block:: python

    assert form.is_valid()
    assert form.fields.name.value == 'Bringing It All Back Home'
    assert form.fields.year.value == 1965

Note that you need a form with a post target, so remember to use
`.create()`, `.edit()` or `.delete()`.

Key validation
~~~~~~~~~~~~~~~~

By default `do_post` checks that every key you pass actually exists in the
rendered form. This catches typos in your tests so you don't silently assert
against a value that was never posted. If you need to post a key that isn't a
plain field (for example a virtual key for inserting a new row in an
`EditTable`, like ``columns__name__field/-1``), turn the check off with
`do_post_key_validation=False`:

.. code-block:: python

    form = do_post(AlbumForm.create(), do_post_key_validation=False, name='Highway 61 Revisited', year='1965')

Building requests
-----------------

`iommi.test_helpers` also provides helpers for building request objects:

- `req(method, **data)` builds a request from an anonymous user.
- `user_req(method, **data)` builds a request from a normal authenticated user.
- `staff_req(method, **data)` builds a request from an authenticated staff/superuser.

`do_post` uses `req` by default. Pass `request_builder` to submit the form as
a different user, which is handy for testing access control:

.. code-block:: python

    class AlbumForm(Form):
        name = Field()

    form = do_post(AlbumForm.create(), name='Slipping Into Darkness', request_builder=staff_req)

These helpers can also be used on their own to build a request to bind any
iommi component to:

.. code-block:: python

    page = AlbumForm.create().bind(request=user_req('get'))





Production use
--------------

You probably want to define your own `Style` in a production scenario. See
:doc:`How to create a Style <styles>`, and especially the section on how to integrate into
an existing code base.

Just like you have your own custom base class for Django's `Model` to have a
central place to put customization you will want to do the same for the base
classes of iommi. In iommi this is even more important since you will almost
certainly want to add more shortcuts that are specific to your product.

Copy this boilerplate to some place in your code and import these classes
instead of the corresponding ones from iommi:

.. code-block:: python

    import iommi


    class Page(iommi.Page):
        pass


    class Action(iommi.Action):
        pass


    class Field(iommi.Field):
        pass


    class Form(iommi.Form):
        class Meta:
            member_class = Field
            page_class = Page
            action_class = Action


    class Filter(iommi.Filter):
        pass


    class Query(iommi.Query):
        class Meta:
            member_class = Filter
            form_class = Form


    class Column(iommi.Column):
        pass


    class Table(iommi.Table):
        class Meta:
            member_class = Column
            form_class = Form
            query_class = Query
            page_class = Page
            action_class = Action


    class EditColumn(iommi.EditColumn):
        pass


    class EditTable(iommi.EditTable):
        class Meta:
            member_class = EditColumn
            form_class = Form
            query_class = Query
            page_class = Page
            action_class = Action


    class Menu(iommi.Menu):
        pass


    class MenuItem(iommi.MenuItem):
        pass


    class PanelCol(iommi.PanelCol):
        pass


    class Panel(iommi.Panel):
        class Meta:
            col_class = PanelCol

Admin
~~~~~

If you are using the iommi admin you will want to tell it to use your custom classes too:

.. code-block:: python

    import iommi.admin

    class Admin(iommi.admin.Admin):
        class Meta:
            table_class = EditTable
            form_class = Form





Add iommi to a FBV
==================

.. note::

    You probably don't want to do this. It's better to go full iommi.

Let's say we have a simple view to display an album:

.. code-block:: python

    def view_artist(request, artist_name):
        artist = get_object_or_404(Artist, name=artist_name)
        return render(
            request,
            'view_artist.html',
            context={
                'artist': artist,
            },
        )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('12beea47-07bd-4df6-8deb-09f5c2156f7b', this)">▼ Hide result</div>
    <iframe id="12beea47-07bd-4df6-8deb-09f5c2156f7b" src="doc_includes/legacy_fbv/test_legacy_fbv.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There's a table in the template for the tracks but it's all manual written `<table>`, `<tr>`, etc tags and so doesn't have sorting, and it's just a lot of code in that template. It would be nicer to use an iommi table!

Add an iommi table
------------------

First the template is modified to extend `"iommi/base.html"` and wrap the content in `{% block content %}`.

Then we need to create the iommi object, and pass the collected assets to the context:

.. code-block:: python

    def view_artist(request, artist_name):
        artist = get_object_or_404(Artist, name=artist_name)

        albums = Table(
            auto__rows=artist.albums.all(),
        ).bind(request=request)

        return render(
            request,
            'view_artist2.html',
            context={
                'artist': artist,
                'albums': albums,
                'assets': albums.iommi_collected_assets(),
            }
        )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a3b5df7a-f69b-48e8-bbe3-9955a4350aca', this)">▼ Hide result</div>
    <iframe id="a3b5df7a-f69b-48e8-bbe3-9955a4350aca" src="doc_includes/legacy_fbv/test_legacy_fbv_step2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Now in the template we can add `{{ albums }}` to render the table, and we can delete all the old manually written table html.

AJAX dispatch
-------------

There are two problems with this code so far though, and that is that if we add filtering on album it breaks. One of the nice features
of iommi is the automatic ajax endpoints (and by default a select2 widget), but this requires some extra routing, and that we include the
relevant JS assets.

For views that are fully iommi the routing is done for you, but as this is a legacy function based view that we don't want to
rewrite fully right now, we'll have to add the routing boilerplate ourselves:

.. code-block:: python

    def view_artist(request, artist_name):
        artist = get_object_or_404(Artist, name=artist_name)

        tracks = Table(
            auto__rows=Track.objects.filter(album__artist=artist),
            columns__album__filter__include=True,
        ).bind(request=request)

        dispatch = tracks.perform_dispatch()
        if dispatch is not None:
            return dispatch

        return render(
            request,
            'view_artist.html',
            context={
                'artist': artist,
                'tracks': tracks,
                'assets': tracks.iommi_collected_assets(),
            }
        )

Multiple iommi components
-------------------------

You should only create one top level iommi component in order to get the automatic namespacing for free. So if you wanted to add two tables, you should wrap them in a `Page`:

.. code-block:: python

    def view_artist(request, artist_name):
        artist = get_object_or_404(Artist, name=artist_name)

        class MyPage(Page):
            albums = Table(auto__rows=artist.albums.all())
            tracks = Table(
                auto__rows=Track.objects.filter(album__artist=artist),
                columns__album__filter__include=True,
            )
        page = MyPage().bind(request=request)

        dispatch = page.perform_dispatch()
        if dispatch is not None:
            return dispatch

        return render(
            request,
            'view_artist3.html',
            context={
                'artist': artist,
                'tracks': page.parts.tracks,
                'albums': page.parts.albums,
                'assets': page.iommi_collected_assets(),
            }
        )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a1d90573-034a-4a6a-8b9a-f2b7173b7ae7', this)">▼ Hide result</div>
    <iframe id="a1d90573-034a-4a6a-8b9a-f2b7173b7ae7" src="doc_includes/legacy_fbv/test_legacy_fbv_step4.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Using iommi's base template with a FBV
--------------------------------------

For existing FBVs, you can get the iommi `MainMenu` and the base style
assets by simply extending `iommi/base.html`:

.. code-block:: python

    def view_artist(request, artist_name):
        artist = get_object_or_404(Artist, name=artist_name)
        return render(
            request,
            'view_artist4.html',
            context={
                'artist': artist,
            }
        )

.. literalinclude:: templates/view_artist4.html
    :language: jinja

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('dbfb50e8-fc73-4130-bd72-a06b0dcd2328', this)">▼ Hide result</div>
    <iframe id="dbfb50e8-fc73-4130-bd72-a06b0dcd2328" src="doc_includes/legacy_fbv/test_legacy_fbv_with_main_menu_and_basic_html.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





Porting
-------

Existing function based views often have an initial part building a set of values from the view parameters that then is passed on as a context to the template rendering.

When refactoring this to the more iommi idiomatic style of calculating values in callbacks, it can sometimes be helpful to not have to move everything at once.

Let's look at an example to make this more concrete:

.. code-block:: python

    def some_function(a, b):
        return a + b

    def legacy_view(request, a, b):
        context = dict(a=a, b=b, c=some_function(a, b))
        return HttpResponse(Template('{{a}} + {{b}} = {{c}}').render(RequestContext(request, context)))

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('49040099-ba9d-4a49-a8ce-106779298fec', this)">▼ Hide result</div>
    <iframe id="49040099-ba9d-4a49-a8ce-106779298fec" src="doc_includes/cookbook_porting/test_existing_views.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

There is a configurable callback, `extra_params`, to provide extra parameters given, on top of the parameters already provided by Django and the iommi path machinery:

.. code-block:: python

    class IommiPage(Page):
        class Meta:
            @staticmethod
            def extra_params(request, a, b):
                return dict(
                    c=some_function(a, b),
                )

        content = Template('{{ params.a }} + {{ params.b }} = {{ params.c }}')

    iommi_view = IommiPage().as_view()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2bee73e4-9a2f-4f13-8665-8d7b92086e06', this)">▼ Hide result</div>
    <iframe id="2bee73e4-9a2f-4f13-8665-8d7b92086e06" src="doc_includes/cookbook_porting/test_existing_views1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



API Reference
=============

Classes
-------

.. toctree::
   :maxdepth: 1

   Action
   Asset
   Attrs
   Calendar
   Cell
   Cells
   Column
   ColumnHeader
   Container
   EditColumn
   EditTable
   Endpoint
   Field
   Filter
   Form
   FormAutoConfig
   Fragment
   Header
   HeaderConfig
   M
   MainMenu
   Members
   Menu
   MenuItem
   Page
   Panel
   PanelCol
   Part
   Query
   QueryAutoConfig
   Style
   Table
   TableAutoConfig
   Traversable

Functions
---------

.. toctree::
   :maxdepth: 1

   functions

Middleware
----------

.. toctree::
   :maxdepth: 1

   middleware




Action
======

Base class: :doc:`Fragment`

The `Action` class describes buttons and links.

Examples:

.. code-block:: python

    # Link
    example=Action(attrs__href='http://example.com'),

    # Link with icon
    edit=Action.icon('pencil-square', attrs__href="edit/"),

    # Button
    button=Action.button(display_name='Button title!'),

    # A submit button
    submit=Action.submit(display_name='Do this'),

    # The primary submit button on a form.
    primary=Action.primary(),

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4edced76-5538-4dee-92bd-397c05c30bec', this)">▼ Hide result</div>
    <iframe id="4edced76-5538-4dee-92bd-397c05c30bec" src="doc_includes/Action/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Notice that because forms
with a single primary submit button are so common, iommi assumes
that if you have an action called submit and do NOT explicitly
specify the action that it is a primary action. This is only
done for the action called `submit`, inside the Form's actions
`Namespace`.

For that reason this works:

.. code-block:: python

    class MyForm(Form):
        class Meta:
            @staticmethod
            def actions__submit__post_handler(form, **_):
                if not form.is_valid():
                    return

                ...

and is roughly equivalent to

.. code-block:: python

    def on_submit(form, **_):
        if not form.is_valid():
            return

    class MyOtherForm(Form):
        class Meta:
            actions__submit = Action.primary(post_handler=on_submit)

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`fragment-children`


`display_name`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `lambda action, **_: capitalize(action._name).replace('_', ' ')`
    See :ref:`name <name>`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`action-group`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`post_handler`
^^^^^^^^^^^^^^

Type: `Callable | None`


Cookbook:
    :ref:`nested-forms`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default: `a`
    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Shortcuts
---------

`Action.button`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `button`

`Action.delete`
^^^^^^^^^^^^^^^

Parent: Action.submit_

`Action.icon`
^^^^^^^^^^^^^

Defaults
++++++++

* `extra__icon_attrs__class`
    * `Namespace()`
* `extra__icon_attrs__style`
    * `Namespace()`

`Action.primary`
^^^^^^^^^^^^^^^^

Parent: Action.submit_

`Action.submit`
^^^^^^^^^^^^^^^

Parent: Action.button_

Defaults
++++++++

* `attrs__accesskey`
    * `s`
* `attrs__name`
    * `lambda action, **_: action.own_target_marker()`
* `display_name`
    * `Submit`

Methods
-------

`is_target`
^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`own_target_marker`
^^^^^^^^^^^^^^^^^^^





Asset
=====

Base class: :doc:`Fragment`

Class that describes an asset in iommi. Assets are meant to be the elements that you refer
to in the HEAD of your document such as links to scripts, style sheets as well as
inline scripts or css. But if necessary you can specify an arbitrary django template.

Every :doc:`Part` can include the assets it needs. Similarly :doc:`Style` can include assets.
When a part is rendered all assets are included in the head of the document.

Because assets have names (:doc:`Everything has a name <philosophy>`), assets with the same name will overwrite
each other, resulting in only one asset with a given name being rendered.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`custom-assets`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`in_body`
^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`custom-assets`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Shortcuts
---------

`Asset.css`
^^^^^^^^^^^

To use this shortcut, pass `attrs__href='/my_url_to_the.css'`

Examples:

.. code-block:: python

    Asset.css(
        attrs__href='https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css',
        attrs__integrity='sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh',
        attrs__crossorigin='anonymous',
    )

    Asset.css('p { font-size: 18pt; }')

Defaults
++++++++

* `tag`
    * `link`
* `attrs__rel`
    * `stylesheet`

`Asset.js`
^^^^^^^^^^

To use this shortcut, pass `attrs__src='/my_url_to_the.js'`

Examples:

.. code-block:: python

    Asset.js(
        attrs__src='https://cdn.jsdelivr.net/npm/select2@4.0.12/dist/js/select2.min.js',
    )

    Asset.js('window.foo = bar')

Defaults
++++++++

* `tag`
    * `script`





Attrs
=====

Base class: `Namespace`

The `attrs` namespace on `Field`, `Form`, `Header`, `Cell` and more is used to customize HTML attributes.

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__artist__attrs__foo='bar',
        fields__name__attrs__class__bar=True,
        fields__name__attrs__style__baz='qwe',
    )

or more succinctly:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__artist__attrs__foo='bar',
        fields__name__attrs=dict(
            class__bar=True,
            style__baz='qwe',
        )
    )

The thing to remember is that the basic namespace is a dict with key value
pairs that gets projected out into the HTML, but there are two special cases
for `style` and `class`. The example above will result in the following
attributes on the field tag:

.. code-block:: html

   <div foo="bar" class="bar" style="baz: qwe">

The values in these dicts can be callables:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__attrs__class__bar=
            lambda request, **_: request.user.is_staff,
    )

Constructor arguments
+++++++++++++++++++++

* `_parent`
* `attrs`





Calendar
========

Base class: :doc:`Part`

A calendar component that renders a month-grid calendar.

.. note::

    This component is experimental. The API may change in future versions.

Example:

.. code-block:: python

    calendar = Calendar(
        auto__model=Album,
        event__attr='published_date',
        event__display_name=lambda event, **_: format_html(
            '<img src="/_static/album_art/{}/{}.jpg" width="30" height="30" title="{}">',
            event.artist,
             event.name,
             event.name
        ),
        event__tag=None,
        year=1983,
        month=8,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e31dbe06-f2cb-4331-8613-849605ff3111', this)">▼ Hide result</div>
    <iframe id="e31dbe06-f2cb-4331-8613-849605ff3111" src="doc_includes/Calendar/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Refinable members
-----------------


`actions`
^^^^^^^^^

Type: `dict[str, Action]`


Cookbook:
    :ref:`calendar-navigation`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`auto`
^^^^^^

Type: `CalendarAutoConfig`

    See :ref:`auto <auto>`


`day`
^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`day_number`
^^^^^^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`event`
^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-from-model`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`h_tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model]`


Cookbook:
    :ref:`calendar-from-model`


`month`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int`


Cookbook:
    :ref:`calendar-from-model`


`navigation`
^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`calendar-navigation`


`other_month`
^^^^^^^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`rows`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`calendar-from-model`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `table`
    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/calendar/calendar.html`
    See :ref:`template <template>`


`title`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | None`

    See :ref:`title <title>`


`today`
^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`weekday`
^^^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`weekend`
^^^^^^^^^

Type: `CalendarCellConfig`


Cookbook:
    :ref:`calendar-cell-styling`


`year`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int`


Cookbook:
    :ref:`calendar-from-model`


Methods
-------

`as_view`
^^^^^^^^^

`days_for_month`
^^^^^^^^^^^^^^^^


Generate CalendarDay instances for each day in the calendar grid.


`get_first_month_with_data`
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Return (year, month) of the earliest month that has data, or None.


`get_first_with_data_url`
^^^^^^^^^^^^^^^^^^^^^^^^^

`get_last_month_with_data`
^^^^^^^^^^^^^^^^^^^^^^^^^^


Return (year, month) of the latest month that has data, or None.


`get_last_with_data_url`
^^^^^^^^^^^^^^^^^^^^^^^^

`get_month_name`
^^^^^^^^^^^^^^^^

`get_next_month`
^^^^^^^^^^^^^^^^

`get_next_month_with_data`
^^^^^^^^^^^^^^^^^^^^^^^^^^


Return (year, month) of the closest later month that has data, or None.


`get_next_url`
^^^^^^^^^^^^^^

`get_next_with_data_url`
^^^^^^^^^^^^^^^^^^^^^^^^

`get_prev_month`
^^^^^^^^^^^^^^^^

`get_prev_month_with_data`
^^^^^^^^^^^^^^^^^^^^^^^^^^


Return (year, month) of the closest earlier month that has data, or None.


`get_prev_url`
^^^^^^^^^^^^^^

`get_prev_with_data_url`
^^^^^^^^^^^^^^^^^^^^^^^^

`get_today_url`
^^^^^^^^^^^^^^^

`get_weekday_names`
^^^^^^^^^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`weeks_for_month`
^^^^^^^^^^^^^^^^^


Generate weeks (lists of 7 CalendarDay instances) for the calendar grid.





Cell
====

Base class: `CellConfig`

Constructor arguments
+++++++++++++++++++++

* `cells`
* `column`
* `kwargs`

Methods
-------

`get_context`
^^^^^^^^^^^^^

`get_request`
^^^^^^^^^^^^^

`iommi_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

`render_cell_contents`
^^^^^^^^^^^^^^^^^^^^^^

`render_formatted`
^^^^^^^^^^^^^^^^^^





Cells
=====

Base class: :doc:`Traversable`

Internal class used in row rendering.

You can access the current row via `.row` and the current row index via `.row_index`.

Refinable members
-----------------


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`cell_class`
^^^^^^^^^^^^

Type: `type[Cell]`


Cookbook:
    :ref:`table-internal-classes`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`layout`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Panel | None`


Cookbook:
    :ref:`complex-layouts-tables`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Methods
-------

`column_count`
^^^^^^^^^^^^^^

`get_table`
^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`render`
^^^^^^^^





Column
======

Base class: :doc:`Part`

Class that describes a column, i.e. the text of the header, how to get and display the data in the cell, etc.

See :doc:`Table` for more complete examples.

Parameters with the prefix `filter__` will be passed along downstream to the `Filter` instance if applicable. This can be used to tweak the filtering of a column.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set the order of columns, see the `howto on ordering <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-reorder-columns>`_ for an example.

Type: `int | str`

    See :ref:`after <after>`


Cookbook:
    :ref:`reorder-columns`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attr`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What attribute to use, defaults to same as name. Follows django conventions to access properties of properties, so `foo__bar` is equivalent to the python code `foo.bar`. This parameter is based on the name of the Column if you use the declarative style of creating tables.

Type: `str`

    See :ref:`attr <attr>`


Cookbook:
    :ref:`fk-related-data-access`

    :ref:`attr-name-diff`


`auto_rowspan`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

enable automatic rowspan for this column. To join two cells with rowspan, just set this `auto_rowspan` to `True` and make those two cells output the same text and we'll handle the rest.

Type: `bool`

Default: `False`

Cookbook:
    :ref:`rowspan`


`bulk`
^^^^^^

Namespace to configure bulk actions. See `howto on bulk editing <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-enable-bulk-editing>`_ for an example and more information.

Type: `Namespace`


Cookbook:
    :ref:`bulk-edit`


`cell`
^^^^^^

Customize the cell, see `howto on rendering <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-customize-the-rendering-of-a-cell>`_ and `howto on links <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-make-a-link-in-a-cell>`_

Type: `Namespace`


Cookbook:
    :ref:`cell-link`

    :ref:`column-computed-data`

    :ref:`customize-table-cell-render`

    :ref:`attr-name-diff`

    :ref:`nested-fk`

    :ref:`row-numbers`


`choices`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Iterable`


Cookbook:
    :ref:`column-choices`


`config_from_model`
^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


`data_retrieval_method`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default: `DataRetrievalMethods.attribute_access`

Cookbook:
    :ref:`data-retrieval-method`


`display_name`
^^^^^^^^^^^^^^

the text of the header for this column. By default this is based on the `_name` so normally you won't need to specify it.

    See :ref:`name <name>`


Cookbook:
    :ref:`header-title`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


Cookbook:
    :ref:`table-as-csv`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`filter`
^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`filter-column`

    :ref:`freetext-column`


`group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

string describing the group of the header. If this parameter is used the header of the table now has two rows. Consecutive identical groups on the first level of the header are joined in a nice way.

Type: `str | None`


Cookbook:
    :ref:`group-columns`


`header`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`customize-header`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to hide the column

Type: `bool`

    See :ref:`include <include>`


Cookbook:
    :ref:`reverse-m2m`

    :ref:`show-columns`

    :ref:`reverse-fk-table`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`table-model-introspection`


`model_field`
^^^^^^^^^^^^^


Cookbook:
    :ref:`table-model-introspection`


`model_field_name`
^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-model-introspection`


`render_column`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If set to `False` the column won't be rendered in the table, but still be available in `table.columns`. This can be useful if you want some other feature from a column like filtering.

Type: `bool`

Default: `True`

Cookbook:
    :ref:`show-columns`


`row_group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`group-rows`


`sort_default_desc`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set to `True` to make table sort link to sort descending first.

Type: `bool`

Default: `False`

Cookbook:
    :ref:`sort-direction`


`sort_key`
^^^^^^^^^^

string denoting what value to use as sort key when this column is selected for sorting. (Or callable when rendering a table from list.)


Cookbook:
    :ref:`custom-sort-key`


`sortable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to disable sorting on this column

Type: `bool`

Default: `iommi.table.default_sortable`

Cookbook:
    :ref:`table-sorting`


`superheader`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`superheader`


Shortcuts
---------

`Column.boolean`
^^^^^^^^^^^^^^^^

Shortcut to render booleans as a check mark if true or blank if false.

.. code-block:: python

    table = Table(
        columns__name=Column(),
        columns__boolean=Column.boolean(),
        rows=[
            Struct(name='true!', boolean=True),
            Struct(name='false!', boolean=False),
        ]
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9db1cfc8-7551-4472-9a9b-62c988e15445', this)">▼ Hide result</div>
    <iframe id="9db1cfc8-7551-4472-9a9b-62c988e15445" src="doc_includes/Column/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Defaults
++++++++

* `filter__call_target__attribute`
    * `boolean`
* `filter__field__call_target__attribute`
    * `boolean_tristate`
* `bulk__call_target__attribute`
    * `boolean`
* `cell__format`
    * `lambda value, **_: mark_safe(f'<span title="{gettext_lazy("Yes")}">&#10004;</span>') if value else ''`

`Column.boolean_tristate`
^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `boolean_tristate` for the filter.



Parent: Column.boolean_

Defaults
++++++++

* `filter__call_target__attribute`
    * `boolean_tristate`

`Column.choice`
^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form.



Defaults
++++++++

* `bulk__call_target__attribute`
    * `choice`
* `bulk__choices`
    * `iommi.table.get_choices_from_column`
* `filter__call_target__attribute`
    * `choice`
* `filter__choices`
    * `iommi.table.get_choices_from_column`

`Column.choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the choice queryset case.



Parent: Column.choice_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `choice_queryset`
* `filter__call_target__attribute`
    * `choice_queryset`

`Column.date`
^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `date`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `date`

`Column.datetime`
^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `datetime`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `datetime`

`Column.decimal`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `decimal`
* `filter__call_target__attribute`
    * `decimal`

`Column.delete`
^^^^^^^^^^^^^^^

Shortcut for creating a clickable delete icon. The URL defaults to `your_object.get_absolute_url() + 'delete/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__delete=Column.delete(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('765d94ef-33b2-4550-8c95-8288ea5cf49c', this)">▼ Hide result</div>
    <iframe id="765d94ef-33b2-4550-8c95-8288ea5cf49c" src="doc_includes/Column/test_base1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: Column.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'delete/'`
* `display_name`
    * `Delete`

`Column.download`
^^^^^^^^^^^^^^^^^

Shortcut for creating a clickable download icon. The URL defaults to `your_object.get_absolute_url() + 'download/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__download=Column.download(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('538e2fc1-b2b2-4054-ae4e-00c645780c44', this)">▼ Hide result</div>
    <iframe id="538e2fc1-b2b2-4054-ae4e-00c645780c44" src="doc_includes/Column/test_base2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: Column.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'download/'`
* `cell__value`
    * `lambda row, **_: getattr(row, 'pk', False)`
* `display_name`
    * `Download`

`Column.duration`
^^^^^^^^^^^^^^^^^

Parent: Column.text_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `duration`
* `filter__call_target__attribute`
    * `duration`

`Column.edit`
^^^^^^^^^^^^^

Shortcut for creating a clickable edit icon. The URL defaults to `your_object.get_absolute_url() + 'edit/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__edit=Column.edit(after=0),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('0fb77714-8497-4954-9d1a-447d80d43a6d', this)">▼ Hide result</div>
    <iframe id="0fb77714-8497-4954-9d1a-447d80d43a6d" src="doc_includes/Column/test_base3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: Column.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'edit/'`
* `display_name`
    * `Edit`

`Column.email`
^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `email`
* `bulk__call_target__attribute`
    * `email`

`Column.file`
^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `file`
* `filter__call_target__attribute`
    * `file`
* `cell__format`
    * `lambda value, **_: str(value)`

`Column.float`
^^^^^^^^^^^^^^

Parent: Column.number_

Defaults
++++++++

* `filter__call_target__attribute`
    * `float`
* `bulk__call_target__attribute`
    * `float`

`Column.foreign_key`
^^^^^^^^^^^^^^^^^^^^

`Column.foreign_key_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `foreign_key_reverse`
* `filter__call_target__attribute`
    * `foreign_key_reverse`
* `cell__format`
    * `lambda value, **_: ', '.join(['%s' % x for x in value.all()])`
* `data_retrieval_method`
    * `DataRetrievalMethods.prefetch`
* `sortable`
    * `False`
* `extra__django_related_field`
    * `True`
* `display_name`
    * `lambda column, **_: capitalize(column.model_field.remote_field.model._meta.verbose_name_plural)`

`Column.icon`
^^^^^^^^^^^^^

Shortcut to create font awesome-style icons.



Parameters
++++++++++

* `extra__icon`
    * `the name of the icon`

Defaults
++++++++

* `display_name`
    * `""`
* `cell__value`
    * `lambda table, **_: True`
* `cell__format`
    * `iommi.table.default_icon__cell__format`
* `attr`
    * `None`

`Column.integer`
^^^^^^^^^^^^^^^^

Parent: Column.number_

Defaults
++++++++

* `filter__call_target__attribute`
    * `integer`
* `bulk__call_target__attribute`
    * `integer`

`Column.link`
^^^^^^^^^^^^^

Shortcut for creating a cell that is a link. The URL is the result of calling `get_absolute_url()` on the object.




Cookbook:
    :ref:`custom-actions`

`Column.many_to_many`
^^^^^^^^^^^^^^^^^^^^^

Parent: Column.related_multiple_

`Column.many_to_many_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `many_to_many_reverse`
* `filter__call_target__attribute`
    * `many_to_many_reverse`

`Column.multi_choice`
^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the multi choice case.



Parent: Column.choice_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `multi_choice`
* `filter__call_target__attribute`
    * `multi_choice`

`Column.multi_choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the multi choice queryset case.



Parent: Column.choice_queryset_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `multi_choice_queryset`
* `filter__call_target__attribute`
    * `multi_choice_queryset`

`Column.number`
^^^^^^^^^^^^^^^

`Column.related`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `related`
* `filter__call_target__attribute`
    * `related`
* `data_retrieval_method`
    * `DataRetrievalMethods.select`
* `sort_key`
    * `iommi.table.foreign_key__sort_key`
* `choices`
    * `iommi.table.related__choices`

`Column.related_multiple`
^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Column.multi_choice_queryset_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `many_to_many`
* `filter__call_target__attribute`
    * `many_to_many`
* `cell__format`
    * `lambda value, **_: ', '.join(['%s' % x for x in value.all()])`
* `data_retrieval_method`
    * `DataRetrievalMethods.prefetch`
* `sortable`
    * `False`
* `extra__django_related_field`
    * `True`
* `display_name`
    * `lambda column, **_: capitalize(column.model_field.remote_field.model._meta.verbose_name_plural)`
* `choices`
    * `iommi.table.related__choices`

`Column.run`
^^^^^^^^^^^^

Shortcut for creating a clickable run icon. The URL defaults to `your_object.get_absolute_url() + 'run/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__run=Column.run(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('60eb33ac-3199-417b-b91d-47ec06cfdd78', this)">▼ Hide result</div>
    <iframe id="60eb33ac-3199-417b-b91d-47ec06cfdd78" src="doc_includes/Column/test_base4.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: Column.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'run/'`
* `display_name`
    * `Run`

`Column.select`
^^^^^^^^^^^^^^^

Shortcut for a column of checkboxes to select rows. This is useful for implementing bulk operations.

By default tables have a column named `select` that is used for this purpose. It is shown
automatically when bulk editing or a bulk action is enabled, and is otherwise hidden. You can
force it on (or off) by setting `columns__select__include`. See the example below.

To implement a custom post handler that operates on the selected rows, do

.. code-block:: python

    def my_handler(table):
        rows = table.selection()
        # rows will either be a queryset, or a list of elements
        # matching the type of rows of the table
        ...

    table = Table(
        auto__model=Album,
        bulk__actions__submit=Action.submit(post_handler=my_handler)
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5a61ed56-0772-4b50-9820-d86bedff2abd', this)">▼ Hide result</div>
    <iframe id="5a61ed56-0772-4b50-9820-d86bedff2abd" src="doc_includes/Column/test_base5.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parameters
++++++++++

* `extra__checkbox_name`
    * `the name of the checkbox. Default is `"pk"`, resulting in checkboxes like `"pk_1234"`.`
* `extra__checked`
    * `callable to specify if the checkbox should be checked initially. Defaults to `False`.`

Defaults
++++++++

* `header__template`
    * `iommi/table/select_column_header.html`
* `sortable`
    * `False`
* `filter__include`
    * `False`
* `filter__is_valid_filter`
    * `lambda **_: (True, '')`
* `filter__field__include`
    * `False`
* `bulk__include`
    * `False`
* `attr`
    * `None`
* `cell__value`
    * `lambda table, cells, row, **_: (       row.pk       if isinstance(table.rows, QuerySet)       # row_index is the visible row number       # See selection() for the code that does the lookup       else cells.row_index     )`
* `cell__format`
    * `lambda column, row, value, **kwargs: format_html(       # language=HTML       '<input type="checkbox" class="checkbox" name="{checkbox_name}_{row_id}" {checked_str} />',       checkbox_name=column.extra.checkbox_name,       row_id=value,       checked_str=(         'checked'         if evaluate_strict(column.extra.checked, column=column, row=row, value=value, **kwargs)         else ''       ),     )`
* `extra__checkbox_name`
    * `pk`
* `extra__checked`
    * `lambda **_: False`
* `extra__icon`
    * `fa fa-check-square-o`

`Column.substring`
^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__query_operator_for_field`
    * `:`

`Column.text`
^^^^^^^^^^^^^

This is an explicit synonym for `Column()`.



Defaults
++++++++

* `bulk__call_target__attribute`
    * `text`
* `filter__call_target__attribute`
    * `text`

`Column.textarea`
^^^^^^^^^^^^^^^^^

Parent: Column.text_

`Column.time`
^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `time`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `time`

Methods
-------

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

Class methods
-------------

`checkboxes`
^^^^^^^^^^^^

`from_model`
^^^^^^^^^^^^



Create a `Column` from a Django model field.

When used declaratively inside a `Table`, you normally don't need to pass anything:
the model is taken from the containing table and the model field name from the column's
own name. This works because resolution is deferred until the table is bound, by which
point both are known.

.. code-block:: python

    class AlbumTable(Table):
        name = Column.from_model()

Pass `attr` (using `__` to drill down) to read a field from a related model:

.. code-block:: python

    class AlbumTable(Table):
        artist_name = Column.from_model(attr='artist__name')

The explicit `model`, `model_field_name` and `model_field` parameters are still
accepted for the rare cases where the field can't be inferred from context (e.g. when
not declared on a table), but are no longer required.





ColumnHeader
============

Internal class implementing a column header. For configuration options
read the docs for :doc:`HeaderConfig`.

Constructor arguments
+++++++++++++++++++++

* `display_name`
* `attrs`
* `template`
* `table`
* `url`
* `column`
* `number_of_columns_in_group`
* `index_in_group`





Container
=========

Base class: :doc:`Fragment`

The main container for iommi. This class is useful when you want to apply styling or change the tag of what iommi produces for its content inside your body tag.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`fragment-children`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`





EditColumn
==========

Base class: :doc:`Column`

The column class for `EditTable`.

Parameters with the prefix `filter__` will be passed along downstream to the `Filter` instance if applicable. This can be used to tweak the filtering of a column.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set the order of columns, see the `howto on ordering <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-reorder-columns>`_ for an example.

Type: `int | str`

    See :ref:`after <after>`


Cookbook:
    :ref:`reorder-columns`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attr`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What attribute to use, defaults to same as name. Follows django conventions to access properties of properties, so `foo__bar` is equivalent to the python code `foo.bar`. This parameter is based on the name of the Column if you use the declarative style of creating tables.

Type: `str`

    See :ref:`attr <attr>`


Cookbook:
    :ref:`fk-related-data-access`

    :ref:`attr-name-diff`


`auto_rowspan`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

enable automatic rowspan for this column. To join two cells with rowspan, just set this `auto_rowspan` to `True` and make those two cells output the same text and we'll handle the rest.

Type: `bool`

Default: `False`

Cookbook:
    :ref:`rowspan`


`bulk`
^^^^^^

Namespace to configure bulk actions. See `howto on bulk editing <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-enable-bulk-editing>`_ for an example and more information.

Type: `Namespace`


Cookbook:
    :ref:`bulk-edit`


`cell`
^^^^^^

Customize the cell, see `howto on rendering <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-customize-the-rendering-of-a-cell>`_ and `howto on links <https://docs.iommi.rocks/cookbook_tables.html#how-do-i-make-a-link-in-a-cell>`_

Type: `Namespace`


Cookbook:
    :ref:`cell-link`

    :ref:`column-computed-data`

    :ref:`customize-table-cell-render`

    :ref:`attr-name-diff`

    :ref:`nested-fk`

    :ref:`row-numbers`


`choices`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Iterable`


Cookbook:
    :ref:`column-choices`


`config_from_model`
^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


`data_retrieval_method`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default: `DataRetrievalMethods.attribute_access`

Cookbook:
    :ref:`data-retrieval-method`


`display_name`
^^^^^^^^^^^^^^

the text of the header for this column. By default this is based on the `_name` so normally you won't need to specify it.

    See :ref:`name <name>`


Cookbook:
    :ref:`header-title`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


Cookbook:
    :ref:`table-as-csv`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`field`
^^^^^^^

Type: `Field | None`


Cookbook:
    :ref:`edit-table-one-to-one`


`filter`
^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`filter-column`


`group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

string describing the group of the header. If this parameter is used the header of the table now has two rows. Consecutive identical groups on the first level of the header are joined in a nice way.

Type: `str | None`


Cookbook:
    :ref:`group-columns`


`header`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`customize-header`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to hide the column

Type: `bool`

    See :ref:`include <include>`


Cookbook:
    :ref:`reverse-m2m`

    :ref:`show-columns`

    :ref:`reverse-fk-table`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`table-model-introspection`


`model_field`
^^^^^^^^^^^^^


Cookbook:
    :ref:`table-model-introspection`


`model_field_name`
^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-model-introspection`


`render_column`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If set to `False` the column won't be rendered in the table, but still be available in `table.columns`. This can be useful if you want some other feature from a column like filtering.

Type: `bool`

Default: `True`

Cookbook:
    :ref:`show-columns`


`row_group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`group-rows`


`sort_default_desc`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set to `True` to make table sort link to sort descending first.

Type: `bool`

Default: `False`

Cookbook:
    :ref:`sort-direction`


`sort_key`
^^^^^^^^^^

string denoting what value to use as sort key when this column is selected for sorting. (Or callable when rendering a table from list.)


Cookbook:
    :ref:`custom-sort-key`


`sortable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to disable sorting on this column

Type: `bool`

Default: `iommi.table.default_sortable`

Cookbook:
    :ref:`table-sorting`


`superheader`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`superheader`


Shortcuts
---------

`EditColumn.boolean`
^^^^^^^^^^^^^^^^^^^^

Shortcut to render booleans as a check mark if true or blank if false.

.. code-block:: python

    table = Table(
        columns__name=Column(),
        columns__boolean=Column.boolean(),
        rows=[
            Struct(name='true!', boolean=True),
            Struct(name='false!', boolean=False),
        ]
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('47cc4f86-dd5d-47fb-a7bd-b36dc2558e00', this)">▼ Hide result</div>
    <iframe id="47cc4f86-dd5d-47fb-a7bd-b36dc2558e00" src="doc_includes/EditColumn/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Defaults
++++++++

* `filter__call_target__attribute`
    * `boolean`
* `filter__field__call_target__attribute`
    * `boolean_tristate`
* `bulk__call_target__attribute`
    * `boolean`
* `cell__format`
    * `lambda value, **_: mark_safe(f'<span title="{gettext_lazy("Yes")}">&#10004;</span>') if value else ''`

`EditColumn.boolean_tristate`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `boolean_tristate` for the filter.



Parent: EditColumn.boolean_

Defaults
++++++++

* `filter__call_target__attribute`
    * `boolean_tristate`

`EditColumn.choice`
^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form.



Defaults
++++++++

* `bulk__call_target__attribute`
    * `choice`
* `bulk__choices`
    * `iommi.table.get_choices_from_column`
* `filter__call_target__attribute`
    * `choice`
* `filter__choices`
    * `iommi.table.get_choices_from_column`

`EditColumn.choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the choice queryset case.



Parent: EditColumn.choice_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `choice_queryset`
* `filter__call_target__attribute`
    * `choice_queryset`

`EditColumn.date`
^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `date`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `date`

`EditColumn.datetime`
^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `datetime`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `datetime`

`EditColumn.decimal`
^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `decimal`
* `filter__call_target__attribute`
    * `decimal`

`EditColumn.delete`
^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `header__template`
    * `iommi/table/header.html`
* `sortable`
    * `False`
* `filter__is_valid_filter`
    * `lambda **_: (True, '')`
* `filter__field__include`
    * `False`
* `attr`
    * `None`
* `display_name`
    * `Delete`
* `cell__attrs__class__delete`
    * `True`
* `cell__attrs__data-iommi-edit-table-delete-row-cell`
    * `True`

`EditColumn.download`
^^^^^^^^^^^^^^^^^^^^^

Shortcut for creating a clickable download icon. The URL defaults to `your_object.get_absolute_url() + 'download/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__download=Column.download(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d4784570-b07d-42be-9961-3887891f26b7', this)">▼ Hide result</div>
    <iframe id="d4784570-b07d-42be-9961-3887891f26b7" src="doc_includes/EditColumn/test_base1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: EditColumn.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'download/'`
* `cell__value`
    * `lambda row, **_: getattr(row, 'pk', False)`
* `display_name`
    * `Download`

`EditColumn.duration`
^^^^^^^^^^^^^^^^^^^^^

Parent: EditColumn.text_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `duration`
* `filter__call_target__attribute`
    * `duration`

`EditColumn.edit`
^^^^^^^^^^^^^^^^^

Shortcut for creating a clickable edit icon. The URL defaults to `your_object.get_absolute_url() + 'edit/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__edit=Column.edit(after=0),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e3df2a56-b338-4be6-bc50-5f1242852afa', this)">▼ Hide result</div>
    <iframe id="e3df2a56-b338-4be6-bc50-5f1242852afa" src="doc_includes/EditColumn/test_base2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: EditColumn.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'edit/'`
* `display_name`
    * `Edit`

`EditColumn.email`
^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `email`
* `bulk__call_target__attribute`
    * `email`

`EditColumn.file`
^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `file`
* `filter__call_target__attribute`
    * `file`
* `cell__format`
    * `lambda value, **_: str(value)`

`EditColumn.float`
^^^^^^^^^^^^^^^^^^

Parent: EditColumn.number_

Defaults
++++++++

* `filter__call_target__attribute`
    * `float`
* `bulk__call_target__attribute`
    * `float`

`EditColumn.foreign_key`
^^^^^^^^^^^^^^^^^^^^^^^^

`EditColumn.foreign_key_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `foreign_key_reverse`
* `filter__call_target__attribute`
    * `foreign_key_reverse`
* `cell__format`
    * `lambda value, **_: ', '.join(['%s' % x for x in value.all()])`
* `data_retrieval_method`
    * `DataRetrievalMethods.prefetch`
* `sortable`
    * `False`
* `extra__django_related_field`
    * `True`
* `display_name`
    * `lambda column, **_: capitalize(column.model_field.remote_field.model._meta.verbose_name_plural)`

`EditColumn.icon`
^^^^^^^^^^^^^^^^^

Shortcut to create font awesome-style icons.



Parameters
++++++++++

* `extra__icon`
    * `the name of the icon`

Defaults
++++++++

* `display_name`
    * `""`
* `cell__value`
    * `lambda table, **_: True`
* `cell__format`
    * `iommi.table.default_icon__cell__format`
* `attr`
    * `None`

`EditColumn.integer`
^^^^^^^^^^^^^^^^^^^^

Parent: EditColumn.number_

Defaults
++++++++

* `filter__call_target__attribute`
    * `integer`
* `bulk__call_target__attribute`
    * `integer`

`EditColumn.link`
^^^^^^^^^^^^^^^^^

Shortcut for creating a cell that is a link. The URL is the result of calling `get_absolute_url()` on the object.




Cookbook:
    :ref:`custom-actions`

`EditColumn.many_to_many`
^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: EditColumn.related_multiple_

`EditColumn.many_to_many_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `many_to_many_reverse`
* `filter__call_target__attribute`
    * `many_to_many_reverse`

`EditColumn.multi_choice`
^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the multi choice case.



Parent: EditColumn.choice_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `multi_choice`
* `filter__call_target__attribute`
    * `multi_choice`

`EditColumn.multi_choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This shortcut sets up `choices` for the filter and bulk form for the multi choice queryset case.



Parent: EditColumn.choice_queryset_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `multi_choice_queryset`
* `filter__call_target__attribute`
    * `multi_choice_queryset`

`EditColumn.number`
^^^^^^^^^^^^^^^^^^^

`EditColumn.related`
^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `bulk__call_target__attribute`
    * `related`
* `filter__call_target__attribute`
    * `related`
* `data_retrieval_method`
    * `DataRetrievalMethods.select`
* `sort_key`
    * `iommi.table.foreign_key__sort_key`
* `choices`
    * `iommi.table.related__choices`

`EditColumn.related_multiple`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: EditColumn.multi_choice_queryset_

Defaults
++++++++

* `bulk__call_target__attribute`
    * `many_to_many`
* `filter__call_target__attribute`
    * `many_to_many`
* `cell__format`
    * `lambda value, **_: ', '.join(['%s' % x for x in value.all()])`
* `data_retrieval_method`
    * `DataRetrievalMethods.prefetch`
* `sortable`
    * `False`
* `extra__django_related_field`
    * `True`
* `display_name`
    * `lambda column, **_: capitalize(column.model_field.remote_field.model._meta.verbose_name_plural)`
* `choices`
    * `iommi.table.related__choices`

`EditColumn.reorder_handle`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `sortable`
    * `False`
* `field__call_target__attribute`
    * `hidden`
* `field__parse`
    * `iommi.form.int_parse`
* `field__include`
    * `True`
* `field__input__attrs__data-reordering-value`
    * `True`
* `cell__attrs__title`
    * `Drag and drop to reorder`
* `cell__attrs__class__reordering-handle-cell`
    * `True`
* `cell__attrs__data-iommi-reordering-handle`
    * `True`
* `after`
    * `<object object at 0x7c9e46be9390>`

`EditColumn.run`
^^^^^^^^^^^^^^^^

Shortcut for creating a clickable run icon. The URL defaults to `your_object.get_absolute_url() + 'run/'`. Specify the option cell__url to override.

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__run=Column.run(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d3812189-00db-405e-be4b-9de4baf4c7e1', this)">▼ Hide result</div>
    <iframe id="d3812189-00db-405e-be4b-9de4baf4c7e1" src="doc_includes/EditColumn/test_base3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parent: EditColumn.icon_

Defaults
++++++++

* `cell__url`
    * `lambda row, **_: row.get_absolute_url() + 'run/'`
* `display_name`
    * `Run`

`EditColumn.select`
^^^^^^^^^^^^^^^^^^^

Shortcut for a column of checkboxes to select rows. This is useful for implementing bulk operations.

By default tables have a column named `select` that is used for this purpose. It is shown
automatically when bulk editing or a bulk action is enabled, and is otherwise hidden. You can
force it on (or off) by setting `columns__select__include`. See the example below.

To implement a custom post handler that operates on the selected rows, do

.. code-block:: python

    def my_handler(table):
        rows = table.selection()
        # rows will either be a queryset, or a list of elements
        # matching the type of rows of the table
        ...

    table = Table(
        auto__model=Album,
        bulk__actions__submit=Action.submit(post_handler=my_handler)
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9abe7d34-7832-475d-9be9-d2b6847d4717', this)">▼ Hide result</div>
    <iframe id="9abe7d34-7832-475d-9be9-d2b6847d4717" src="doc_includes/EditColumn/test_base4.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Parameters
++++++++++

* `extra__checkbox_name`
    * `the name of the checkbox. Default is `"pk"`, resulting in checkboxes like `"pk_1234"`.`
* `extra__checked`
    * `callable to specify if the checkbox should be checked initially. Defaults to `False`.`

Defaults
++++++++

* `header__template`
    * `iommi/table/select_column_header.html`
* `sortable`
    * `False`
* `filter__include`
    * `False`
* `filter__is_valid_filter`
    * `lambda **_: (True, '')`
* `filter__field__include`
    * `False`
* `bulk__include`
    * `False`
* `attr`
    * `None`
* `cell__value`
    * `lambda table, cells, row, **_: (       row.pk       if isinstance(table.rows, QuerySet)       # row_index is the visible row number       # See selection() for the code that does the lookup       else cells.row_index     )`
* `cell__format`
    * `lambda column, row, value, **kwargs: format_html(       # language=HTML       '<input type="checkbox" class="checkbox" name="{checkbox_name}_{row_id}" {checked_str} />',       checkbox_name=column.extra.checkbox_name,       row_id=value,       checked_str=(         'checked'         if evaluate_strict(column.extra.checked, column=column, row=row, value=value, **kwargs)         else ''       ),     )`
* `extra__checkbox_name`
    * `pk`
* `extra__checked`
    * `lambda **_: False`
* `extra__icon`
    * `fa fa-check-square-o`

`EditColumn.substring`
^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__query_operator_for_field`
    * `:`

`EditColumn.text`
^^^^^^^^^^^^^^^^^

This is an explicit synonym for `Column()`.



Defaults
++++++++

* `bulk__call_target__attribute`
    * `text`
* `filter__call_target__attribute`
    * `text`

`EditColumn.textarea`
^^^^^^^^^^^^^^^^^^^^^

Parent: EditColumn.text_

`EditColumn.time`
^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `filter__call_target__attribute`
    * `time`
* `filter__query_operator_to_q_operator`
    * `lambda op: {'=': 'exact', ':': 'contains'}.get(op)`
* `bulk__call_target__attribute`
    * `time`

Methods
-------

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

Class methods
-------------

`hardcoded`
^^^^^^^^^^^





EditTable
=========

Base class: :doc:`Table`

Describe an editable table. Example:

.. code-block:: python

    table = EditTable(
        auto__model=Album,
        columns__name__field__include=True,
        columns__delete=EditColumn.delete(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('29c52eb4-0c37-409f-ada6-c169799a19f4', this)">▼ Hide result</div>
    <iframe id="29c52eb4-0c37-409f-ada6-c169799a19f4" src="doc_includes/EditTable/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Refinable members
-----------------


`action_class`
^^^^^^^^^^^^^^

Type: `type[Action]`


Cookbook:
    :ref:`table-internal-classes`


`actions`
^^^^^^^^^

Type: `dict[str, Action]`


Cookbook:
    :ref:`custom-actions`


`actions_below`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `False`

Cookbook:
    :ref:`actions-below-table`


`actions_template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/form/actions.html`

Cookbook:
    :ref:`actions-below-table`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

dict of strings to string/callable of HTML attributes to apply to the table

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`auto`
^^^^^^

Type: :doc:`TableAutoConfig`

    See :ref:`auto <auto>`


Cookbook:
    :ref:`fk-related-data-access`

    :ref:`nested-fk`


`bulk`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Form | None`


Cookbook:
    :ref:`bulk-delete`

    :ref:`custom-bulk-action`


`bulk_container`
^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`post-bulk-edit`


`bulk_exclude`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

exclude filters to apply to the `QuerySet` before performing the bulk operation

Type: `Namespace`

Default: `{}`

Cookbook:
    :ref:`post-bulk-edit`


`bulk_filter`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

filters to apply to the `QuerySet` before performing the bulk operation

Type: `Namespace`

Default: `{}`

Cookbook:
    :ref:`post-bulk-edit`


`cell`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `CellConfig`


Cookbook:
    :ref:`table-as-div`


`cells_class`
^^^^^^^^^^^^^

Type: `type[Cells]`


Cookbook:
    :ref:`table-internal-classes`


`columns`
^^^^^^^^^

(use this only when not using the declarative style) a list of Column objects

Type: `dict[str, Column]`


Cookbook:
    :ref:`column-computed-data`


`container`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`arbitrary-html`


`create_form`
^^^^^^^^^^^^^

Type: `Form | None`


Cookbook:
    :ref:`edit-table-forms`


`default_sort_order`
^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`default-sort-order`


`edit_actions`
^^^^^^^^^^^^^^

Type: `dict[str, Action]`


Cookbook:
    :ref:`edit-table-actions`


`edit_form`
^^^^^^^^^^^

Type: :doc:`Form`


Cookbook:
    :ref:`edit-table-forms`


`empty_message`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`table-as-div`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


Cookbook:
    :ref:`table-as-csv`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`form_class`
^^^^^^^^^^^^

Type: `type[Form]`


Cookbook:
    :ref:`custom-member-class`


`h_tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`header`
^^^^^^^^

Default: `Namespace()`

Cookbook:
    :ref:`stop-header-render`

    :ref:`turn-off-header`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`invalid_form_message`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`table-invalid-form-message`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`member_class`
^^^^^^^^^^^^^^

Type: `type[Column]`


Cookbook:
    :ref:`custom-member-class`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`table-model-introspection`


`outer`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`arbitrary-html`


`page_class`
^^^^^^^^^^^^

Type: `type[Page]`


Cookbook:
    :ref:`table-internal-classes`


`page_size`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int`

Default: `16`

Cookbook:
    :ref:`turn-off-pagination`


`parent_form`
^^^^^^^^^^^^^

Type: `Form | None`


Cookbook:
    :ref:`edit-table-parent-form`


`parts`
^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`turn-off-pagination`


`post_bulk_edit`
^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`post-bulk-edit`


`preprocess_row`
^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-as-div`


`preprocess_row_for_create`
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`edit-table-preprocess-create`


`preprocess_rows`
^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-as-div`


`query`
^^^^^^^

Type: `Query | None`


Cookbook:
    :ref:`initial-filter`


`query_class`
^^^^^^^^^^^^^

Type: `type[Query]`


Cookbook:
    :ref:`custom-member-class`


`query_from_indexes`
^^^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`query-from-indexes`


`reorderable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool | dict[str, Any] | None`


Cookbook:
    :ref:`edit-table-reorderable`


`row`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `RowConfig`


Cookbook:
    :ref:`customize-rendering-row`


`row_group_class`
^^^^^^^^^^^^^^^^^

Type: `type[RowGroup]`


Cookbook:
    :ref:`table-internal-classes`


`rows`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

a list or QuerySet of objects


Cookbook:
    :ref:`additional-rows`


`sortable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to turn off sorting for all columns

Type: `bool`

Default: `True`

Cookbook:
    :ref:`table-sorting`


`sorter`
^^^^^^^^


Cookbook:
    :ref:`custom-sort-key`


`superheader`
^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`superheader`


`table_tag_wrapper`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`table-tag-wrapper`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `table`
    See :ref:`tag <tag>`


`tbody`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`table-as-div`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/table/table.html`
    See :ref:`template <template>`


`title`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | None`

    See :ref:`title <title>`


Shortcuts
---------

`EditTable.div`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`
* `tbody__tag`
    * `div`
* `cell__tag`
    * `None`
* `row__tag`
    * `div`
* `header__template`
    * `None`

Methods
-------

`bind`
^^^^^^

`cells_for_rows_for_create`
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Yield a Cells instance for each create row sent from the client.


`get_errors`
^^^^^^^^^^^^

`is_valid`
^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`should_render_form_tag`
^^^^^^^^^^^^^^^^^^^^^^^^





Endpoint
========

Base class: :doc:`Traversable`

Class that describes an endpoint in iommi. You can create your own custom
endpoints on any :doc:`Part`.

An endpoint can return an `HttpResponse` directly, or a `Part` (which is
rendered for you); everything else we try to dump to json for you.

Example:

.. code-block:: python

    def my_view(request):
        return Page(
            parts__h1=html.h1('Hi!'),
            endpoints__echo__func=lambda value, **_: value,
        )

This page will respond to `?/echo=foo` by returning a json response `"foo"`.

If you want to allow POST requests, you can set `endpoints__echo__http_methods = {'POST'}` or `{'GET', 'POST'}` to allow both.

Refinable members
-----------------


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`func`
^^^^^^

Type: `Callable`


Cookbook:
    :ref:`custom-endpoint`


`http_methods`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `set`

Default: `{'GET'}`

Cookbook:
    :ref:`custom-endpoint`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `True`
    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


Methods
-------

`on_bind`
^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^





Field
=====

Base class: :doc:`Part`

Class that describes a field, i.e. what input controls to render, the label, etc.

See :doc:`Form` for more complete examples.

The life cycle of the data is:

    1. `raw_data`: will be set if the corresponding key is present in the HTTP request
    2. `parsed_data`: set if parsing is successful, which only happens if the previous step succeeded
    3. `value`: set if validation is successful, which only happens if the previous step succeeded

Note that, in addition to the parameters with the defined behavior below, you can pass in any keyword argument you need yourself, including callables that conform to the protocol, and they will be added and evaluated as members.

All these parameters can be callables, and if they are, will be evaluated with the keyword arguments form and field. The only exceptions are `is_valid` (which gets `form`, `field` and `parsed_data`), `render_value` (which takes `form`, `field` and `value`) and `parse` (which gets `form`, `field`, `string_value`). Example of using a lambda to specify a value:

.. code-block:: python

        Field(attrs__id=lambda form, field: 'my_id_%s' % field._name)

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set the order of fields, see the `howto <https://docs.iommi.rocks/cookbook_forms.html#how-do-i-change-the-order-of-the-fields>`_ for an example.

Type: `int | str`

    See :ref:`after <after>`


Cookbook:
    :ref:`field-order`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attr`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The attribute path to apply or get the data from. For example using `foo__bar__baz` will result in `your_instance.foo.bar.baz` being set by the `apply()` function. Setting this to `None` will mean no attribute is read or written by `apply()`. Defaults to same as `name`.

Type: `str`

    See :ref:`attr <attr>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A dict containing any custom html attributes to be sent to the `input__template`.

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


Cookbook:
    :ref:`freetext-column`


`choice_display_name_formatter`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Callback given the keyword argument `choice` in addition to standard parameters, to obtain the display name representing a given choice to the end user. Default implementation will use `str(choice)`

Type: `Callable[..., str]`

Default: `lambda choice, **_: '%s' % choice`

Cookbook:
    :ref:`customize-choices-display`


`choice_id_formatter`
^^^^^^^^^^^^^^^^^^^^^

Callback given the keyword argument `choice` in addition to standard parameters, to obtain the string value to represent the identity of a given `choice`. Default implementation will use `str(choice)`

Type: `Callable[..., str]`

Default: `lambda choice, **_: '%s' % choice`

Cookbook:
    :ref:`customize-choices-display`


`choice_to_optgroup`
^^^^^^^^^^^^^^^^^^^^

Callback to generate the optgroup for the given choice. It will get the keyword argument `choice`. It should return None if the choice should not be grouped.

Type: `Callable[..., str | None] | None`


Cookbook:
    :ref:`customize-choices-display`


`choices`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Callable[..., list[Any]]`


Cookbook:
    :ref:`dependent-fields`

    :ref:`dependent-fields2`


`config_from_model`
^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


`display_name`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The text in the HTML label tag. Default: `capitalize(name).replace('_', ' ')`

Type: `str | None`

    See :ref:`name <name>`


`editable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Is this field editable.

Type: `bool`

Default: `True`

Cookbook:
    :ref:`create-or-edit-forms`

    :ref:`non-rendered-field`

    :ref:`field-non-editable`


`empty_label`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `---`

Cookbook:
    :ref:`customize-choices-display`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`errors`
^^^^^^^^

Type: `Errors`


Cookbook:
    :ref:`field-hidden`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`group-fields`


`help`
^^^^^^

Type: `Fragment | str`


Cookbook:
    :ref:`field-label-help`


`help_text`
^^^^^^^^^^^

The help text will be grabbed from the django model if specified and available.


Cookbook:
    :ref:`field-label-help`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


Cookbook:
    :ref:`field-reverse-m2m`

    :ref:`include-exclude-fields`

    :ref:`show-fields`


`initial`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Initial value of the field

Type: `Any`


Cookbook:
    :ref:`field-initial-value`

    :ref:`non-rendered-field`


`input`
^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`field-input-template`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`is_boolean`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `False`

Cookbook:
    :ref:`customize-choices-display`


`is_list`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Interpret request data as a list (can NOT be a callable). Default: `False`

Type: `bool`

Default: `False`

Cookbook:
    :ref:`customize-choices-display`


`is_valid`
^^^^^^^^^^


Validation function. Should return a tuple of `(bool, reason_for_failure_if_bool_is_false)` or raise `ValidationError`.

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        fields__name__is_valid=lambda parsed_data, **_: (parsed_data.startswith('H'), 'Must start with H!'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('8df5343a-166a-4294-8da6-7c4f534f7382', this)">▼ Hide result</div>
    <iframe id="8df5343a-166a-4294-8da6-7c4f534f7382" src="doc_includes/Field/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Cookbook:
    :ref:`validate-multiple-fields-together`

    :ref:`custom-validator`


`label`
^^^^^^^

Type: `Fragment | None`


Cookbook:
    :ref:`field-label-help`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`form-model-introspection`


`model_field`
^^^^^^^^^^^^^

Type: `Field | None`


Cookbook:
    :ref:`form-model-introspection`


`model_field_name`
^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`form-model-introspection`


`non_editable_input`
^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`

Default: `{'call_target': <class 'iommi.fragment.Fragment'>, 'children__text': <function Field.<lambda> at 0x7c9e449c8fe0>, 'attrs__value': <function Field.<lambda> at 0x7c9e449c9080>}`

Cookbook:
    :ref:`field-raw-data`


`parse`
^^^^^^^


Parse function. Default just returns the string input unchanged. This function can raise `ValueError` or `ValidationError` to produce a field error message.




Cookbook:
    :ref:`supply-custom-parser-field`


`parse_empty_string_as_none`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `True`

Cookbook:
    :ref:`field-raw-data`


`parsed_data`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Any`


Cookbook:
    :ref:`field-non-editable`


`post_validation`
^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`validate-multiple-fields-together`


`raw_data`
^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`field-raw-data`


`read_from_instance`
^^^^^^^^^^^^^^^^^^^^

Callback to retrieve value from edited instance. Invoked with parameters field and instance.


Cookbook:
    :ref:`field-read-from-instance`


`render_value`
^^^^^^^^^^^^^^


Render the parsed and validated value into a string. Default just converts to `str`.

.. code-block:: python

    sentinel = '!!custom!!'
    form = Form(
        fields__foo=Field(
            initial='not sentinel value',
            render_value=lambda form, field, value, **_: sentinel,
        )
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4039070b-5009-4f73-8376-ae8eb42bd386', this)">▼ Hide result</div>
    <iframe id="4039070b-5009-4f73-8376-ae8eb42bd386" src="doc_includes/Field/test_base1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Cookbook:
    :ref:`field-raw-data`


`render_value_on_error`
^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`field-raw-data`


`required`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the field is a required field. Default: `True`

Type: `bool`

Default: `True`

Cookbook:
    :ref:`field-required`


`search_fields`
^^^^^^^^^^^^^^^


Cookbook:
    :ref:`field-search-fields`


`strip_input`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Runs the input data through standard python .strip() before passing it to the parse function (can NOT be callable). Default: `True`

Type: `bool`

Default: `True`

Cookbook:
    :ref:`field-raw-data`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `div`
    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Django template filename or `Template` instance for the entire row. Normally you shouldn't need to override on this level. Prefer overriding `input__template`, `label__template` or `error__template` as needed.

Type: `str | Template`

    See :ref:`template <template>`


Cookbook:
    :ref:`field-template`


`write_to_instance`
^^^^^^^^^^^^^^^^^^^

Callback to write value to instance. Invoked with parameters field, instance and value.


Cookbook:
    :ref:`field-write-to-instance`


Shortcuts
---------

`Field.boolean`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `parse`
    * `iommi.form.bool_parse`
* `required`
    * `False`
* `is_boolean`
    * `True`

`Field.boolean_tristate`
^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.choice_

Defaults
++++++++

* `choices`
    * `[True, False]`
* `choice_id_formatter`
    * `lambda choice, **_: 'true' if choice else 'false'`
* `choice_display_name_formatter`
    * `lambda choice, **_: gettext_lazy('Yes') if choice else gettext_lazy('No')`
* `parse`
    * `iommi.form.boolean_tristate__parse`
* `required`
    * `False`

`Field.checkboxes`
^^^^^^^^^^^^^^^^^^

Parent: Field.multi_choice_

Defaults
++++++++

* `input__attrs__id`
    * `None`
* `extra_evaluated__id`
    * `iommi.form.default_input_id`

`Field.choice`
^^^^^^^^^^^^^^

Shortcut for single choice field. If required is false it will automatically add an option first with the value '' and the title '---'. To override that text pass in the parameter empty_label.



Defaults
++++++++

* `required`
    * `True`
* `is_list`
    * `False`
* `is_valid`
    * `iommi.form.choice_is_valid`
* `input__attrs__multiple`
    * `lambda field, **_: True if field.is_list else None`
* `parse`
    * `iommi.form.choice_parse`

`Field.choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.choice_

Defaults
++++++++

* `parse`
    * `iommi.form.choice_queryset__parse`
* `choice_id_formatter`
    * `lambda choice, **_: choice.pk`
* `endpoints__choices__func`
    * `iommi.form.choice_queryset__endpoint_handler`
* `is_valid`
    * `iommi.form.choice_queryset__is_valid`
* `extra__filter_and_sort`
    * `iommi.form.choice_queryset__extra__filter_and_sort`
* `extra__model_from_choices`
    * `iommi.form.choice_queryset__extra__model_from_choices`

`Field.choice_searchable`
^^^^^^^^^^^^^^^^^^^^^^^^^

Shortcut for single choice field, but with select2.



Parent: Field.choice_

`Field.date`
^^^^^^^^^^^^

Defaults
++++++++

* `parse`
    * `iommi.form.date_parse`
* `render_value`
    * `iommi.form.date_render_value`

`Field.datetime`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `parse`
    * `iommi.form.datetime_parse`
* `render_value`
    * `iommi.form.datetime_render_value`
* `extra_evaluated__is_tz_aware`
    * `lambda **_: settings.USE_TZ`

`Field.decimal`
^^^^^^^^^^^^^^^

Parent: Field.number_

Defaults
++++++++

* `parse`
    * `iommi.form.decimal_parse`

`Field.dropfile`
^^^^^^^^^^^^^^^^

Parent: Field.file_

`Field.dropimage`
^^^^^^^^^^^^^^^^^

Parent: Field.dropfile_

`Field.duration`
^^^^^^^^^^^^^^^^

Parent: Field.text_

Defaults
++++++++

* `parse`
    * `iommi.form.duration_parse`
* `render_value`
    * `iommi.form.duration_render_value`

`Field.email`
^^^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `email`
* `parse`
    * `iommi.form.email_parse`

`Field.file`
^^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `file`
* `input__attrs__multiple`
    * `lambda field, **_: True if field.is_list else None`
* `raw_data`
    * `iommi.form.file__raw_data`
* `write_to_instance`
    * `iommi.form.file_write_to_instance`
* `extra__django_related_field`
    * `True`
* `extra_evaluated__show_thumbs`
    * `True`
* `attrs__data-iommi-extended-file-field`
    * `True`
* `attrs__data-iommi-extended-file-with-thumbs`
    * `lambda field, **_: field.extra_evaluated.show_thumbs`
* `attrs__data-iommi-extended-file-thumb-width`
    * `100`
* `attrs__data-iommi-extended-file-thumb-height`
    * `100`
* `attrs__data-iommi-extended-file-loading-icon`
    * `lambda **_: static('images/iommi-icons/spinner.svg')`

`Field.float`
^^^^^^^^^^^^^

Parent: Field.number_

Defaults
++++++++

* `parse`
    * `iommi.form.float_parse`

`Field.foreign_key`
^^^^^^^^^^^^^^^^^^^

`Field.foreign_key_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.related_multiple_

Defaults
++++++++

* `editable`
    * `False`
* `display_name`
    * `lambda field, **_: capitalize(field.model_field.related_model._meta.verbose_name_plural)`
* `choices`
    * `iommi.form.related__choices`
* `extra__django_related_field`
    * `True`

`Field.hardcoded`
^^^^^^^^^^^^^^^^^

`Field.heading`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `editable`
    * `False`
* `attr`
    * `None`

`Field.hidden`
^^^^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `hidden`
* `attrs__style__display`
    * `none`


Cookbook:
    :ref:`field-hidden`

`Field.image`
^^^^^^^^^^^^^

Parent: Field.file_

`Field.info`
^^^^^^^^^^^^

Shortcut to create an info entry.



Defaults
++++++++

* `editable`
    * `False`
* `attr`
    * `None`

`Field.integer`
^^^^^^^^^^^^^^^

Parent: Field.number_

Defaults
++++++++

* `parse`
    * `iommi.form.int_parse`

`Field.many_to_many`
^^^^^^^^^^^^^^^^^^^^

Parent: Field.related_multiple_

`Field.many_to_many_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.related_multiple_

`Field.multi_choice`
^^^^^^^^^^^^^^^^^^^^

Parent: Field.choice_

Defaults
++++++++

* `is_list`
    * `True`

`Field.multi_choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.choice_queryset_

Defaults
++++++++

* `is_list`
    * `True`


Cookbook:
    :ref:`field-related-multi-select`

`Field.non_rendered`
^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `template`
    * `<iommi._web_compat.Template object at 0x7c9e44a66510>`
* `editable`
    * `False`


Cookbook:
    :ref:`non-rendered-field`

`Field.number`
^^^^^^^^^^^^^^

`Field.password`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `password`
* `render_value`
    * `lambda **_: ''`
* `render_value_on_error`
    * `lambda **_: ''`

`Field.phone_number`
^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `is_valid`
    * `iommi.form.phone_number_is_valid`

`Field.radio`
^^^^^^^^^^^^^

Parent: Field.choice_

Defaults
++++++++

* `input__attrs__id`
    * `None`
* `extra_evaluated__id`
    * `iommi.form.default_input_id`

`Field.related`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `choices`
    * `iommi.form.related__choices`


Cookbook:
    :ref:`field-related-multi-select`

`Field.related_multiple`
^^^^^^^^^^^^^^^^^^^^^^^^

Parent: Field.multi_choice_queryset_

Defaults
++++++++

* `display_name`
    * `lambda field, **_: capitalize(field.model_field.remote_field.model._meta.verbose_name_plural)`
* `choices`
    * `iommi.form.related__choices`
* `read_from_instance`
    * `iommi.form.related_multiple__read_from_instance`
* `write_to_instance`
    * `iommi.form.related_multiple__write_to_instance`
* `extra__django_related_field`
    * `True`

`Field.text`
^^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `text`

`Field.textarea`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `input__tag`
    * `textarea`
* `input__attrs__type`
    * `None`
* `input__attrs__value`
    * `None`
* `input__children__text`
    * `lambda field, **_: field.rendered_value`

`Field.time`
^^^^^^^^^^^^

Defaults
++++++++

* `parse`
    * `iommi.form.time_parse`
* `render_value`
    * `iommi.form.time_render_value`

`Field.url`
^^^^^^^^^^^

Defaults
++++++++

* `input__attrs__type`
    * `url`
* `parse`
    * `iommi.form.url_parse`

Methods
-------

`add_error`
^^^^^^^^^^^

`bind_from_instance`
^^^^^^^^^^^^^^^^^^^^

`get_errors`
^^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

Class methods
-------------

`from_model`
^^^^^^^^^^^^



Create a `Field` from a Django model field.

When used declaratively inside a `Form`, you normally don't need to pass anything:
the model is taken from the containing form and the model field name from the field's
own name. This works because resolution is deferred until the form is bound, by which
point both are known.

.. code-block:: python

    class AlbumForm(Form):
        name = Field.from_model()

Pass `attr` (using `__` to drill down) to read a field from a related model:

.. code-block:: python

    class AlbumForm(Form):
        artist_name = Field.from_model(attr='artist__name')

The explicit `model`, `model_field_name` and `model_field` parameters are still
accepted for the rare cases where the field can't be inferred from context (e.g. when
not declared on a form), but are no longer required.





Filter
======

Base class: :doc:`Part`

Class that describes a filter that you can search for.

See :doc:`Query` for more complete examples.

Parameters with the prefix `field__` will be passed along downstream to the `Field` instance if applicable. This can be used to tweak the basic style interface.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attr`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`attr <attr>`


Cookbook:
    :ref:`control-q`


`choices`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`filter-gui-field`


`config_from_model`
^^^^^^^^^^^^^^^^^^^

Type: `Namespace`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`field`
^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`filter-gui-field`


`freetext`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`freetext-column`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


Cookbook:
    :ref:`filter-column`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`is_valid_filter`
^^^^^^^^^^^^^^^^^

Default: `iommi.query.default_filter__is_valid_filter`

Cookbook:
    :ref:`filter-matching`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`filter-matching`


`model_field`
^^^^^^^^^^^^^


Cookbook:
    :ref:`filter-matching`


`model_field_name`
^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`filter-matching`


`parse`
^^^^^^^


Cookbook:
    :ref:`filter-matching`


`pk_lookup_to_q`
^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`filter-matching`


`query_name`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default: `lambda filter, **_: filter.iommi_name()`

Cookbook:
    :ref:`control-q`


`query_operator_for_field`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `=`

Cookbook:
    :ref:`filter-matching`


`query_operator_to_q_operator`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`override-operator`


`search_fields`
^^^^^^^^^^^^^^^


Cookbook:
    :ref:`filter-gui-field`


`unary`
^^^^^^^


Cookbook:
    :ref:`filter-matching`


`value_to_q`
^^^^^^^^^^^^


Cookbook:
    :ref:`control-q`


Shortcuts
---------

`Filter.boolean`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `boolean`
* `parse`
    * `iommi.form.bool_parse`
* `unary`
    * `True`
* `query_operator_to_q_operator`
    * `iommi.query.boolean__query_operator_to_q_operator`

`Filter.boolean_tristate`
^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `boolean_tristate`
* `parse`
    * `iommi.form.boolean_tristate__parse`
* `query_operator_to_q_operator`
    * `iommi.query.boolean__query_operator_to_q_operator`
* `unary`
    * `True`

`Filter.case_sensitive`
^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `query_operator_to_q_operator`
    * `iommi.query.case_sensitive_query_operator_to_q_operator`

`Filter.choice`
^^^^^^^^^^^^^^^

Field that has one value out of a set.



Defaults
++++++++

* `field__call_target__attribute`
    * `choice`

`Filter.choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^

Field that has one value out of a set.



Defaults
++++++++

* `field__call_target__attribute`
    * `choice_queryset`
* `query_operator_to_q_operator`
    * `lambda op: 'exact'`
* `value_to_q`
    * `iommi.query.choice_queryset_value_to_q`
* `is_valid_filter`
    * `iommi.query.choice_queryset__is_valid_filter`

`Filter.date`
^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `date`
* `parse`
    * `iommi.form.date_parse`

`Filter.datetime`
^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `date`
* `parse`
    * `iommi.form.date_parse`
* `extra_evaluated__is_tz_aware`
    * `lambda **_: settings.USE_TZ`

`Filter.decimal`
^^^^^^^^^^^^^^^^

Parent: Filter.number_

Defaults
++++++++

* `field__call_target__attribute`
    * `decimal`

`Filter.duration`
^^^^^^^^^^^^^^^^^

Parent: Filter.text_

Defaults
++++++++

* `field__call_target__attribute`
    * `duration`

`Filter.email`
^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `email`

`Filter.file`
^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `file`

`Filter.float`
^^^^^^^^^^^^^^

Parent: Filter.number_

Defaults
++++++++

* `field__call_target__attribute`
    * `float`
* `parse`
    * `iommi.form.float_parse`

`Filter.foreign_key`
^^^^^^^^^^^^^^^^^^^^

`Filter.foreign_key_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `foreign_key_reverse`
* `extra__django_related_field`
    * `True`

`Filter.integer`
^^^^^^^^^^^^^^^^

Parent: Filter.number_

Defaults
++++++++

* `field__call_target__attribute`
    * `integer`
* `parse`
    * `iommi.form.int_parse`

`Filter.many_to_many`
^^^^^^^^^^^^^^^^^^^^^

`Filter.many_to_many_reverse`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`Filter.multi_choice`
^^^^^^^^^^^^^^^^^^^^^

Field that has one value out of a set.



Defaults
++++++++

* `field__call_target__attribute`
    * `multi_choice`

`Filter.multi_choice_queryset`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `multi_choice_queryset`


Cookbook:
    :ref:`filter-multi-select`

`Filter.number`
^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `number`
* `query_operator_to_q_operator`
    * `iommi.query.case_sensitive_query_operator_to_q_operator`

`Filter.related`
^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `related`
* `choices`
    * `iommi.query.related__choices`


Cookbook:
    :ref:`filter-multi-select`

`Filter.related_multiple`
^^^^^^^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `many_to_many`
* `choices`
    * `iommi.query.related__choices`
* `extra__django_related_field`
    * `True`

`Filter.text`
^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `text`
* `query_operator_for_field`
    * `:`

`Filter.textarea`
^^^^^^^^^^^^^^^^^

Parent: Filter.text_

`Filter.time`
^^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `time`
* `parse`
    * `iommi.form.time_parse`

`Filter.url`
^^^^^^^^^^^^

Defaults
++++++++

* `field__call_target__attribute`
    * `url`

Methods
-------

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

Class methods
-------------

`checkboxes`
^^^^^^^^^^^^

`from_model`
^^^^^^^^^^^^



Create a `Filter` from a Django model field.

When used declaratively inside a `Query`, you normally don't need to pass anything:
the model is taken from the containing query and the model field name from the filter's
own name. This works because resolution is deferred until the query is bound, by which
point both are known.

.. code-block:: python

    class AlbumQuery(Query):
        name = Filter.from_model()

Pass `attr` (using `__` to drill down) to read a field from a related model:

.. code-block:: python

    class AlbumQuery(Query):
        artist_name = Filter.from_model(attr='artist__name')

The explicit `model`, `model_field_name` and `model_field` parameters are still
accepted for the rare cases where the field can't be inferred from context (e.g. when
not declared on a query), but are no longer required.





Form
====

Base class: :doc:`Part`

Describe a Form. Example:

.. code-block:: python

    class MyForm(Form):
        a = Field()
        b = Field.email()

    form = MyForm().bind(request=request)

You can also create an instance of a form with this syntax if it's more convenient:

.. code-block:: python

    form = Form(
        fields=dict(
            a=Field(),
            b=Field.email(),
        ),
    ).bind(request=request)

In the common case the fields namespace will contain only instances of `Field`, but
iommi actually supports arbitrary `Part` objects. For example:

.. code-block:: python

    form = Form(
        fields=dict(
            # Display a and b inside a box
            box=html.div(
                attrs__class__box=True,
                children__a=Field(),
                children__b=Field.email(),
            ),
            # And c regularly
            c=Field(),
        )
    )

So that writing the application logic (e.g. validation and post handlers) is independent
of minor changes to the layout, after bind the `fields` namespace of the form will contain
only instances of `Field` keyed by their `_name` independently of how deep they are in the
hierarchy. Given the above, an appropriate post_handler would be:

.. code-block:: python

    def post_handler(form, **_):
        if not form.is_valid():
            return

        print(form.fields.a.value, form.fields.b.value, form.fields.c.value)
        # And not:
        # print(form.fields.box.a.value, form.fields.box.b.value, form.fields.c.value)

Use of Form.layout:

.. code-block:: python

    from django.contrib.auth import get_user_model
    from django.utils.translation import gettext_lazy
    from iommi._web_compat import Template

    class UserForm(Form):
        class Meta:
            auto__model = get_user_model()
            layout = Panel(dict(
                p_main=Panel.fieldset(dict(
                    username=Panel.field(),
                    p_fullname=Panel.row(dict(
                        first_name=Panel.field(col__attrs__class__firstname=True),
                        last_name=Panel.field(),
                    )),
                    # examples of custom html parts:
                    p_foo=Panel.row(dict(
                        p_bar=gettext_lazy('Some plain text'),
                        p_baz=Template('{% load i18n %}<span>{% translate "Foobar!" %}</span>'),
                    )),
                    p_qux=Fragment(template='path/to/template.html'),
                    p_quux=html.h3('Quux'),
                    p_corge__template='path/to/another_template.html',
                )),
                p_permissions=Panel.fieldset(dict(
                    # ...
                )),
                p_error=Panel.alert('Error!', level='error'),
            ))

.. _form-save-callbacks:

Save callbacks
~~~~~~~~~~~~~~

Saving a model in Django mirrors SQL quite closely, and `Form.create`/`Form.edit`
have hooks for all the steps in a multi-step commit. They are called in this
order:

- `extra__new_instance`: called to create a new instance of the model. By default it just calls `form.model()`.
- `extra__save`: called to save each `model_object`. By default it calls `model_object.save()`. Note that the keyword argument is `model_object`, *not* `instance`, and that it is called once per model when the form spans more than one (e.g. `auto__include=['name', 'artist__name']`), so always check `isinstance` before applying model specific behavior.
- `extra__pre_save_all_but_related_fields` (only called for `Form.create`)
- `extra__on_save_all_but_related_fields` (only called for `Form.create`)
- `extra__pre_save` (before `instance.save()`)
- `extra__on_save` (after `instance.save()`)

Note that `Form.create` saves twice, because Django needs a pk before related
fields can be written. The first save happens between
`pre_save_all_but_related_fields` and `on_save_all_but_related_fields`, which
means `extra__pre_save` runs *after* the row already exists and is too late to
fill in a `NOT NULL` column. `Form.edit` saves once, before `extra__on_save`.

After a POST completes, `extra__redirect` is called if present, otherwise
`extra__redirect_to` determines where to redirect to.

See :ref:`the cookbook <form-save-hooks>` for worked examples.

Refinable members
-----------------


`action_class`
^^^^^^^^^^^^^^

Type: `type[Action]`


Cookbook:
    :ref:`custom-member-class`


`actions`
^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`form-actions`


`actions_template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/form/actions.html`

Cookbook:
    :ref:`form-actions`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attr`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`attr <attr>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


Cookbook:
    :ref:`freetext-column`


`auto`
^^^^^^

Type: :doc:`FormAutoConfig`

    See :ref:`auto <auto>`


Cookbook:
    :ref:`include-exclude-fields`

    :ref:`reverse-fk-form`


`editable`
^^^^^^^^^^

Type: `bool`

Default: `True`

Cookbook:
    :ref:`field-non-editable`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`errors`
^^^^^^^^

Type: `Errors`


Cookbook:
    :ref:`field-hidden`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


Cookbook:
    :ref:`form-save-hooks`

    :ref:`form-redirect`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`field_group`
^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`group-fields`


`fields`
^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`dependent-fields`

    :ref:`nested-forms`


`fields_template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`


Cookbook:
    :ref:`fields-templates`


`h_tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`instance`
^^^^^^^^^^

Type: `Any`


Cookbook:
    :ref:`form-save-hooks`

    :ref:`create-or-edit-forms`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`layout`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Panel | None`


Cookbook:
    :ref:`field-write-to-instance`


`layout_render_unused_fields`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `False`

Cookbook:
    :ref:`field-write-to-instance`


`layout_template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template | None`

Default: `lambda form, **_: 'iommi/form/layout.html' if form.layout is not None else None`

Cookbook:
    :ref:`field-write-to-instance`


`member_class`
^^^^^^^^^^^^^^

Type: `type[Field]`


Cookbook:
    :ref:`custom-member-class`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`form-model-introspection`


`page_class`
^^^^^^^^^^^^

Type: `type[Page]`


Cookbook:
    :ref:`custom-member-class`


`post_validation`
^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`validate-multiple-fields-together`


`read_nested_form_from_instance`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Read the nested forms instance from the parent forms instance.

This is analogous to `Field.read_from_instance` but for nested forms.




Cookbook:
    :ref:`nested-forms`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/form/form.html`
    See :ref:`template <template>`


`title`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`write_nested_form_to_instance`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Write the nested_form to the instance.

This is analogous to `Field.write_to_instance` but for nested forms.




Cookbook:
    :ref:`nested-forms`


Shortcuts
---------

`Form.create`
^^^^^^^^^^^^^

Parent: Form.crud_

Defaults
++++++++

* `actions__submit__post_handler`
    * `iommi.form.create_object__post_handler`
* `extra__is_create`
    * `True`

`Form.create_or_edit`
^^^^^^^^^^^^^^^^^^^^^

Parent: Form.crud_

Defaults
++++++++

* `actions__submit__post_handler`
    * `iommi.form.create_or_edit_object__post_handler`
* `extra__is_create`
    * `None`


Cookbook:
    :ref:`create-or-edit-forms`

`Form.crud`
^^^^^^^^^^^

Defaults
++++++++

* `extra__pre_save_all_but_related_fields`
    * `lambda **kwargs: None, # pragma: no mutate`
* `extra__on_save_all_but_related_fields`
    * `lambda **kwargs: None, # pragma: no mutate`
* `extra__pre_save`
    * `lambda **kwargs: None, # pragma: no mutate`
* `extra__on_save`
    * `lambda **kwargs: None, # pragma: no mutate`
* `extra__on_delete`
    * `lambda **kwargs: None, # pragma: no mutate`
* `extra__redirect`
    * `lambda redirect_to, **_: HttpResponseRedirect(redirect_to)`
* `extra__redirect_to`
    * `None`
* `extra__crud_type`
    * `lambda form, **_: 'create' if form.instance is None else 'edit'`
* `extra__new_instance`
    * `lambda form, **_: form.model()`
* `auto`
    * `Namespace()`

`Form.delete`
^^^^^^^^^^^^^

Parent: Form.crud_

Defaults
++++++++

* `actions__submit__call_target__attribute`
    * `delete`
* `actions__submit__post_handler`
    * `iommi.form.delete_object__post_handler`
* `extra__crud_type`
    * `delete`
* `editable`
    * `False`
* `fields__iommi_default_text`
    * `{'call_target': <class 'iommi.fragment.Fragment'>, 'include': <function Form.<lambda> at 0x7c9e449cfba0>, 'after': 0, 'tag': 'p', 'children__text': <function Form.<lambda> at 0x7c9e449d4180>}`

`Form.edit`
^^^^^^^^^^^

Parent: Form.crud_

Defaults
++++++++

* `actions__submit__post_handler`
    * `iommi.form.edit_object__post_handler`
* `extra__is_create`
    * `False`

Methods
-------

`add_error`
^^^^^^^^^^^



Explicitly add an error message to the form's global error set.

Example:

.. code-block:: python

    def post_validation(form, **_):
        form.add_error('global error')

    form = Form.create(
        auto__model=Album,
        post_validation=post_validation,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('63de18b0-ad19-4479-a31b-3f1ceb966760', this)">▼ Hide result</div>
    <iframe id="63de18b0-ad19-4479-a31b-3f1ceb966760" src="doc_includes/Form/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`apply`
^^^^^^^



Write the new values specified in the form into the instance specified.



`as_view`
^^^^^^^^^

`get_errors`
^^^^^^^^^^^^



Get a dict containing two keys:

- `global` for errors global to the entire form.
- `fields` for errors specific to fields. This is itself a dict with a key for each field.



`get_field`
^^^^^^^^^^^

`get_nested_form`
^^^^^^^^^^^^^^^^^

`is_target`
^^^^^^^^^^^

`is_valid`
^^^^^^^^^^



Is the form valid?  Can be called inside forms post_validation hook to determine if the
individual fields were all valid.



`next_value`
^^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`validate`
^^^^^^^^^^

Static methods
--------------

`apply_field`
^^^^^^^^^^^^^

Class methods
-------------

`fields_from_model`
^^^^^^^^^^^^^^^^^^^





FormAutoConfig
==============

Base class: `AutoConfig`

Refinable members
-----------------


`default_included`
^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`show-fields`


`exclude`
^^^^^^^^^

A list of attribute names to exclude, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`

Type: `list[str] | None`


Cookbook:
    :ref:`show-fields`


`include`
^^^^^^^^^

A list of attribute names to include, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`. A list item may also be a dict carrying the attribute path under its `attr` key, with the remaining keys passed as additional configuration to that entry. Example: `['album', dict(attr='album__year', display_name='Year')]`

Type: `list[str | dict] | None`

    See :ref:`include <include>`


Cookbook:
    :ref:`show-fields`


`instance`
^^^^^^^^^^

An instance of a Django model. If this field is specified, the `model` attribute will be automatically derived. This cannot be a callable, in that case set `model` and use `instance=lambda...` instead of `auto__instance`.


Cookbook:
    :ref:`form-redirect`

    :ref:`field-non-editable`

    :ref:`reverse-fk-form`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Django model class

Type: `type[Model] | None`


Cookbook:
    :ref:`form-save-hooks`

    :ref:`show-fields`


`type`
^^^^^^


Cookbook:
    :ref:`create-or-edit-forms`





Fragment
========

Base class: :doc:`Part`

.. _Fragment:

`Fragment` is a class used to build small HTML fragments that plug into iommi's structure.

.. code-block:: python

    h1 = Fragment(children__text='Tony', tag='h1')

    # There is also a shorthand version that is identical to the above:
    h1 = Fragment('Tony', tag='h1')

It's easiest to use via the html builder:

.. code-block:: python

    h1 = html.h1('Tony')

Fragments are useful because attrs, template and tag are evaluated, so if
you have a `Page` with a fragment in it you can configure it later:

.. code-block:: python

    class MyPage(Page):
        header = html.h1(
            'Hi!',
            attrs__class__staff=
                lambda request, **_: request.user.is_staff,
        )

Rendering a `MyPage` will result in a `<h1>`, but if you do
`MyPage(parts__header__tag='h2')` it will be rendered with a `<h2>`.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`override-part-of-page`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Cookbook:
    :ref:`field-input-template`


Methods
-------

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`render_text_or_children`
^^^^^^^^^^^^^^^^^^^^^^^^^





Header
======

Base class: :doc:`Fragment`

`Header` is a special fragment that automatically calculates its level.
This means that you will get `h1` for the top level, `h2` for the next level,
and so on. If you want a specific `h1`/`h2`/etc tag use `Fragment`.

The header level is only increased by the existence of `Header` objects,
so putting a manual `h1` somewhere won't make the next `Header` into a
`h2` tag.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`fragment-children`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Cookbook:
    :ref:`table-as-div`


Methods
-------

`on_bind`
^^^^^^^^^





HeaderConfig
============

Base class: :doc:`Traversable`

Refinable members
-----------------


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


Cookbook:
    :ref:`stop-header-render`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Methods
-------

`render`
^^^^^^^^





M
=

See the :ref:`MainMenu <mainmenu>` docs and the :ref:`MainMenu cookbook <cookbook-main-menu>`.

Constructor arguments
+++++++++++++++++++++

* `icon`
* `view`
* `view_kwargs`
* `path`
* `url`
* `open`
* `params`
* `display_name`
* `items`
* `include`
* `attrs`
* `template`
* `paths`
* `extra`
* `extra_evaluated`
* `render`

Methods
-------

`bind`
^^^^^^

`urlpatterns`
^^^^^^^^^^^^^





MainMenu
========

See the :ref:`MainMenu <mainmenu>` docs and the :ref:`MainMenu cookbook <cookbook-main-menu>`.

Constructor arguments
+++++++++++++++++++++

* `items`
* `attrs`
* `template`
* `paths`
* `extra`
* `extra_evaluated`

Methods
-------

`bind`
^^^^^^

`urlpatterns`
^^^^^^^^^^^^^





Members
=======

Base class: :doc:`Traversable`

Internal iommi class that holds members of another class, for example the columns of a `Table` instance.

Refinable members
-----------------


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


Methods
-------

`on_bind`
^^^^^^^^^





Menu
====

Base class: `MenuBase`

Class that describes menus.

Example:

.. code-block:: python

    menu = Menu(
        sub_menu=dict(
            root=MenuItem(url='/'),

            albums=MenuItem(url='/albums/'),

            # url defaults to /<name>/ so we
            # don't need to write /musicians/ here
            musicians=MenuItem(),
        ),
    )

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`items_container`
^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`cookbook-menu`


`sort`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `False`

Cookbook:
    :ref:`cookbook-menu`


`sub_menu`
^^^^^^^^^^

Type: `dict`


Cookbook:
    :ref:`cookbook-menu`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Methods
-------

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`set_active`
^^^^^^^^^^^^

`validate`
^^^^^^^^^^





MenuItem
========

Base class: `MenuBase`

Class that is used for the clickable menu items in a menu.

See :doc:`Menu` for more complete examples.

Refinable members
-----------------


`a`
^^^


Cookbook:
    :ref:`cookbook-menu`


`active_class`
^^^^^^^^^^^^^^


Cookbook:
    :ref:`cookbook-menu`


`active_class_on_item`
^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`cookbook-menu`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`display_name`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `lambda menu_item, **_: capitalize(menu_item.iommi_name()).replace('_', ' ')`
    See :ref:`name <name>`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`group`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`cookbook-menu`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`regex`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `lambda menu_item, **_: '^' + str(menu_item.url) if menu_item.url else None`

Cookbook:
    :ref:`cookbook-menu`


`sort`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`cookbook-menu`


`sub_menu`
^^^^^^^^^^

Type: `dict`


Cookbook:
    :ref:`cookbook-menu`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


`url`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `lambda menu_item, **_: (       '/' + path_join(getattr(menu_item.iommi_parent(), 'url', None), menu_item.iommi_name()) + '/'     )`

Cookbook:
    :ref:`cookbook-menu`


Methods
-------

`on_bind`
^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^





Page
====

Base class: :doc:`Part`

A page is used to compose iommi parts into a bigger whole.

See the `howto <https://docs.iommi.rocks//cookbook_parts_pages.html#parts-pages>`_ for example usages.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`context`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`context-of-page`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`h_tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`member_class`
^^^^^^^^^^^^^^

Type: `type[Fragment]`


Cookbook:
    :ref:`custom-member-class`


`parts`
^^^^^^^

Type: `dict[str, Part | str | Template]`


Cookbook:
    :ref:`override-part-of-page`


`title`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

    See :ref:`title <title>`


Cookbook:
    :ref:`title-of-page`


Methods
-------

`as_view`
^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^





Panel
=====

Base class: :doc:`Fragment`

Class used to define form and table row layouts. See :ref:`the forms cookbook <complex-layouts-forms>` and :ref:`the table cookbook <complex-layouts-tables>`.

Refinable members
-----------------


`_parent_form`
^^^^^^^^^^^^^^


Cookbook:
    :ref:`field-write-to-instance`


`_parent_table`
^^^^^^^^^^^^^^^


Cookbook:
    :ref:`complex-layouts-tables`


`_parent_table_cells`
^^^^^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`complex-layouts-tables`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`field-write-to-instance`


`col`
^^^^^


Cookbook:
    :ref:`field-write-to-instance`


`col_class`
^^^^^^^^^^^

Type: `type[PanelCol]`


Cookbook:
    :ref:`field-write-to-instance`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`fieldset_legend`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`field-write-to-instance`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`nested_path`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`field-write-to-instance`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Shortcuts
---------

`Panel.alert`
^^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`
* `attrs__role`
    * `alert`
* `attrs__class__alert`
    * `True`

`Panel.card`
^^^^^^^^^^^^

eg. for bootstrap div.card



Defaults
++++++++

* `tag`
    * `div`
* `attrs__class__card`
    * `True`
* `template`
    * `iommi/form/panel_card.html`

`Panel.card_footer`
^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`
* `attrs__class__card-footer`
    * `True`

`Panel.card_header`
^^^^^^^^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`
* `attrs__class__card-header`
    * `True`

`Panel.cell`
^^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `None`

`Panel.div`
^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`

`Panel.field`
^^^^^^^^^^^^^

generates form field



Defaults
++++++++

* `tag`
    * `None`

`Panel.fieldset`
^^^^^^^^^^^^^^^^

generates <fieldset><legend>{legend}</legend>{subfields/subpanels}</fieldset>



Defaults
++++++++

* `tag`
    * `fieldset`
* `template`
    * `iommi/form/panel_fieldset.html`

`Panel.nested_form`
^^^^^^^^^^^^^^^^^^^

generates nested form



Defaults
++++++++

* `tag`
    * `None`

`Panel.part`
^^^^^^^^^^^^

for non-field parts/fragments
you don't need to call this by hand, non-field children of rows/fieldsets get wrapped automatically



Defaults
++++++++

* `tag`
    * `None`

`Panel.reorder_handle`
^^^^^^^^^^^^^^^^^^^^^^

Parent: Panel.cell_

Defaults
++++++++

* `tag`
    * `span`
* `attrs__title`
    * `Drag and drop to reorder`
* `attrs__class__reordering-handle-cell`
    * `True`
* `attrs__data-iommi-reordering-handle`
    * `True`

`Panel.row`
^^^^^^^^^^^

generates div.row



Defaults
++++++++

* `tag`
    * `div`
* `attrs__class__row`
    * `True`

Methods
-------

`as_dict`
^^^^^^^^^

`get_cell_panels`
^^^^^^^^^^^^^^^^^


recursively gets all cells from the panel


`get_fields`
^^^^^^^^^^^^


recursively gets all fields from the panel


`on_bind`
^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^





PanelCol
========

Base class: :doc:`Fragment`

Generates `div.col` - for wrapping all children of `Panel.row`.

See :ref:`the forms cookbook <complex-layouts-forms>` and :ref:`the table cookbook <complex-layouts-tables>`.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


`children`
^^^^^^^^^^


Cookbook:
    :ref:`field-write-to-instance`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Default: `div`
    See :ref:`tag <tag>`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`





Part
====

Base class: :doc:`Traversable`

`Part` is the base class for parts of a page that can be rendered as html, and can respond to ajax and post.

See the `howto <https://docs.iommi.rocks//cookbook_parts_pages.html#parts-pages>`_ for example usages.

Refinable members
-----------------


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `True`
    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


Methods
-------

`bind`
^^^^^^

`iommi_collected_assets`
^^^^^^^^^^^^^^^^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`perform_dispatch`
^^^^^^^^^^^^^^^^^^

`render_to_response`
^^^^^^^^^^^^^^^^^^^^





Query
=====

Base class: :doc:`Part`

Declare a query language. Example:

.. code-block:: python

    class AlbumQuery(Query):
        year = Filter.integer()
        name = Filter()

    query_set = Album.objects.filter(
        AlbumQuery().bind(request=request).get_q()
    )

Refinable members
-----------------


`advanced`
^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`advanced-query`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


Cookbook:
    :ref:`control-q`


`auto`
^^^^^^

Type: :doc:`QueryAutoConfig`

    See :ref:`auto <auto>`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`filter`
^^^^^^^^


Cookbook:
    :ref:`query-filter-rows`


`filters`
^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`query-filter-rows`


`form`
^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`initial-filter`


`form_class`
^^^^^^^^^^^^

Type: `type[Form]`


Cookbook:
    :ref:`custom-member-class`


`form_container`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`control-q`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`member_class`
^^^^^^^^^^^^^^

Type: `type[Filter]`


Cookbook:
    :ref:`custom-member-class`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`query-filter-rows`


`postprocess`
^^^^^^^^^^^^^


Cookbook:
    :ref:`query-filter-rows`


`rows`
^^^^^^


Cookbook:
    :ref:`query-filter-rows`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `div`
    See :ref:`tag <tag>`


Cookbook:
    :ref:`control-q`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

    See :ref:`template <template>`


Methods
-------

`get_advanced_query_param`
^^^^^^^^^^^^^^^^^^^^^^^^^^

`get_q`
^^^^^^^



Create a query set based on the data in the request.



`get_query_string`
^^^^^^^^^^^^^^^^^^



Based on the data in the request, return the equivalent query string that you can use with parse_query_string() to create a query set.



`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`parse_query_string`
^^^^^^^^^^^^^^^^^^^^

Class methods
-------------

`filters_from_model`
^^^^^^^^^^^^^^^^^^^^





QueryAutoConfig
===============

Base class: `AutoConfig`

Refinable members
-----------------


`default_included`
^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`query-auto-config`


`exclude`
^^^^^^^^^

A list of attribute names to exclude, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`

Type: `list[str] | None`


Cookbook:
    :ref:`query-auto-config`


`include`
^^^^^^^^^

A list of attribute names to include, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`. A list item may also be a dict carrying the attribute path under its `attr` key, with the remaining keys passed as additional configuration to that entry. Example: `['album', dict(attr='album__year', display_name='Year')]`

Type: `list[str | dict] | None`

    See :ref:`include <include>`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Django model class

Type: `type[Model] | None`


Cookbook:
    :ref:`query-auto-config`


`rows`
^^^^^^

A `QuerySet` object. If this field is specified, the `model` attribute will be automatically derived. This cannot be a callable, in that case set `model` and use `rows=lambda...` instead of `auto__rows`.


Cookbook:
    :ref:`query-auto-config`





Style
=====

Constructor arguments
+++++++++++++++++++++

* `bases`
* `base_template`
* `content_block`
* `root`
* `internal`
* `sub_styles`
* `icon_formatter`
* `kwargs`

Methods
-------

`resolve`
^^^^^^^^^



Calculate the namespaces of additional argument that should be applied
to the given object. If is_root is set to True, assets might also be
added to the namespace.





Table
=====

Base class: :doc:`Part`

Describe a table. Example:

.. code-block:: python

    class AlbumTable(Table):
        name = Column()
        artist = Column()

        class Meta:
            sortable = False

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('61b475e7-d462-4e59-a5ff-1398ce75d395', this)">▼ Hide result</div>
    <iframe id="61b475e7-d462-4e59-a5ff-1398ce75d395" src="doc_includes/Table/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Refinable members
-----------------


`action_class`
^^^^^^^^^^^^^^

Type: `type[Action]`


Cookbook:
    :ref:`table-internal-classes`


`actions`
^^^^^^^^^

Type: `dict[str, Action]`


Cookbook:
    :ref:`table-as-csv`

    :ref:`custom-actions`


`actions_below`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

Default: `False`

Cookbook:
    :ref:`actions-below-table`


`actions_template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/form/actions.html`

Cookbook:
    :ref:`actions-below-table`


`after`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int | str`

    See :ref:`after <after>`


`assets`
^^^^^^^^

Type: `Namespace`

    See :ref:`assets <assets>`


`attrs`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

dict of strings to string/callable of HTML attributes to apply to the table

Type: :doc:`Attrs`

    See :ref:`attributes <attributes>`


Cookbook:
    :ref:`freetext-column`


`auto`
^^^^^^

Type: :doc:`TableAutoConfig`

    See :ref:`auto <auto>`


Cookbook:
    :ref:`fk-related-data-access`

    :ref:`nested-fk`


`bulk`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Form | None`


Cookbook:
    :ref:`bulk-delete`

    :ref:`custom-bulk-action`


`bulk_container`
^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`post-bulk-edit`


`bulk_exclude`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

exclude filters to apply to the `QuerySet` before performing the bulk operation

Type: `Namespace`

Default: `{}`

Cookbook:
    :ref:`post-bulk-edit`


`bulk_filter`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

filters to apply to the `QuerySet` before performing the bulk operation

Type: `Namespace`

Default: `{}`

Cookbook:
    :ref:`post-bulk-edit`


`cell`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `CellConfig`


Cookbook:
    :ref:`table-as-div`


`cells_class`
^^^^^^^^^^^^^

Type: `type[Cells]`


Cookbook:
    :ref:`table-internal-classes`


`columns`
^^^^^^^^^

(use this only when not using the declarative style) a list of Column objects

Type: `dict[str, Column]`


Cookbook:
    :ref:`cell-link`

    :ref:`reorder-columns`

    :ref:`column-computed-data`


`container`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`arbitrary-html`


`default_sort_order`
^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`default-sort-order`


`empty_message`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`table-as-div`


`endpoints`
^^^^^^^^^^^

Type: `Namespace`

    See :ref:`endpoints <endpoints>`


Cookbook:
    :ref:`table-as-csv`


`extra`
^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


`extra_evaluated`
^^^^^^^^^^^^^^^^^

Type: `dict[str, Any]`

    See :ref:`extra <extra>`


Cookbook:
    :ref:`table-as-csv`


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`form_class`
^^^^^^^^^^^^

Type: `type[Form]`


Cookbook:
    :ref:`custom-member-class`


`h_tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `Fragment | str`

    See :ref:`title <title>`


`header`
^^^^^^^^

Default: `Namespace()`

Cookbook:
    :ref:`table-as-div`

    :ref:`stop-header-render`

    :ref:`turn-off-header`


`include`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `bool`

    See :ref:`include <include>`


`invalid_form_message`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`


Cookbook:
    :ref:`table-invalid-form-message`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


`member_class`
^^^^^^^^^^^^^^

Type: `type[Column]`


Cookbook:
    :ref:`custom-member-class`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `type[Model] | None`


Cookbook:
    :ref:`table-model-introspection`


`outer`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`arbitrary-html`


`page_class`
^^^^^^^^^^^^

Type: `type[Page]`


Cookbook:
    :ref:`table-internal-classes`


`page_size`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `int`

Default: `16`

Cookbook:
    :ref:`turn-off-pagination`


`parts`
^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`turn-off-pagination`


`post_bulk_edit`
^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`post-bulk-edit`


`preprocess_row`
^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-as-div`


`preprocess_rows`
^^^^^^^^^^^^^^^^^


Cookbook:
    :ref:`table-as-div`


`query`
^^^^^^^

Type: `Query | None`


Cookbook:
    :ref:`initial-filter`


`query_class`
^^^^^^^^^^^^^

Type: `type[Query]`


Cookbook:
    :ref:`custom-member-class`


`query_from_indexes`
^^^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`query-from-indexes`


`row`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `RowConfig`


Cookbook:
    :ref:`customize-rendering-row`


`row_group_class`
^^^^^^^^^^^^^^^^^

Type: `type[RowGroup]`


Cookbook:
    :ref:`table-internal-classes`


`rows`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

a list or QuerySet of objects


Cookbook:
    :ref:`additional-rows`


`sortable`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

set this to `False` to turn off sorting for all columns

Type: `bool`

Default: `True`

Cookbook:
    :ref:`table-sorting`


`sorter`
^^^^^^^^


Cookbook:
    :ref:`custom-sort-key`


`superheader`
^^^^^^^^^^^^^

Type: `Namespace`


Cookbook:
    :ref:`superheader`


`table_tag_wrapper`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`table-tag-wrapper`


`tag`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str`

Default: `table`
    See :ref:`tag <tag>`


Cookbook:
    :ref:`table-as-div`


`tbody`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: :doc:`Fragment`


Cookbook:
    :ref:`table-as-div`


`template`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | Template`

Default: `iommi/table/table.html`
    See :ref:`template <template>`


`title`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Type: `str | None`

    See :ref:`title <title>`


Shortcuts
---------

`Table.div`
^^^^^^^^^^^

Defaults
++++++++

* `tag`
    * `div`
* `tbody__tag`
    * `div`
* `cell__tag`
    * `None`
* `row__tag`
    * `div`
* `header__template`
    * `None`

Methods
-------

`as_view`
^^^^^^^^^

`bulk_queryset`
^^^^^^^^^^^^^^^


Return the queryset that contains only the selected rows with
        bulk_filter and bulk_exclude applied.

        For use in post_handlers. Only valid when rows was a queryset.



`cells_for_rows`
^^^^^^^^^^^^^^^^


Yield a Cells instance for each visible row on the screen.


`get_visible_rows`
^^^^^^^^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^

`selection`
^^^^^^^^^^^


Return the selected rows.

        For use in post_handlers. It's a queryset if rows is a queryset and a list otherwise.
        Unlike bulk_queryset neither bulk_filter nor bulk_exclude are applied.



`should_render_form_tag`
^^^^^^^^^^^^^^^^^^^^^^^^

Class methods
-------------

`columns_from_model`
^^^^^^^^^^^^^^^^^^^^





TableAutoConfig
===============

Base class: `AutoConfig`

Refinable members
-----------------


`default_included`
^^^^^^^^^^^^^^^^^^

Type: `bool`


Cookbook:
    :ref:`show-columns`


`exclude`
^^^^^^^^^

A list of attribute names to exclude, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`

Type: `list[str] | None`


Cookbook:
    :ref:`show-columns`


`include`
^^^^^^^^^

A list of attribute names to include, use `__` to drill down to nested attributes. Example: `['album', 'album__year']`. A list item may also be a dict carrying the attribute path under its `attr` key, with the remaining keys passed as additional configuration to that entry. Example: `['album', dict(attr='album__year', display_name='Year')]`

Type: `list[str | dict] | None`

    See :ref:`include <include>`


Cookbook:
    :ref:`nested-fk`

    :ref:`show-columns`


`model`       (:ref:`evaluated <evaluate>`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A Django model class

Type: `type[Model] | None`


Cookbook:
    :ref:`cell-link`

    :ref:`filter-column`

    :ref:`group-columns`

    :ref:`freetext-column`

    :ref:`show-columns`

    :ref:`column-computed-data`

    :ref:`turn-off-pagination`

    :ref:`reorder-columns`


`rows`
^^^^^^

A `QuerySet` object. If this field is specified, the `model` attribute will be automatically derived. This cannot be a callable, in that case set `model` and use `rows=lambda...` instead of `auto__rows`.


Cookbook:
    :ref:`group-rows`





Traversable
===========

Base class: `RefinableObject`

Abstract API for objects that have a place in the iommi path structure.
You should not need to care about this class as it is an implementation
detail.

Refinable members
-----------------


`extra_params`
^^^^^^^^^^^^^^

    See :ref:`extra_params <extra_params>`


`iommi_style`
^^^^^^^^^^^^^

Type: `str | Style | None`

    See :ref:`iommi_style <iommi_style>`


Methods
-------

`apply_style`
^^^^^^^^^^^^^

`bind`
^^^^^^

`get_context`
^^^^^^^^^^^^^

`get_request`
^^^^^^^^^^^^^

`invoke_callback`
^^^^^^^^^^^^^^^^^

`iommi_bound_members`
^^^^^^^^^^^^^^^^^^^^^

`iommi_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

`iommi_name`
^^^^^^^^^^^^

`iommi_parent`
^^^^^^^^^^^^^^

`iommi_root`
^^^^^^^^^^^^

`on_bind`
^^^^^^^^^

`on_refine_done`
^^^^^^^^^^^^^^^^

`own_evaluate_parameters`
^^^^^^^^^^^^^^^^^^^^^^^^^





Functions
=========

The classes iommi exposes are documented one page each under
:doc:`api`. This page covers the module level functions.

Most of these are *registrations*: you call them once at startup (typically in
the `ready` method of an `AppConfig`) to teach iommi about your code base. For
why you would want to, see :doc:`registrations` and :doc:`semantic_models`.


Model introspection
-------------------

These tell iommi which shortcut to use when it generates a `Column`, `Field` or
`Filter` from a Django model field. See :doc:`registrations` for how to choose
between them, and :doc:`auto` for the generation they affect.

`register_factory(django_field_class, *, shortcut_name=MISSING, factory=MISSING, **kwargs)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register the handling of a Django field class for `Column`, `Field` and `Filter`
at once. Pass either `shortcut_name` (the name of a shortcut to call) or
`factory` (a `Shortcut` instance or a callable returning one). Register `None`
to make iommi ignore the field type.

`register_column_factory` / `register_field_factory` / `register_filter_factory` / `register_edit_column_factory`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Same signature as `register_factory`, but each affects only one of `Column`,
`Field`, `Filter` and `EditColumn`. Use these when the three need to differ.

`register_related_factory(model, *, shortcut_name=MISSING, factory=MISSING, **kwargs)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register handling of `ForeignKey` and `OneToOneField` by their *related* model
rather than by field class. There are also
`register_related_column_factory`, `register_related_field_factory` and
`register_related_filter_factory` for the single-class versions.

`register_related_multiple_factory(model, *, shortcut_name=MISSING, factory=MISSING, **kwargs)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As above, for `ManyToManyField` and one-to-many (reverse foreign key). There are
also `register_related_multiple_column_factory`,
`register_related_multiple_field_factory` and
`register_related_multiple_filter_factory`.

`register_search_fields(*, model, search_fields, allow_non_unique=False, overwrite=False)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Declare which model fields `Query` uses to find an object by name, so the
advanced query language can say `album=Heaven` instead of `album.pk=42`.
`search_fields` accepts `__` separated paths. Pass `allow_non_unique=True` when
the fields don't uniquely identify a row.


Rendering
---------

`register_cell_formatter(type_or_class, formatter)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register how a value of a given type renders in a table cell. `formatter` is
called with the keyword arguments `table`, `column`, `row` and `value`.

`register_style(name, style, allow_overwrite=False)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register a :doc:`Style` under `name` so it can be referenced as a string by
`IOMMI_DEFAULT_STYLE` and `iommi_style`. Returns a context manager, which makes
it convenient in tests. See :doc:`styles`.

`html`
~~~~~~

Not a function but a fragment builder object. `html.div('foo')` is a shorter way
to write `Fragment(tag='div', children__text='foo')`, and any tag name works.
See :doc:`fragments`.

`M`
~~~

Shorthand for declaring a :doc:`MainMenu` item. See :doc:`main_menu` and the
:ref:`main menu cookbook <cookbook-main-menu>`.


Path decoding
-------------

See :doc:`path` for the full picture.

`register_path_decoding(**kwargs)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Register decoders for URL path components. Each keyword is the name you will
use in your url pattern, and the value is a model (decoded by pk), a model
field (decoded by that field), a callable, or a `PathDecoder`:

.. code-block:: python

    register_path_decoding(
        artist_pk=Artist,
        artist_name=Artist.name,
        album_pk=PathDecoder(
            decode=lambda string, **_: Album.objects.get(pk=string),
            name='album',
        ),
    )

`PathDecoder(*, decode=None, model=None, name)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An explicit decoder. `decode` is a callable receiving `string`, `request`,
`decoded_kwargs` and `kwargs`; `name` is the keyword argument the decoded object
is delivered under. Useful for lookups Django's path converters can't express,
and for access control.

`register_explicit_path_decoding(**kwargs)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lower level version of `register_path_decoding` that takes only `PathDecoder`
instances, with no shorthand.

`decode_path(f)`
~~~~~~~~~~~~~~~~

Decorator that applies iommi's path decoders to a plain Django function based
view, so it receives decoded objects as arguments:

.. code-block:: python

    @decode_path
    def my_view(request, artist, album):
        return artist, album

The raw and decoded values are both available on `request.iommi_view_params`.


Bundled views
-------------

See :doc:`views` for what these render.

`crud_views(*, model, table=EMPTY, create=EMPTY, edit=EMPTY, delete=EMPTY, detail=EMPTY)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Returns an `include()` of list, create, detail, edit and delete views for
`model`. The `table`, `create`, `edit`, `delete` and `detail` namespaces are
passed through to the underlying `Table`/`Form`, so you can configure any of
them, e.g. `crud_views(model=Album, table__page_size=10)`:

.. code-block:: python

    urlpatterns = [
        path('albums/', crud_views(model=Album)),
    ]

`auth_views()`
~~~~~~~~~~~~~~

Returns an `include()` of `login/`, `logout/` and `change_password/` views:

.. code-block:: python

    urlpatterns = [
        path('', auth_views()),
    ]

`middleware(get_response)`
~~~~~~~~~~~~~~~~~~~~~~~~~~

iommi's middleware, which lets a view return an iommi object directly. See
:doc:`middleware`. Must be last in `MIDDLEWARE`.

`iommi_render(view)`
~~~~~~~~~~~~~~~~~~~~

Decorator that renders the iommi object returned by a single view, for when you
don't want to install the middleware globally.


.. _test-helpers:

Test helpers
------------

From `iommi.test_helpers`. See :doc:`testing` for how to use these.

`do_post(form, do_post_key_validation=True, request_builder=req, **user_data)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Simulate a user filling out `form` and submitting it. Renders the form, extracts
the default post data, merges `user_data` on top, and returns the form bound to
the resulting POST request. Requires a form with a post target, so use
`.create()`, `.edit()` or `.delete()`.

Every key in `user_data` must exist in the rendered form; pass
`do_post_key_validation=False` to allow keys that aren't plain fields.

`req(method, url='/', **data)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Build a request with an anonymous user.

`user_req(method, **data)`
~~~~~~~~~~~~~~~~~~~~~~~~~~

Build a request from a normal authenticated user.

`staff_req(method, **data)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Build a request from an authenticated staff/superuser.

`extract_form_data(content)`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Extract the default form data from rendered HTML. Used by `do_post`.





middleware
==========

Constructor arguments
+++++++++++++++++++++

* `get_response`

Methods
-------

`process_view`
^^^^^^^^^^^^^^



Common config
=============

Many configuration options are common across iommi, forming part of the cohesive structure which makes it easy to transfer your skills from one part of iommi to another. Rather than repeating them on every class in :doc:`api`, they get a page each here.

The most important is `include`, which is the command you use to include or exclude a part from an iommi component, for example removing a field from a form or including a field that by default would be hidden (like the primary key for forms and tables).

`attr` and `attrs` are easy to confuse, so it's important to understand the difference between them.

`auto` is used to generate forms, tables, etc from models.

.. toctree::

    after
    assets
    attr
    attributes
    auto
    endpoints
    extra
    extra_params
    include
    iommi_style
    name
    tag
    template
    title



.. _after:

`after`
-------

Ordering of fields and columns is based on the declared order, the order in the model (when using :ref:`auto`), and the `after` configuration. The last takes precedence over the others.

To order fields, set `after` to:

- `field_name` to place after the named field
- `>field_name` to place after the named field
- `<field_name` to place before the named field
- an integer index
- the special value `LAST` to put a field last

Using `after` is especially useful when you already have a complex object that you want to add one or a few fields to in some specific position.



.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__after=LAST,
        fields__year__after='artist',
        fields__artist__after=0,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('38d89813-9095-416f-96b5-6a31853f2818', this)">▼ Hide result</div>
    <iframe id="38d89813-9095-416f-96b5-6a31853f2818" src="doc_includes/after/test_after.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

This will make the field order `artist`, `year`, `name`.

If there are multiple fields with the same index or name the order of the fields will be used to disambiguate.



.. _assets:


`assets`
--------

Assets are meant to be the elements that you refer
to in the `<head>` tag of your document such as links to scripts, style sheets, and
inline scripts or css.

Every :doc:`Part` can include the assets it needs. Similarly :doc:`Style` can include assets.
When a part is rendered all assets are automatically collected and included in the `<head>` of the document.

Because assets have names (:doc:`Everything has a name <philosophy>`), assets with the same name will overwrite
each other, resulting in only one asset with a given name being rendered.

You can remove an asset by passing `None` as the value.





.. _attr:

`attr`
------

`attr` is the configuration for specifying what Python attribute is read from or written to. Set it to `None` to make a `Field`/`Column`/etc that does not write or read from an attribute on the objects it works on. This is useful for displaying computed data without needing to pollute your model class with single use methods.

`attr` defaults to the `name`, so this:

.. code-block:: python

    class MyForm(Form):
        foo = Field()

is the same as:

.. code-block:: python

    class MyForm(Form):
        foo = Field(attr='foo')

`attr` values can be dunder paths:

.. code-block:: python

    class TrackTable(Table):
        artist_name = Column(attr='album__artist__name')

        class Meta:
            auto__model = Track
            auto__include = []

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a1a2b518-636f-4da8-94ce-f2ff7d4b7956', this)">▼ Hide result</div>
    <iframe id="a1a2b518-636f-4da8-94ce-f2ff7d4b7956" src="doc_includes/attr/test_attr_dunder_paths.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

(Although this example is more idiomatically written with `auto`)



.. _attributes:

`attrs`
-------

The `attrs` namespace is used to customize the rendering of HTML attributes.

For example, in this form we add a custom attribute, a CSS class and an inline style specification:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__artist__attrs__foo='bar',
        fields__name__attrs__class__bar=True,
        fields__name__attrs__style__baz='qwe',
    )

or more succinctly:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__artist__attrs__foo='bar',
        fields__name__attrs=dict(
            class__bar=True,
            style__baz='qwe',
        )
    )

The thing to remember is that the basic namespace is a dict with key value
pairs that gets projected out into the HTML, but there are two special cases
for `style` and `class`. The example above will result in the following
attributes on the field tag:

.. code-block:: html

   <div foo="bar" class="bar" style="baz: qwe">

The values in these dicts can be callables:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__name__attrs__class__bar=
            lambda request, **_: request.user.is_staff,
    )

Note that the class names are sorted alphabetically on render.


If you need to add a style with `-` in the name you have to do this:


.. code-block:: pycon

    >>> render_attrs(Namespace(**{'style__font-family': 'sans-serif'}))
    ' style="font-family: sans-serif"'





.. _auto:

`auto`
------

The `auto` configuration namespace is used to generate forms/tables/etc from Django models. The simplest example is:

.. code-block:: python

    form = Form(auto__model=Album)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('91c316cd-8a1a-4be8-8b32-43b15cd677cf', this)">▼ Hide result</div>
    <iframe id="91c316cd-8a1a-4be8-8b32-43b15cd677cf" src="doc_includes/auto/test_auto.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

By default you will get all fields from the model except the primary key. You can use `include` to include it again:

.. code-block:: python

    form = Form(
        auto__model=Album,
        fields__pk__include=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('f3d8d00b-3480-4f98-8213-22b4f2ce61fe', this)">▼ Hide result</div>
    <iframe id="f3d8d00b-3480-4f98-8213-22b4f2ce61fe" src="doc_includes/auto/test_auto1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You can specify which model fields to include via `auto__include` to include just the fields you want, or `auto__exclude` to take all fields except some excluded fields. Fields/columns/etc can be excluded/included later using `include` on the field:

.. code-block:: python

    form = Form(
        auto__model=Album,
        auto__include=['name', 'artist', 'year'],
        fields__name__include=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4cb02d0c-bfa5-440a-9cca-98358b3ba2a6', this)">▼ Hide result</div>
    <iframe id="4cb02d0c-bfa5-440a-9cca-98358b3ba2a6" src="doc_includes/auto/test_auto2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

An item in the `auto__include` list can also be a dict. The `attr` key is the field to include (just like the plain string form), and the remaining keys are extra configuration passed to that field/column/etc. This is a more compact alternative to configuring each generated member separately via `fields__<name>__...`:

.. code-block:: python

    form = Form(
        auto__model=Album,
        auto__include=[
            dict(attr='name', display_name='Album name'),
            'artist',
            dict(attr='year', help_text='The year the album was released'),
        ],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('22d9c58c-c8a3-49fe-b759-d383fb76c357', this)">▼ Hide result</div>
    <iframe id="22d9c58c-c8a3-49fe-b759-d383fb76c357" src="doc_includes/auto/test_auto3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



.. _endpoints:

`endpoints`
-----------

You can add arbitrary `GET` endpoints with the `endpoints` namespace on any :doc:`Part`.


An endpoint can return an `HttpResponse` directly, or a `Part` (which is
rendered for you); everything else we try to dump to json for you.

Example:



.. code-block:: python

    page = Page(
        parts__h1=html.h1('Hi!'),
        endpoints__echo__func=lambda value, **_: value,
    )

This page will respond to `?/echo=foo` by returning a json response `"foo"`.





.. _extra:

.. _extra_evaluated:

`extra` and `extra_evaluated`
=============================

Very often it's useful to add some little bit of data on the side that you need
later to customize something. We think it's important to support this use case
with minimal amounts of code. To do this we have `extra` and `extra_evaluated`.
This is your place to put whatever you want in order to extend iommi for a general
feature or just some simple one-off customization for a single view.

All `Part` derived classes have `extra` and `extra_evaluated` namespaces, for example:
`Page`, `Column`, `Table`, `Field`, `Form`, and `Action`.

You use `extra` to put some data you want as-is:

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        fields__name__extra__sounds_cool=True,
        extra__is_cool=True,
    )

Here we add `sounds_cool` to the `name` field, and the `is_cool` value to the
entire `Form`. We can then access these in e.g. a template:
`{{ form.fields.name.extra.sounds_cool }}` and `{{ form.extra.is_cool }}`.

`extra_evaluated` is useful when you want to use the iommi evaluation
machinery to get some dynamic behavior:

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        fields__name__extra_evaluated__sounds_cool=lambda request, **_: request.user.is_staff,
        extra_evaluated__is_cool=lambda request, **_: request.user.is_staff,
    )

These are accessed like this in the template: `{{ form.fields.name.extra_evaluated.sounds_cool }}`.



.. _extra_params:


`extra_params`
--------------



`extra_params` is used to provide extra parameters, on top of the parameters already provided by Django and the iommi path machinery:

.. code-block:: python

    def some_function(a, b):
        return a + b

    class IommiPage(Page):
        class Meta:
            @staticmethod
            def extra_params(request, a, b):
                return dict(
                    c=some_function(a, b),
                )

        content = Template('{{ params.a }} + {{ params.b }} = {{ params.c }}')

    iommi_view = IommiPage().as_view()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fb791a34-1480-45a1-a23f-a2deeb1f8e79', this)">▼ Hide result</div>
    <iframe id="fb791a34-1480-45a1-a23f-a2deeb1f8e79" src="doc_includes/extra_params/test_extra_params.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



.. _include:

`include`
---------

The `include` configuration is used to include or exclude parts programmatically. Let's start with a simple example of a table:



.. code-block:: python

    table = Table(
        auto__model=Album,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('bf38bb19-5486-4461-a5e0-5368ddd306ec', this)">▼ Hide result</div>
    <iframe id="bf38bb19-5486-4461-a5e0-5368ddd306ec" src="doc_includes/include/test_include.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

We could make the `name` column only visible for staff users:

.. code-block:: python

    table = Table(
        auto__model=Album,
        columns__name__include=lambda user, **_: user.is_staff,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('86ae6dae-6338-4946-860a-3b7ef24b59d6', this)">▼ Hide result</div>
    <iframe id="86ae6dae-6338-4946-860a-3b7ef24b59d6" src="doc_includes/include/test_include1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



.. _iommi_style:

`iommi_style`
-------------

The :ref:`style` system is what you normally use to specify how your product should look and behave, but sometimes you want something more limited for just one or a few places. You can then specify a :doc:`Style` object directly on a component:



.. code-block:: python

    from iommi.style_bootstrap5 import bootstrap5
    form = Form(
        auto__model=Album,
        iommi_style=Style(
            bootstrap5,  # Based on the bootstrap style
            Field=dict(
                input__attrs__style__background='blue',
            )
        )
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a7393985-3cf3-4be5-a5ad-13a6b45a5937', this)">▼ Hide result</div>
    <iframe id="a7393985-3cf3-4be5-a5ad-13a6b45a5937" src="doc_includes/iommi_style/test_iommi_style.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



.. _name:

.. _display_name:

.. _iommi_name:

.. _iommi_path:


`name`/`display_name`/`iommi_path`
-----------------------------------------------

The different name concepts in iommi can be confusing, but each has a logical place.



`name`
~~~~~~

The `name` is the name used in configuration for a part:

.. code-block:: python

    class MyTable(Table):
        foo = Column()

The `name` is "foo". 

There is a special situation when using deep dunder paths with :ref:`auto`:

.. code-block:: python

    table = Table(
        auto__model=Track,
        auto__include=[
            'album__artist__name',
        ],
    )

Here the `name` of the column is `album_artist_name`, with the double underscore collapsed down to single underscores. This is because otherwise iommi can't know if `__` means "enter the configuration namespace of the `Column` object, or if it means "traverse the foreign key to go from one model to another". So in this situation, to further configure the artist name column, you need the configuration path `columns__album_artist_name`.

`display_name`
~~~~~~~~~~~~~~

By default iommi will pick up `verbose_name` from your model if you use :ref:`auto`, and if there is no such information, it will take the `name` and capitalize it. If you want to override this you specify `display_name`:

.. code-block:: python

    table = Table(
        auto__model=Track,
        auto__include=[
            'album__artist__name',
        ],
        columns__album_artist_name__display_name='Hello',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('1e016c9e-0fda-4618-9f78-1fd743f5d678', this)">▼ Hide result</div>
    <iframe id="1e016c9e-0fda-4618-9f78-1fd743f5d678" src="doc_includes/name/test_display_name.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`iommi_path`
~~~~~~~~~~~~

The `iommi_path` is used in HTTP dispatching, so AJAX endpoints, and POST requests. Normally you don't need to use this yourself. These paths are `/` separated.

`iommi_dunder_path`
~~~~~~~~~~~~~~~~~~~
This is useful for finding the full path for an object. It's the value you get with the pick tool, and it's the same as `iommi_path` except `__` replaces `/`.



.. _tag:

`tag`
-----

The `tag` config is used to specify what HTML tag the component renders as. For example, you can take a `Table` and give it `tag='div'` to make it render not as `<table>` but as `<div>`. Of course, in that case you need to do the same for the row rendering.

This feature can be used to change the tag used for the :ref:`title` of a component. By default iommi uses :doc:`Header`, which is a special class that automatically infers if it should be `<h1>`, `<h2>`, `<h3>`, etc based on the nesting level. You can then override the `tag` to specify the exact HTML tag you want.



.. _template:

`template`
----------

With the :ref:`philosophy of escape hatches <escape-hatches>`, at the edge we enable replacing the entire rendering of components with the `template` config. You can use it in `Table` cells, to render table rows, to replace the rendering of fields, inputs, headers, and more. The `template` argument supports two types of values:



Template path
~~~~~~~~~~~~~

Strings are interpreted as template paths:

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        fields__name__template='test_template_as_path.html',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c943d8a5-e028-49b6-a6c9-d4168c742ad3', this)">▼ Hide result</div>
    <iframe id="c943d8a5-e028-49b6-a6c9-d4168c742ad3" src="doc_includes/template/test_template_as_path.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`Template` object
~~~~~~~~~~~~~~~~~

Pass a Django `Template` object to write the template code you want inline:

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        fields__name__template=Template('template contents <b>here</b>'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('4b47d887-ad42-4a3a-9e8d-7d99bc4648f1', this)">▼ Hide result</div>
    <iframe id="4b47d887-ad42-4a3a-9e8d-7d99bc4648f1" src="doc_includes/template/test_template_objects.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>



.. _title:

.. _h_tag:

`title`/`h_tag`
---------------

The `title` attribute is for setting the title or heading of a component. To customize the exact rendering you use `h_tag`.



`title`
~~~~~~~

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        title='Custom title',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('487aea1a-7458-4278-9bd2-b7c9d0deaa96', this)">▼ Hide result</div>
    <iframe id="487aea1a-7458-4278-9bd2-b7c9d0deaa96" src="doc_includes/title/test_template_as_path.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

`h_tag`
~~~~~~~

.. code-block:: python

    form = Form.create(
        auto__model=Artist,
        h_tag__attrs__style__background='blue',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ebb309eb-2fb6-439d-9a3c-427913aeeb7c', this)">▼ Hide result</div>
    <iframe id="ebb309eb-2fb6-439d-9a3c-427913aeeb7c" src="doc_includes/title/test_template_objects.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





Views
=====

iommi ships with some views for some common use cases:

Authorization
-------------
We have `login`, `logout`, and `change_password` views, and there's a function to get all patterns:

.. code-block:: python

    urlpatterns = [
        path('', auth_views()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('350a1224-5c60-4d63-a7b5-16b9e40339e4', this)">▼ Hide result</div>
    <iframe id="350a1224-5c60-4d63-a7b5-16b9e40339e4" src="doc_includes/views/test_auth.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('949d4376-6d07-43b7-8af1-96472035daa1', this)">▼ Hide result</div>
    <iframe id="949d4376-6d07-43b7-8af1-96472035daa1" src="doc_includes/views/test_auth1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('bd158a8e-7a12-47b9-a9d5-9a80cbb96064', this)">▼ Hide result</div>
    <iframe id="bd158a8e-7a12-47b9-a9d5-9a80cbb96064" src="doc_includes/views/test_auth2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

CRUD views
----------

Create a full CRUD set of views:

.. code-block:: python

    urlpatterns = [
        path('', crud_views(model=Album)),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('029fd488-e23e-4595-9538-68e69a3ea888', this)">▼ Hide result</div>
    <iframe id="029fd488-e23e-4595-9538-68e69a3ea888" src="doc_includes/views/test_crud_view.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('696eb878-04bd-4da3-ac95-f84cb23d5836', this)">▼ Hide result</div>
    <iframe id="696eb878-04bd-4da3-ac95-f84cb23d5836" src="doc_includes/views/test_crud_view1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('73b71946-bf9c-46de-b104-71569fca1a07', this)">▼ Hide result</div>
    <iframe id="73b71946-bf9c-46de-b104-71569fca1a07" src="doc_includes/views/test_crud_view2.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('70c0f530-fd15-49d5-8abc-e094300edf1c', this)">▼ Hide result</div>
    <iframe id="70c0f530-fd15-49d5-8abc-e094300edf1c" src="doc_includes/views/test_crud_view3.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('004538d8-ca2a-4ec7-9855-58a69d3bc516', this)">▼ Hide result</div>
    <iframe id="004538d8-ca2a-4ec7-9855-58a69d3bc516" src="doc_includes/views/test_crud_view4.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





Dev tools
=========

iommi ships with several integrated tools to increase your development speed. They
are shown on iommi pages when `settings.DEBUG` is `True`. Some are always
active and some are optional and need to be added to your project.

On iommi pages you get a debug panel to quickly access the debug tools:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d06778a6-af8f-4daf-a219-7fabe98da051', this)">▼ Hide result</div>
    <iframe id="d06778a6-af8f-4daf-a219-7fabe98da051" src="doc_includes/dev_tools/test_dev_tools.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Code (jump to your code)
------------------------

Click this button to jump to the code of the current view in your IDE. By
default it is configured to jump into PyCharm, but you can configure it
for your use case by defining `settings.IOMMI_DEBUG_URL_BUILDER`. This is a
callable that takes `filename` and `lineno` arguments and returns a string.

On your staging server you can use this to point to your source code too,
which can be very handy.

For VSCode: `IOMMI_DEBUG_URL_BUILDER = lambda filename, lineno: 'vscode://file/%s:' % (filename,)+ ('' if lineno is None else "%d" % (lineno,))`

Tree
----

This tool shows you the full tree of the current page with the names, full
iommi paths, types (with links to documentation), and the included state
of all the nodes in the tree.

Pick
----

If you want to configure some part of a page, pick is your friend. Start the
pick tool and then click on the item and you'll get the iommi path to that
part with the type shown (with a link to the documentation). You will also
get the paths and types of all the parent components up the tree.

Code finder
-----------

For complex pages that use a lot of templates with loops, translations, and
includes, it can be hard to find where the code is. For this use case, "Code
finder" is useful. Start the tool and then click on what you want to modify
to jump to your IDE at the right place or close to the right place. This
relies on the `IOMMI_DEBUG_URL_BUILDER` setting. By default this is
configured for PyCharm.

.. code-block:: python

    class MyPage(Page):
        foo = html.div(template='docs/code_finder_test.html')

Mouse over the interactive example below for a demo:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9ced5ba3-2c4f-427f-b4d1-6922d9caa004', this)">▼ Hide result</div>
    <iframe id="9ced5ba3-2c4f-427f-b4d1-6922d9caa004" src="doc_includes/dev_tools/test_code_finder.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You might note that there's a `>` at the start of this example. This is because the way this works is that an HTML comment is inserted before each `{% if %}`/`{% for %}`/`{% include %}` tag, but HTML comments are not allowed inside HTML tags, causing some broken HTML. This is mostly fine for this use case, but it will sometimes lead to some artifacts as seen here.

Edit
----

Edit the code of your view directly in your browser. It re-renders
as-you-type and when the syntax is correct and execution succeeded it will
save the code back to disk. This works not just for iommi views, but for any
function based view.

.. note::

    This feature isn't enabled by default because it requires you to add
    `'iommi.live_edit.Middleware'` to `settings.MIDDLEWARE`. Note that you need
    to add this at the very top of the middleware list!

This tool is full arbitrary remote execution so it will be *very* bad if you run this in production! It will only work when `DEBUG` is true.

Edit style
----------

A special version of the live edit feature, but specific for editing a `Style`. This is most useful for implementing support for a new CSS framework.

Profile
-------

Press this tool to get a profile of the current page. By default it
will do sorting on the cumulative time, but you can do `?_iommi_prof=tottime`
to get the total time.

- `?_iommi_prof=flame` gives you a flame graph.
- If you have gprof2dot installed you can also do `?_iommi_prof=graph` to get a graph output.

On Python 3.15 and later iommi uses the statistical sampling engine that CPython's
own sampling profiler is built on. It reads the stack of the thread serving the
request from a separate thread, so the page renders at full speed and the numbers
you get aren't distorted by the measuring. Sampled data has no call counts, so the
`ncalls` column is replaced by the number of samples the function was on the stack
for.

On older versions of Python there is no such engine available, so iommi falls back
to a tracing profiler: `yappi <https://pypi.org/project/yappi/>`_ if it is
installed, and `cProfile` otherwise. Tracing makes the page several times slower to
render, which does skew the result towards whatever is called the most often, but
you do get exact call counts.

.. note::

    This feature isn't enabled by default because it requires you to add
    `'iommi.profiling.Middleware'` to `settings.MIDDLEWARE`. Note that you
    need to put this below `django.contrib.auth.middleware.AuthenticationMiddleware`
    if you want to use this in production. Only staff users are allowed to
    profile in production, but all users can profile in debug mode.

Profile POST
------------

If you want to profile the `POST` of a form, click this button first and then click the normal submit button on the form.

SQL trace
---------

This tool gives you a list of all SQL statements issued by the page, with
timing for each, and a timeline at the top for each statement. There is also
a grouped time graph so if you have many similar database hits you will see
those easily.

.. note::

    This feature isn't enabled by default because it requires you to add
    `'iommi.sql_trace.Middleware'` to `settings.MIDDLEWARE`. Note that you
    need to put this below `django.contrib.auth.middleware.AuthenticationMiddleware`
    if you want to use this in production. Only staff users are allowed to
    trace sql in production, but all users can trace sql in debug mode.

In DEBUG the SQL trace middleware will automatically warn you if your views
appear to have `N+1 type errors <https://stackoverflow.com/questions/97197/what-is-the-n1-selects-problem-in-orm-object-relational-mapping>`_. By default iommi will print stack traces and example SQL statements
for the worst offenders for your view to the console:

.. code-block::

    ------ 5 times: -------
    From source:
      File "/Users/boxed/Projects/iommi/examples/examples/table_examples.py", line 146, in root => return Page(
    With Stack:
      File "iommi/table.py", line 308, in default_cell__value => return getattr_path(row, evaluate_strict(column.attr, row=row, column=column, **kwargs))
      File "iommi/evaluate.py", line 60, in evaluate => return func_or_value(**kwargs)
      File "iommi/evaluate.py", line 76, in evaluate_strict => return evaluate(func_or_value, __signature=None, __strict=True, __match_empty=__match_empty, **kwargs)
      File "iommi/table.py", line 933, in __init__ => self.tag = evaluate_strict(self.tag, **self._evaluate_parameters)
      File "iommi/table.py", line 887, in __iter__ => yield Cell(cells=self, column=column)
    SELECT "examples_tfoo"."id", "examples_tfoo"."name", "examples_tfoo"."a" FROM "examples_tfoo" WHERE "examples_tfoo"."id" = 1
    SELECT "examples_tfoo"."id", "examples_tfoo"."name", "examples_tfoo"."a" FROM "examples_tfoo" WHERE "examples_tfoo"."id" = 2
    SELECT "examples_tfoo"."id", "examples_tfoo"."name", "examples_tfoo"."a" FROM "examples_tfoo" WHERE "examples_tfoo"."id" = 3
    SELECT "examples_tfoo"."id", "examples_tfoo"."name", "examples_tfoo"."a" FROM "examples_tfoo" WHERE "examples_tfoo"."id" = 4
    ... and 1 more unique statements


If you want more detailed information in your console to debug a problem you can set
`settings.SQL_DEBUG` to `'all'` (which prints all SQL statements), `'stacks'` (all SQL statements with tracebacks). You can also set it to `None` to turn it off.


You can use this middleware on non-iommi views too. Just add `?_iommi_sql_trace` to your url.



Components
==========

These are the building blocks iommi gives you. One page each, explaining what the
component is, what you get for free, and where it differs from the Django
equivalent.

These pages are for understanding, not for looking things up or getting a job done.
For a specific task see the :doc:`cookbook`; for the complete list of options on any
component see :doc:`api`.

.. toctree::

    edit_tables
    forms
    fragments
    main_menu
    pages
    queries
    tables





.. _edit-tables:

Edit tables
===========

iommi edit tables build on top of iommi tables but enable editing of cells too.

A simple example:

.. code-block:: python

    EditTable(
        auto__model=Album,
        page_size=10,
        # Turn on the edit feature for the year column
        columns__year__field__include=True,
        # Turn on the delete row feature
        columns__delete=EditColumn.delete(),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2248ff35-d420-4a9e-a1ca-2f5206a440d1', this)">▼ Hide result</div>
    <iframe id="2248ff35-d420-4a9e-a1ca-2f5206a440d1" src="doc_includes/edit_tables/test_edit_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _orderable-edit-tables:

Orderable edit tables
---------------------

iommi edit tables also support manual ordering. That can be especially useful for editing reverse FKs in nested forms.

The easiest way to make an `EditTable` orderable is to inherit your model from `iommi.models.Orderable`:

.. code-block:: python

       from iommi.models import Orderable

       class FavoriteArtist(Orderable):
           user = ForeignKey(
               settings.AUTH_USER_MODEL,
               on_delete=models.CASCADE,
               related_name='favorite_artists',
           )
           artist = ForeignKey(Artist, on_delete=CASCADE, related_name='+')
           comment = CharField(max_length=255)

           def __str__(self):
               return self.artist.name

.. code-block:: python

    class UserForm(Form):
        class Meta:
            auto__model = get_user_model()
            auto__include = ['username', 'email']
            fields__username__editable = False

    class FavoriteArtists(EditTable):
        class Meta:
            auto__model = FavoriteArtist
            auto__include = ['artist__name', 'comment', 'sort_order']
            columns__comment__field__include = True
            sortable = False

    user = get_user_model().objects.get(username='john.doe')

    class ParentForm(Form):
        user_form = UserForm.edit(auto__instance=user)
        favorite_artists = FavoriteArtists(rows=user.favorite_artists.all())

        class Meta:
            actions__submit__post_handler = save_nested_forms

.. code-block:: python

    ParentForm()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9b3e63f5-2ea0-4788-ac30-feb5a1c7ae9b', this)">▼ Hide result</div>
    <iframe id="9b3e63f5-2ea0-4788-ac30-feb5a1c7ae9b" src="doc_includes/edit_tables/test_orderable_edit_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

If you already have a custom model field for ordering, you can register it as a `reorder_handle` column:

.. code-block:: python

       from iommi import register_edit_column_factory

       register_edit_column_factory(YourOrderField, shortcut_name='reorder_handle')

If you just use any django integer field, you can still make your EditTable orderable with:

.. code-block:: python

           class MyEditTable(EditTable):
               class Meta:
                   auto__model = Foo
                   columns__bar = EditColumn.reorder_handle()
                   sortable = False

We use SortableJS and if you want, you can also pass other `options <https://github.com/SortableJS/Sortable?tab=readme-ov-file#options>`__.
For example this allows multi-drag:

.. code-block:: python

           class MyEditTable(EditTable):
               class Meta:
                   auto__model = Foo
                   columns__bar = EditColumn.reorder_handle()
                   reorderable = {
                       "multiDrag": True,  # Enable multi-drag
                       "selectedClass": 'selected',  # The class applied to the selected items
                       "fallbackTolerance": 3,  # So that we can select items on mobile
                   }
                   sortable = False

Note: We recommend using `sortable=False` on orderable EditTables, because it doesn't really make sense to have both. 
And if you sort table by another column, the `reorder_handle` column gets `render_column=False`.





.. _forms:

Forms
=====

iommi forms is an alternative forms system for Django. It is inspired by the standard Django forms, while improving on its weaknesses.

This page explains what iommi forms are and how they differ from Django's. If you
want to *do* something specific, go to the :ref:`form cookbook <cookbook-forms>`;
for the exhaustive list of options see :doc:`Form` and :doc:`Field`.

Where iommi forms differ from Django's
--------------------------------------

- They render to HTML nicely out of the box. The default is bootstrap, several other :doc:`styles <styles>` ship with iommi, and you can adapt them to your own design system.
- Foreign key relationships get AJAX-backed select widgets, with the endpoint wired up on the same URL as the view. Because it's the same view, it's covered by the same permission checks.
- `__` works for going across table/object boundaries, the same way Django does it for QuerySets.
- Anywhere you can put a value you can put a callable instead, evaluated late. `include=lambda request, **_: request.user.is_staff` is how you show a slightly different form to administrators, without a second form class.
- You can add a CSS class or attribute to exactly one thing without copying a template.
- Configuration doesn't require writing a class that's only used in one place.

A `Form` is also a complete view. `Form.create`, `Form.edit` and `Form.delete`
give you the post handler and the redirect too, so there's no template and no
view function to write. See :doc:`views` for the CRUD set built on top of these.

Instead of `Field` subclasses, iommi pre-packages sets of defaults as
*shortcuts* -- `Field.boolean`, `Field.integer`, `Field.choice` and so on. The
difference matters: a shortcut's config is defaults, not hard coded behavior, so
you can start from one and refine it without subclassing. See
:doc:`philosophy` for why, and :doc:`Field` for the full list.

Three ways to say the same thing
--------------------------------

The next three sections build the same form automatically, declaratively and
programmatically. They are not three different features to choose between: they
are one API seen from three angles, and you can mix them freely. Which one reads
best depends on how much you know at import time. :doc:`equivalency` spells out
the mapping between them.

Fully automatic forms
~~~~~~~~~~~~~~~~~~~~~

Generating forms from Django models automatically is the most powerful and common use for iommi forms:

.. code-block:: python

    form = Form.create(auto__model=Album)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a7b981fe-0bae-46a4-b11e-45ea200e2406', this)">▼ Hide result</div>
    <iframe id="a7b981fe-0bae-46a4-b11e-45ea200e2406" src="doc_includes/forms/test_fully_automatic_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Forms in iommi scale with higher complexity:

.. code-block:: python

    edit_user_form = Form.edit(
        auto__model=User,
        instance=lambda user_pk, **_: User.objects.get(pk=user_pk),
        fields__username__is_valid=
            lambda parsed_data, **_: (
                parsed_data.startswith('demo_'),
                'needs to start with demo_'
            ),
        fields__is_staff__label__template='tweak_label_tag.html',
        # show only for staff
        fields__is_staff__include=lambda request, **_: request.user.is_staff,
    )

Install like this:

.. code-block:: python

    urlpatterns = [
        path('users/<user_pk>/edit/', edit_user_form.as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d8b47d7e-fbb3-410a-b9fb-2b0a534e7955', this)">▼ Hide result</div>
    <iframe id="d8b47d7e-fbb3-410a-b9fb-2b0a534e7955" src="doc_includes/forms/test_fully_automatic_forms1.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

In this case the default behavior for the post handler for `Form.edit` is a save function like the one we had to define ourselves in the previous example.

Declarative forms
~~~~~~~~~~~~~~~~~

You can create forms declaratively, similar to Django forms. There are some important differences between iommi forms and Django forms in this mode, maybe the most important being that in iommi you can pass a callable as a parameter to late evaluate what the value of something is. This is used to restrict a field for staff users in this example:

.. code-block:: python

    class UserForm(Form):
        first_name = Field.text()
        username = Field.text(
            is_valid=lambda parsed_data, **_: (
                parsed_data.startswith('demo_'),
                'needs to start with demo_'
            )
        )
        is_staff = Field.boolean(
            # show only for staff
            include=lambda request, **_: request.user.is_staff,
            label__template='tweak_label_tag.html',
        )

        class Meta:
            instance = lambda params, **_: User.objects.get(pk=params.user_pk)

            @staticmethod
            def actions__submit__post_handler(user, form, **_):
                if not form.is_valid():
                    return  # pragma: no cover

                form.apply(user)
                user.save()
                return HttpResponseRedirect('..')

Install like this:

.. code-block:: python

    urlpatterns = [
        # Note `UserForm()`, not `UserForm`!
        path('users/<user_pk>/edit/', UserForm().as_view()),
    ]

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9de6bfa7-b4c7-497a-8ee7-80ad3a64ab0a', this)">▼ Hide result</div>
    <iframe id="9de6bfa7-b4c7-497a-8ee7-80ad3a64ab0a" src="doc_includes/forms/test_declarative_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Note that we don't need any template here.

Programmatic forms
~~~~~~~~~~~~~~~~~~

The declarative style is very readable, but sometimes you don't know until runtime what the form should look like. Creating forms programmatically in iommi is easy (and equivalent to doing it the declarative way):

.. code-block:: python

    def edit_user_save_post_handler(form, **_):
        if not form.is_valid():
            return  # pragma: no cover

        form.apply(form.instance)
        form.instance.save()
        return HttpResponseRedirect('..')

    def edit_user_view(request, username):
        return Form(
            instance=User.objects.get(username=username),
            fields=dict(
                first_name=Field.text(),
                username=Field.text(
                    is_valid=lambda parsed_data, **_: (
                        parsed_data.startswith('demo_'),
                        'needs to start with demo_'
                    ),
                ),
                is_staff=Field.boolean(
                    # show only for staff
                    include=lambda request, **_: request.user.is_staff,
                    label__template='tweak_label_tag.html',
                ),
            ),
            actions__submit__post_handler=edit_user_save_post_handler,
        )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('32b1c1f2-1ac3-4cf9-889e-63f5d28f8574', this)">▼ Hide result</div>
    <iframe id="32b1c1f2-1ac3-4cf9-889e-63f5d28f8574" src="doc_includes/forms/test_programmatic_forms.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Post handlers
-------------

In the simplest cases, like in a create form, you only have one post handler.
You can do this yourself in the classic Django way:

.. code-block:: python

    if form.is_valid() and request.method == 'POST':
        do_your_thing()

This is fine. But what if you have two buttons? What if you have two forms?
What if there are two forms, one with two submit buttons, and a table with a
bulk action? Suddenly writing the if statement above becomes very difficult.
Post handlers in iommi handle this for you. iommi makes sure that the parts
compose cleanly and the right action is called.

By default for create/edit/delete forms you get one post handler by the name
`submit`. Adding more is easy:

.. code-block:: python

    def disable_action(form, **_):
        form.instance.disabled = True
        form.instance.save()
        return HttpResponseRedirect('.')

    form = Form.edit(
        auto__instance=instance,
        actions__disable__post_handler=disable_action,
    )

Post handlers can return a few different things:

- a `HttpResponse` object which will get returned all the way up the stack
- a *bound* `Part` of some kind. This could be a `Table`, `Form`, `Page`, etc. This is rendered into a `HttpResponse`
- `None` will result in the page being rendered like normal
- everything else iommi will attempt to json encode and return as a json response

Saving
------

`Form.create` and `Form.edit` come with a post handler that saves for you, so in
the common case there is nothing to write. When you do need to intervene, you
don't subclass or override a `save` method: you refine one of the callbacks that
correspond to the steps of a Django multi-step commit.

This mirrors the philosophy elsewhere in iommi -- there is a named hook for each
step, so you can replace just the step you care about and leave the rest of the
default behavior alone.

For the list of callbacks and the order they run in, see
:ref:`Save callbacks <form-save-callbacks>` on `Form`. For worked examples, see
:ref:`the cookbook <form-save-hooks>`.



.. _fragments:

Fragments
---------

If you are just using iommi's built in components like `Form` and `Table`, you won't need to use `Fragment` directly. `Fragment` is a class that is used to compose HTML tags in a way that is later refinable. The most basic example of this is the :ref:`h_tag <h_tag>` of a form or table. A `Fragment` has :ref:`attrs <attributes>`, :ref:`template` and :ref:`tag` configuration:



.. code-block:: python

    table = Table(
        auto__model=Artist,
        h_tag__attrs__style__background='blue',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('9f4c574c-4c3d-4e0f-9db7-55150c27616a', this)">▼ Hide result</div>
    <iframe id="9f4c574c-4c3d-4e0f-9db7-55150c27616a" src="doc_includes/fragments/test_fragment.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

See the API reference for :doc:`Fragment` for more details.





.. _mainmenu:

Main menu
=========

The main menu component in iommi is used to create the main navigation for your app. This is primarily useful for SaaS or internal apps. It creates a sidebar menu with support for nested menu items, and centralized access control that automatically shows only menu items the user has access to.

To set up your main menu:

- add the `iommi.main_menu.main_menu_middleware` middleware to the `MIDDLEWARE` list
- declare your `MainMenu`
- define the `IOMMI_MAIN_MENU` setting to point to where you have defined your menu (like `IOMMI_MAIN_MENU = 'your_app.main_menu.main_menu'`).
- add the url patterns from the menu to your app

Access control is recursive, meaning that if a user does not have access to a menu item, it is automatically denied access to all subitems.

.. note::

    There are many more examples in :doc:`the cookbook <cookbook_main_menu>`.

.. code-block:: python

    menu_declaration = MainMenu(
        items=dict(
            artists=M(
                icon='people',
                view=artists_view,
            ),
            albums=M(
                icon='disc',
                view=albums_view,
            ),
        ),
    )

Add the url patterns from the menu to your app:

.. code-block:: python

    urlpatterns = menu_declaration.urlpatterns()

Your views will now get the menu rendered on standard iommi views. For non-iommi views you can render the menu with `{{ request.iommi_main_menu }}`.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2e2d8ae3-86f9-4d16-9e51-5369be0c89a1', this)">▼ Hide result</div>
    <iframe id="2e2d8ae3-86f9-4d16-9e51-5369be0c89a1" src="doc_includes/main_menu/test_base.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>





.. _pages:

Pages
=====

iommi pages are used to compose parts of a page into a full page. A "part" can be any iommi component (like :ref:`Table <tables>`, :ref:`Form <forms>`, :doc:`Fragment`), or a plain Python string, or a Django `Template <https://docs.djangoproject.com/en/5.1/topics/templates/>`_.

The `html`_ builder function is used to create simple :doc:`Fragment` objects for div, h1, span, etc.

Example
-------

.. code-block:: python

    class MyPage(Page):
        title = html.h1('My page')
        users = Table(auto__model=User)
        create_user = Form.create(auto__model=User)

This creates a page with an h1 tag, a table of users and a form to create a
new user. You can add it your `urls.py` like this: `path('my_page/', MyPage().as_view())`, or make a function based view and `return MyPage()`.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('70baa06e-9abb-4e79-8a95-176d049e57fe', this)">► Show result</div>
    <iframe id="70baa06e-9abb-4e79-8a95-176d049e57fe" src="doc_includes/pages/test_example.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Page
----

The `Page` class is used to compose pages. Use `.as_view()` to create a view from a `Page`.
If you have installed the iommi middleware you can also return them directly from your views. They accept
`str`, `Part` and Django `Template` types:

.. code-block:: python

    class MyPage(Page):
        # Using the html builder to create a tag safely
        h1 = html.h1('Welcome!')

        # If you write an HTML tag in here it will be
        # treated as unsafe and escaped by Django like normal
        body_text = 'Welcome to my iommi site...'

        # You can nest Page objects!
        some_other_page = MyOtherPage()

        # Table and Form are Part types
        my_table = Table(auto__model=Artist)

        # Django template
        other_stuff = Template('<div>{{ foo }}</div>')

The types here that aren't `Part` will be converted to a `Part` derived class
as needed.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fbd27eba-61ef-4dde-a3fb-b18ea1e59407', this)">► Show result</div>
    <iframe id="fbd27eba-61ef-4dde-a3fb-b18ea1e59407" src="doc_includes/pages/test_page.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Add more parameters to a `Page`
-------------------------------

.. code-block:: python

    class MyPage(Page):
        class Meta:
            @staticmethod
            def extra_params(**_):
                return dict(
                    extra_param='foo',
                )

        text = html.div(lambda extra_param, **_: extra_param + 'bar')

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('c392b733-97e5-4e28-84c7-00b315242e58', this)">▼ Hide result</div>
    <iframe id="c392b733-97e5-4e28-84c7-00b315242e58" src="doc_includes/pages/test_extra_params.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Or the functional syntax for the same thing:

.. code-block:: python

    my_page = Page(
        extra_params=lambda **_: dict(extra_param='foo'),
        parts__text=html.div(lambda extra_param, **_: extra_param + 'bar'),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('727fd4da-122f-46ff-908a-ecfeea3f9f33', this)">► Show result</div>
    <iframe id="727fd4da-122f-46ff-908a-ecfeea3f9f33" src="doc_includes/pages/test_extra_params1.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _html:

html
----


html is a little builder object to create simple elements. You just do
`html.h1('some text')` to create an h1 html tag. It works by creating `Fragment`
instances, so the `html.h1('foo')` is the same as
`Fragment('some text', tag='h1')`, which is itself a convenient short way to
write `Fragment(children__text='some text', tag='h1')`. See `Fragment` for more
available parameters.


Part
--------

`Part` is the base class/API for objects that can be composed into a page.

Fragment
--------

Advanced example:

.. code-block:: python

    Fragment(
        'foo',
        tag='div',
        children__bar=Fragment('bar'),
        attrs__baz='quux',
    )

This fragment will render as:

.. code-block:: html

    <div baz='quux'>foobar</div>

This might seem overly complex for such a simple thing, but when used in
reusable components in iommi `Fragment` objects can be further customized
with high precision.





.. _queries:

Queries
=======

iommi queries makes it easy to implement searching and filtering in your Django app.

Major features:

- Generate simple filtering GUIs
- Supply your views with an advanced query language
- Query language can be used stand alone without the GUI parts
- Highly customizable GUI based on iommi :doc:`forms`

Queries are normally used from inside iommi tables where they are an
integrated part, but can also be used stand alone. See below for an
example.

.. image:: https://docs.iommi.rocks/queries_example.png

The code for the example above:

.. code-block:: python

    Table(
        auto__model=Album,
        page_size=10,
        columns__name__filter__include=True,
        columns__artist__filter__include=True,
    )

Read the full documentation and the :doc:`cookbook` for more.

Query language
--------------

iommi comes with an advanced query language so users can filter tables
based on what they want. Searching songs can look like this:

.. code-block::

    album=Paranoid AND lyrics:"have the power"

This will find the song War Pigs, as it's from the album Paranoid and
the lyrics contains the text "have the power". The query language supports
`AND` and `OR`, parenthesis and the operations `<`, `<=`, `>`, `>=` for
numerical values, and `=` for all values which is an exact case insensitive
match. You can exclude with `!=`. As the example above shows `:` is used for
case insensitive "contains" queries, and the inverse of that is `!:`.

iommi tries to support what the user might intuitively write for searching
boolean columns. It will interpret "n", "no", "0" (zero), "false", "f" and "off"
as `false`  and the corresponding values for `true`.

You can configure a `Filter` to be case sensitive by setting `query_operator_to_q_operator`
to `case_sensitive_query_operator_to_q_operator`.

iommi queries have a special form for filtering directly on pk, which can be
very handy: `album.pk=3`.

`query_operator_for_field` specifies what operation the simple form uses to
interpret its inputs. The default is `=`, meaning exact case insensitive match.

If you have table of `Song` and a foreign key to `Album`, if you search for
`album=Paranoid` iommi will by default create the Django query
`Q(album__name='Paranoid')`. If your model has different fields used as names,
you must register those with `register_search_fields`, or if you want
something other special for just this view you can use the `search_fields`
parameter to specify the fields to use. Note that you can use `pk` or
other non-string columns as search fields if you want.

Stand alone example
-------------------

Simple view that allows the user to search for an album by choosing the artist from a drop down, and search
for specific year in the advanced mode:

.. code-block:: python

    class AlbumQuery(Query):
        artist = Filter.choice_queryset(choices=Artist.objects.all())
        year = Filter.integer()

    def albums(request):
        query = AlbumQuery().bind(request=request)

        dispatch = query.perform_dispatch()
        if dispatch is not None:
            return dispatch

        return render(
            request=request,
            template_name='albums.html',
            context={
                'query': query,
                'albums': query.get_q(),
            },
        )

.. code-block:: html

    <!-- albums.html -->
    {{ query }}

    <ul>
        {% for album in albums %}
            <li>{{ album }}</li>
        {% endfor %}
    </ul>

You will also need to render the assets in your `<head>` tag:



.. code-block:: html

    {% for asset in query.iommi_collected_assets.values %}
        {{ asset }}
    {% endfor %}

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d7a9ce96-8fe3-4123-8d54-656a1d15eaaa', this)">▼ Hide result</div>
    <iframe id="d7a9ce96-8fe3-4123-8d54-656a1d15eaaa" src="doc_includes/queries/test_stand_alone_example.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Programmatically call the search API:

.. code-block:: python

    query = Query(auto__model=Album).bind(request=request)
    albums_queryset = query.parse_query_string(
        'artist="Black Sabbath" and (year=1991 or year=1992)'
    )





.. _tables:

Tables
======

iommi tables make it easy to create full featured HTML tables.

This page explains what a `Table` is and what you get for free. If you want to
*do* something specific, go to the :ref:`table cookbook <cookbook-tables>`; for
the exhaustive list of options see :doc:`Table` and :doc:`Column`.

A table generates the header, rows and cells, and comes with sorting, filtering,
pagination, bulk edit, link creation, automatic rowspan and header grouping
already wired up. The point is that these aren't features you assemble: they are
on by default and you turn them off or reconfigure them from the outside, which
is why a useful table is usually one line of code.

Customization goes all the way down -- table, row, cell, and the template for
any of them -- so you rarely have to abandon the abstraction to get the markup
you want.

A simple example:

.. code-block:: python

    Table(
        auto__model=Album,
        page_size=10,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('66dd5d59-d8fc-481f-9c38-7ac3a554d8b8', this)">▼ Hide result</div>
    <iframe id="66dd5d59-d8fc-481f-9c38-7ac3a554d8b8" src="doc_includes/tables/test_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Read the full documentation and the :doc:`cookbook` for more.

Creating tables from models
---------------------------

Say I have some model:

.. code-block:: python

    class Foo(models.Model):
        a = models.IntegerField()

        def __str__(self):
            return f'Foo: {self.a}'

.. code-block:: python

    class Bar(models.Model):
        b = models.ForeignKey(Foo, on_delete=models.CASCADE)
        c = models.CharField(max_length=255)

Now I can display a list of `Bar` in a table like this:

.. code-block:: python

    def my_view(request):
        return Table(auto__model=Bar)

This automatically creates a table with pagination and sorting. If you pass
`query_from_indexes=True` you will get filters for all the model fields
that have database indexes. This filtering system includes an advanced filter
language. See :doc:`queries` for more on filtering.

Explicit tables
---------------

You can also create tables explicitly:

.. code-block:: python

    class AlbumTable(Table):
        # Shortcut for creating checkboxes to select rows
        select = Column.select()

        name = Column()

        # Show the name field from Artist. This works for plain old objects too.
        artist_name = Column(
            attr='artist__name',

            # put this field into the query language
            filter__include=True,
        )
        year = Column.number(
            # Enable bulk editing for this field
            bulk__include=True,
        )

        class Meta:
            rows = Album.objects.all()
            title = 'Albums'

    albums = AlbumTable().as_view()

This gives me a view with filtering, sorting, bulk edit and pagination.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e136f808-4979-4ba6-8f5e-9913b41b1f6a', this)">▼ Hide result</div>
    <iframe id="e136f808-4979-4ba6-8f5e-9913b41b1f6a" src="doc_includes/tables/test_explicit_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Table of plain python objects
-----------------------------

.. code-block:: python

    # Say I have a class...
    class Foo(object):
        def __init__(self, i):
            self.a = i
            self.b = 'foo %s' % (i % 3)
            self.c = (i, 1, 2, 3, 4)

    # I can declare a table:
    class FooTable(Table):
        a = Column.number()

        b = Column()

        # Display the last value of the tuple
        c = Column(
            cell__format=lambda value, **_: value[-1],
        )

        # Calculate a value not present in Foo
        sum_c = Column(
            cell__value=lambda row, **_: sum(row.c),
            sortable=False,
        )

    def plain_objs_view(request):
        # and now create a list of items
        foos = [Foo(i) for i in range(4)]

        # now to get an HTML table:
        return FooTable(rows=foos)

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('823fd3ed-57f4-4e16-bad7-1a3d4eb00956', this)">▼ Hide result</div>
    <iframe id="823fd3ed-57f4-4e16-bad7-1a3d4eb00956" src="doc_includes/tables/test_table_of_plain_python_objects.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

All these examples and a bigger example using many more features can be found in the examples project.



Understanding iommi
===================

These pages cover the thinking behind iommi, which will help write idiomatic and maintainable iommi code.


.. toctree::
   :maxdepth: 2

   architecture
   equivalency
   philosophy
   registrations
   semantic_models




Architecture
============

Execution phases
----------------

`Part` objects have this life cycle:

1. Definition
2. Construction
3. Refine done
4. `Bind`_
5. Traversal (e.g. render to html, respond to ajax, custom report creation)


At definition time we can have just a bunch of dicts. This is really a stacking and merging of namespaces.

At construction time we take the definition namespaces and materialize them into proper :code:`Table`, :code:`Column`, :code:`Form` etc objects.

At bind time we:

- register parents
- evaluate callables into real values
- invoke any user defined :code:`on_bind` handlers

At traversal time we are good to go and can now invoke the final methods of all objects. We can now render html, respond to ajax, etc.

Refine done
-----------

At some point we know that this object has been completely configured.
This is when `refine_done` is either called automatically (for example if
you call `bind()` on an object that hasn't had `refine_done()` called yet),
or you can do it explicitly yourself.

The refine done step does a lot of the work that is needed for the final
traversal step, so if possible you want to make sure this is done before.
If this step is done on an object that is then kept around, all this work
doesn't need to be redone. Examples of work that is done in this step include
all the application of the `Style`, and pre-sorting out callables and constants.

This is simpler to understand with a concrete example, so let's take a
table of albums that contain the string passed in a query parameter, or
otherwise the letter `x`:

.. code-block:: python

    albums_with_o = Table(
        auto__model=Album,
        rows=lambda request, **_: Album.objects.filter(
            name__icontains=request.GET.get('q', 'x')
        )
    )

If you register that to a path with the `.as_view()` method, then 
`refine_done` will be called once on first use. You can also explicitly call
`refine_done()` to force this optimization to happen at import time, which
might be preferable to you, especially for views that you know will be called
by all web workers anyway.

If you do this instead:

.. code-block:: python

    def albums_with_o(request):
        return Table(
            auto__model=Album,
            rows=Album.objects.filter(
                name__icontains=request.GET.get('q', 'x')
            )
        )

The functionality is the same, but since a fresh `Table` is created on
each request, all the work done in the `refine_done` step will have to
be redone each request. 

So in general, the FBV style is often easier to reason about when starting
out with iommi, but it has some big downsides on performance.

.. _bind:

Bind
----

"Bind" is when we take an abstract declaration of what we want and convert it into the "bound" concrete expression of that. It consists of these parts:

1. Copy of the part. (We set a member `_declared` to point to the original definition if you need to refer to it for debugging purposes.)
2. Set the `parent` and set `_is_bound` to `True`
3. Style application
4. Call the part's `on_bind` method

The parts are responsible for calling `bind(parent=self)` on all their children in `on_bind`.

The root object of the graph is initialized with `bind(request=request)`. Only one object can be the root.

.. _dispatching:

Namespace dispatching
---------------------

This section is about how `__` is *implemented*. For what it means as a user,
see :ref:`dunder-dict-equivalence`; for why iommi has it at all, see
:doc:`philosophy`.

``columns__foo__include=False`` is an example of the namespace dispatch mechanism
from iommi.declarative. It
enables functions to expose the *full* API of functions it calls while
still keeping the code simple. Here's a contrived example:

.. code-block:: python

    from iommi.declarative.dispatch import dispatch
    from iommi.declarative.namespace import EMPTY

    @dispatch(
        b__x=1,  # these are default values. "b" here is implicitly
        # defining a namespace with a member "x" set to 1
        c__y=2,
    )
    def a(foo, b, c):
        print('foo:', foo)
        some_function(**b)
        another_function(**c)

    @dispatch(
        d=EMPTY,  # explicit namespace
    )
    def some_function(x, d):
        print('x:', x)
        another_function(**d)

    def another_function(y=None, z=None):
        if y:
            print('y:', y)
        if z:
            print('z:', z)

    # now to call a()!
    a('q')
    # output:
    # foo: q
    # x: 1
    # y: 2

    a('q', b__x=5)
    # foo: q
    # x: 5
    # y: 2

    a('q', b__d__z=5)
    # foo: q
    # x: 1
    # z: 5
    # y: 2

This is really useful for the `Table` class as it means we can expose the full
feature set of the underlying `Query` and `Form` classes by just
dispatching keyword arguments downstream. It also enables us to bundle
commonly used features in what we call "shortcuts", which are pre-packaged sets of defaults.

.. _evaluate:

Evaluate
--------

To customize iommi you can pass functions/lambdas in many places. This makes it super easy and fast to customize things, but how does this all work? Let's start with a concrete example:

.. code-block:: python

    Table(
        auto__model=Artist,
        columns__name__cell__format=lambda value, **_: f'{value} !!!',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('140b8825-8712-4880-9034-f73d2dabd15c', this)">▼ Hide result</div>
    <iframe id="140b8825-8712-4880-9034-f73d2dabd15c" src="doc_includes/architecture/test_evaluate.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

This will change the rendering of Dios name from `Dio` to `Dio !!!`. The obvious question here is: what other keyword arguments besides `value` do I get? In this case you get:

.. code-block:: python

    request        WSGIRequest
    table          Table
    column         Column
    params         Struct
    traversable    Column
    user           User
    value          str
    row            Artist
    cells          Cells
    bound_cell     Cell
    root           Table

The general idea here that you should get all useful objects up the tree and as they are named it becomes easy to understand what is happening when reading these functions. If you have an iommi object you can call the method `iommi_evaluate_parameters()` on it to retrieve this dict.

`traversable` is exactly the same object as `column`. It's the general name of the closest object (or the leaf) for that callback. You can think of it as similar to `self`. This is useful for creating functions that you can use for `Field`, `Column`, and `Filter`; as the keyword argument `traversable` is the same, but they will get `field`, `column`, and `filter` as the specific keyword arguments. Prefer the specific name if possible since it makes the code more readable.


.. note::

    It is a good idea to always give your callbacks `**_` even if you match all keyword arguments. We don't consider adding keyword arguments a breaking change so additional keyword arguments can be added at any time.

Evaluate - under the hood
~~~~~~~~~~~~~~~~~~~~~~~~~

There are three functions that handle the evaluation of callables into values when needed. All of these pass values straight through, which is why you can write e.g. `display_name='Artist'` instead of having to write lambdas for simple values.

- `evaluate`: evaluates non-strict, which means it will allow functions that don't match the given signature to pass through
- `evaluate_strict`: evaluates strictly, which means functions that don't match the given signature will be an error

Each object in the tree declares what it adds to the evaluate parameters with a method `own_evaluate_parameters`. For example `Table` adds just one argument `table` which is itself. The method `iommi_evaluate_parameters` gives you all the evaluate parameters up the tree from where you are.

There are two special cases: `traversable` which is the leaf node, and `request` which is the http request object.





Equivalence
===========

In iommi there are two equivalence principles that are important to grasp:

- declarative/programmatic hybrid API
- double underscore as a short hand syntax for nesting dicts

The model used for these examples is `Album`:

.. literalinclude:: models.py
     :start-at: class Album
     :end-before: def __str__
     :language: python


Declarative/programmatic hybrid API
-----------------------------------

The programmatic API is pretty straightforward: you have a class constructor that takes some arguments. The interesting part is how we can mirror that *exactly* into a declarative style.

.. code-block:: python

    table = Table(
        model=Album,
        columns=dict(
            name=Column(),
        ),
    )

This simple table can be written as a class definition:

.. code-block:: python

    class MyTable(Table):
        class Meta:
            model = Album

        name = Column()

There are two things to notice here: 

1. Variables declared in `class Meta` in iommi means they get passed into the constructor. `model = Album` in `Meta` is exactly the same as `Table(model=Album)`.
2. The `name` column is declared on the class itself, and the `columns` part of the argument (`Table(columns=dict(...)`) is implicit. For `Page` the same implicit name is called `parts`, and for `Form` it's called `fields`.

Note that values set in `Meta` are *defaults*, not hard coded values, so you can
still override them in the constructor call (or in a subclass).

.. note::

    Writing `MyTable().as_view()` in your `urlpatterns` looks superficially like a
    Django class based view, but the two are unrelated. Notice the parentheses after
    the class name: you are creating an *instance* and asking it for a view, which is
    why you can pass arguments at that point (`MyTable(page_size=2).as_view()`).
    Django CBVs and iommi classes are radically different concepts and can't be
    combined.

.. _dunder-dict-equivalence:

Double underscore short form
----------------------------

In iommi you can have very deeply nested object structures, and because you want to customize something deep inside a graph it would be cumbersome to nest dicts a lot. So `__` is used as a separator.

Say we have a table, where we want to turn on filtering for a column, but we want to insert a special CSS class (called `special`) on the label of the search field:

.. code-block:: python

    table = Table(
        auto__model=Model,
        # Enable filtering
        columns__name__filter__include=True,
        # Set the CSS class on the label
        columns__name__filter__field__label__attrs__class__special=True,
    )

We could also write this without using `__` for nesting:

.. code-block:: python

    table = Table(
        auto=dict(model=Model),
        columns=dict(
            name=dict(
                filter=dict(
                    # Enable filtering
                    include=True,
                    # Set the CSS class on the label
                    field=dict(
                        label=dict(
                            attrs={
                                # have to use a dict literal here,
                                # because `class` is a reserved keyword in Python
                                'class': dict(
                                    special=True,
                                ),
                            },
                        ),
                    ),
                ),
            ),
        ),
    )

These two things have exactly the same meaning, but the `__` syntax is a lot shorter and cleaner.

Further examples
----------------

We want to create a form to create an album for a specific artist. We already have the artist from the URL, so that field shouldn't be in the form.

The following forms all accomplish this goal (you can use `form.as_view()` to create a view from a `Form` instance):

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        auto__exclude=['artist'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ba7f3df6-1664-406e-b5d8-a5057b372115', this)">▼ Hide result</div>
    <iframe id="ba7f3df6-1664-406e-b5d8-a5057b372115" src="doc_includes/equivalency/test_equivalence.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    form = Form.create(
        auto=dict(
            model=Album,
            exclude=['artist'],
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a4453e5e-1184-4570-bc9b-f3058f677724', this)">► Show result</div>
    <iframe id="a4453e5e-1184-4570-bc9b-f3058f677724" src="doc_includes/equivalency/test_equivalence1.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    form = Form.create(
        auto__model=Album,
        fields__artist__include=False,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('fec33bf2-0bfe-4934-b868-0fdb8d7bdc53', this)">► Show result</div>
    <iframe id="fec33bf2-0bfe-4934-b868-0fdb8d7bdc53" src="doc_includes/equivalency/test_equivalence2.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            auto__exclude = ['artist']

    form = AlbumForm.create()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2b58f5df-770d-4ec5-a9bb-fb1eb3368faa', this)">► Show result</div>
    <iframe id="2b58f5df-770d-4ec5-a9bb-fb1eb3368faa" src="doc_includes/equivalency/test_equivalence3.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            auto__include = ['name', 'year']

    form = AlbumForm.create()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2f6f5381-dbdd-48cf-8bd9-9d17e2636eab', this)">► Show result</div>
    <iframe id="2f6f5381-dbdd-48cf-8bd9-9d17e2636eab" src="doc_includes/equivalency/test_equivalence4.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    class AlbumForm(Form):
        class Meta:
            auto__model = Album
            fields__artist__include = False

    form = AlbumForm.create()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('cfcbbd8d-d434-4a41-a661-00bbf2479eb5', this)">► Show result</div>
    <iframe id="cfcbbd8d-d434-4a41-a661-00bbf2479eb5" src="doc_includes/equivalency/test_equivalence5.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Without using the `auto` features:

.. code-block:: python

    class AlbumForm(Form):
        name = Field()
        year = Field.integer()

        class Meta:
            title = 'Create album'
            actions__submit__post_handler = create_album

    form = AlbumForm()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ac1b1ee3-d835-4d23-9bca-73bb4f362586', this)">► Show result</div>
    <iframe id="ac1b1ee3-d835-4d23-9bca-73bb4f362586" src="doc_includes/equivalency/test_equivalence6.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. code-block:: python

    form = Form(
        fields__name=Field(),
        fields__year=Field.integer(),
        title='Create album',
        actions__submit__post_handler=create_album,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('43eae091-8a2d-4d34-826a-c512a558a0df', this)">► Show result</div>
    <iframe id="43eae091-8a2d-4d34-826a-c512a558a0df" src="doc_includes/equivalency/test_equivalence7.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

You can read more about this in the philosophy section under :ref:`philosophy_hybrid_api`.





Philosophy
==========

iommi follows a design philosophy that has evolved over several
years. It might feel a bit strange in the beginning but we believe
it's well worth it.

We want it to always be possible to create higher abstractions where
you can reuse those abstractions with small tweaks *without having to
change the abstraction to enable this*. If you have code that creates
a complex page with tables, forms, and help text fragments in several places,
then you should be able to reuse that but with a single line of code
make a change to a single small detail of that page, like adding a CSS
class somewhere.

In standard APIs you often have to copy paste the entire page and make
a small change. This hides the difference between the two pages because you
spend 99% of the code to say the same thing. Or alternatively you have to
pollute the definition of the first page with some super specific option
that makes that code worse. We want to avoid both these scenarios.

In short we want to be able to have code that reads like:

    It's like that one, but different like this.

The philosophy has these main parts:

No silent mistakes
---------------------

Systems that fail silently are the worst. Like when you try to render a
value in a django template and you just get silence instead of an error telling
you that you misspelled the variable name. Or when you define a `clean_albumm` method
that never gets called because you misspelled "album" (or worse if you renamed
album to record!). Or silent changes to behavior because you upgraded a library
and your overridden method isn't called because they renamed the function in
the class you inherited from.

In iommi we have an explicit design goal that all mistakes made by the
programmer should (if at all possible) be an error with a very good
error message telling them how to fix the problem.

To accomplish this we:

- don't override using standard object oriented overriding, instead preferring `refining <https://kodare.net/2018/06/25/refinableobject-object-orientation-refined.html>`_
- show you the valid values when you supply an invalid one, one per line and in alphabetical order
- detect common mistakes we've made and have helpful error messages telling you what to do or why you can't do that thing

We love Django, but it does silently fail in many places. In iommi we try our hardest to never let you get stuck with silence as your only company.

Everything has a name
---------------------

We like to think of GUIs as a tree of items like tables, buttons, links
and pages. We want it to be easy to reference an item in this tree so we
can change some property of it, ask it about its configuration, or its state,
and more. This is why iommi requires names for everything. This might seem
overly verbose in the beginning but this is what enables many of the powerful
features of iommi and the robust error handling and error messages.

This philosophy is what enables `Single point customization with no boilerplate`_ via :ref:`dispatching`.

Traversing a namespace is done with `__` when `.` can't be used in normal python syntax
---------------------------------------------------------------------------------------

If you have a class `Car` that has a member `engine` of type `Engine`. Now
let's say you want to create a `Car` with an electric engine. In standard
OOP the `Car` constructor might take an `engine` parameter so you'll end up
with something like:

.. code-block:: python

    car = Car(engine=ElectricEngine())

which is fine if you want to replace the entire engine, but if you just wanted
to configure a small thing but keep all the defaults this can become noisy:

.. code-block:: python

    car = Car(
        engine=InternalCombustionEngine(
            turbo=True,
            cylinders=6,
            gearbox=SequentialGearbox(
                clutch_type='double',
            ),
            color='blue',
            doors=4,
            make='toyota'
            # ...and on and on!...
        )
    )

Now it's impossible to see the intent of the programmer: which of all those
options was the single thing they wanted to change and which are copy paste
of the defaults? Turns out in this case it was just the `clutch_type`! We
would like to write:

.. code-block:: python

    car = Car(engine.gearbox.clutch_type='double')

but Python's syntax doesn't allow this. So instead we use `__`:

.. code-block:: python

    car = Car(engine__gearbox__clutch_type='double')

this is an elegant solution to this problem, one we've stolen from Django's ORM.

That's the motivation. For the mechanical rules -- exactly how `__` maps onto
nested dicts, and how the declarative and programmatic forms correspond -- see
:doc:`equivalency`. For how it is implemented, see :ref:`dispatching`.

Callables for advanced usage, values for the simple cases
---------------------------------------------------------

We want the simple cases to be obvious and simple and the complex cases to
be possible. To enable this we aim to make it so that every place you can
place a value, you can use a lambda. So for example the simple case could be:

.. code-block:: python

    form = Form(
        auto__model=Musician,
        fields__instrument__initial='guitar',
    )

but for the more dynamic case we can write:

.. code-block:: python

    form = Form(
        auto__model=Musician,
        fields__instrument__initial=
            lambda request, **_: 'guitar' if request.user.is_staff else 'tambourine',
    )

In this case you have e.g. `form`, and `field` accessible. If you don't
know which arguments you can use, you can write whatever and you will get an
error message telling you what arguments are available.

Late binding
------------

Late binding allows us to sometimes avoid doing work, but more importantly
it enables us to build more flexible customizations. A concrete example can
be to show a column in a table for only staff users even though the table is
defined in the module scope, long before there even is a request object.

Late binding is accomplished by two mechanisms:

- not creating object structures until the :ref:`bind` phase
- and `Callables for advanced usage, values for the simple cases`_

.. _philosophy_hybrid_api:

Declarative/programmatic hybrid API
-----------------------------------

The ``@declarative`` and ``@with_meta``
decorators enables us to very easily write an API
that can look both like a normal simple python API:

.. code-block:: python

    my_table = Table(
        columns=dict(
            foo=Column(),
            bar=Column(),
        ),
        sortable=False)

This code is hopefully pretty self explanatory. But the cool thing is
that we can do the exact same thing with a declarative style:

.. code-block:: python

    class MyTable(Table):
        foo = Column()
        bar = Column()

        class Meta:
            sortable = False

    my_table = MyTable()

This style can be much more readable. There's a subtle difference though
between the first and second styles: the second is really a way to
declare defaults, not hard coding values. This means we can create
instances of the class and set the values in the call to the
constructor:

.. code-block:: python

    my_table = MyTable(
        columns__foo__include=False,  # <- hides the column foo
        sortable=True,                # <- turns on sorting again
    )

...without having to create a new class inheriting from ``MyTable``. So
the API keeps all the power of the simple style and also getting the
nice syntax of a declarative API.

Prepackaged commonly used patterns (that can still be customized!)
------------------------------------------------------------------

A pattern you'll see often in iommi is that we have class methods instead of
classes. We call these "shortcuts". We don't need to have classes in order to
share functionality and in fact we think this hinders composability and hides
lack of customizability.

A shortcut is a bunch of config (and sometimes a tiny bit of code) that also
has a name. We use these instead of writing e.g. `Field` subclasses. The names of
these shortcuts are also used by the style system to determine what rules to
apply.

An important difference between a traditional class and a shortcut is that the
config in a shortcut are defaults, not hard behavior. That means we can start
with a shortcut that does mostly what we want and then pass one or more
arguments to further refine. Again without writing a class.

Single point customization with no boilerplate
----------------------------------------------

GUIs consist of layers of abstraction like a form containing fields,
fields containing input tags, and a button. But in traditional APIs, to customize the input tag of
a form field row you must subclass several classes even for very trivial
things. Often trivial things also require copy pasting a template and making
a minor change. This leads to lots of code that basically does nothing and it
*hides* the unique and relevant code in the noise of the other cruft around
it that is just copy paste or boilerplate.

In iommi we strive to avoid this by enabling one-off customizations with
*no boilerplate*. To set a CSS style on a specific input field inside a form
that was automatically generated we can write:

.. code-block:: python

    Form(
        auto__model=Album,
        fields__year__input__attrs__style__font='helvetica')

See also `Everything has a name`_

.. _escape-hatches:

Escape hatches included
-----------------------

It's frustrating when a library can't do what you want. But if the library
can't be *extended* to do what you want it's even worse. We aim to include escape
hatches for when you reach the limits of iommi. You should be able to add your
own logic and data without having to subclass or patch the code.

Read the documentation on :doc:`extra` for more information.





Registrations
=============

To make iommi understand the specifics of your code base you can register various handlers and behaviors.

Django custom fields
--------------------

To tell iommi how to handle your custom fields you have these options:


* `register_factory`: register behavior for everything at once
* `register_column_factory`: specific to `Column`
* `register_filter_factory`: specific to `Filter`
* `register_field_factory`: specific to `Field`


You use the `register_factory` function to register your own factory. The simplest way is:

.. code-block:: python

    register_factory(
        TimeField,
        shortcut_name='time'
    )

When iommi then sees a Django `TimeField` it will call the `Column.time` shortcut to create a column, `Filter.time` to create a `Filter` and `Field.time` to create a field.

If you need different behavior for the three classes you need to use the more specific registration functions.

You can also register `None` to tell iommi to just ignore the field type whenever it sees it.

For more advanced behavior you can pass a `Shortcut` instance or a callable that returns a shortcut. This is the iommi definition for booleans:

.. code-block:: python

    register_field_factory(
        BooleanField,
        factory=lambda model_field, **kwargs: (
            Shortcut(call_target__attribute='boolean')
            if not model_field.null
            else Shortcut(call_target__attribute='boolean_tristate')
        )
    )

Related fields (foreign key/many-to-many)
--------------------------------------------

`ForeignKey`, `OneToOneField`, and `ManyToManyField` don't carry their semantic meaning in
a custom type the way a `TimeField` does -- they're all keyed on the *related* model. To
register behavior for them you point at the related model instead of a field class:


* `register_related_factory`: foreign key and one-to-one, for everything at once
* `register_related_column_factory`/`register_related_field_factory`/`register_related_filter_factory`: foreign key and one-to-one, for a specific class
* `register_related_multiple_factory`: many-to-many and one-to-many (reverse foreign key), for everything at once
* `register_related_multiple_column_factory`/`register_related_multiple_field_factory`/`register_related_multiple_filter_factory`: many-to-many and one-to-many, for a specific class

.. code-block:: python

    # foreign key and one-to-one
    register_related_factory(User, shortcut_name='user')
    # many-to-many and one-to-many (aka reverse foreign key)
    register_related_multiple_factory(Role, shortcut_name='roles')

When iommi then sees a `ForeignKey` to `User` it will call the `Column.user`/`Filter.user`/`Field.user`
shortcuts, and a `ManyToManyField` to `Role` will use the `Column.roles`/`Filter.roles`/`Field.roles`
shortcuts. You will need to add those shortcuts on your subclasses of `Column`, `Field`, and `Filter`.

This is the primary mechanism behind :ref:`semantic-models`, see that page for a fuller example.

Rendering of your custom types in a table
-----------------------------------------

iommi renders `bool`, `list`, `set`, `tuple`, `QuerySet` and any type that has a `__html__` method with special logic to make it look nice in a table. If you have a type where you can't or don't want to implement a `__html__` method (or you want more complex rendering) you can plug into this system yourself with `register_cell_formatter`:

.. code-block:: python

    register_cell_formatter(MyType, lambda value, **_: f'hello {value}')

The callable you register gets the keyword arguments `value`, `table`, `column` and `row`.

The search fields of your Django models
---------------------------------------

When searching for an object with `Query` we need to know which fields to use to find the object. This enables the advanced query language to be `my_car_brand='toyota'` instead of `my_car_brand.pk=42` which is a lot nicer. iommi will automatically use a field called `name` if it exists and is unique. If you have other fields you want iommi to use to find objects you can register it like this:

.. code-block:: python

    register_search_fields(model=Album, search_fields=['year'], allow_non_unique=True)

On startup iommi registers just this one particular canonical name for you, since you probably want it. Note also that you can use `__` separated paths here if you have a one-to-one with another model where the name field exists.

Custom styles
-------------

You can register your own styles with `register_style`. By default the style `bootstrap` is used. You can use it as the basis of your custom look and feel or start with the `base` style and work from there.





.. _semantic-models:

Semantic models
===============


The standard way in Django to define models is something like this:

.. code-block:: python

    class User(Model):
        is_active = BooleanField()
        name = CharField()
        person_number = CharField()
        manager = ForeignKey('self', on_delete=CASCADE)
        roles = ManyToManyField(Role, blank=True)

The issue with that is that the semantic meaning of each field is hidden behind the name, and not in the type. The `name`
and `person_number` fields have the same type but should be handled differently. Since iommi shortcut registrations are
based on the type, you can't customize the parsing or rendering of the `person_number` or `birth_place` fields on
the project level via the :ref:`style`.

Moreover in this example the type information alone is not enough for other customization. For `ForeignKey`, by default
in iommi you'll get a select2 drop-down to select from all items in that table. This is not good UX for a location, and
it's probably not good UX for a manager field either as that should most likely exclude non-active users, and/or limited
to users with a certain role.

For `CharField`, the default is to present a text field, but in the above model we want a Swedish "person number", which
has a specific storage format, can accept a variety of input formats that can be unambiguously parsed, and even has a
checksum that can be used to validate that the user input is correct.

A solution to this is to create an additional specialized type to specify semantic model fields:

.. code-block:: python

    class PersonNumberField(CharField):
        pass

This field can then be registered in iommi:

.. code-block:: python

    register_factory(PersonNumberField, shortcut_name='person_number')

Then change the model to use `PersonNumberField`:

.. code-block:: python

    class User(Model):
        is_active = BooleanField()
        name = CharField()
        person_number = PersonNumberField()
        manager = ForeignKey('self', on_delete=CASCADE)

For foreign key, and many-to-many fields it would be cumbersome to make custom classes, so registrations are done slightly differently:

.. code-block:: python

    # foreign key and one-to-one
    # related, related_multiple
    register_related_factory(User, shortcut_name='user')
    # many-to-many and one-to-many (aka reverse foreign key)
    register_related_multiple_factory(Role, shortcut_name='roles')

You will then need to add shortcuts for these in your subclasses of `Column`, `Field`, and `Filter`.

.. code-block:: python

    class Field(iommi.Field):
        @classmethod
        @with_defaults(
            parse=person_number__parse,
        )
        def person_number(cls, **kwargs):
            return cls.text(**kwargs)

        @classmethod
        @with_defaults(
            choices=lambda **_: User.objects.filter(is_active=True),
        )
        def user(cls, **kwargs):
            return cls.foreign_key(**kwargs)

        @classmethod
        @with_defaults()
        def roles(cls, **kwargs):
            return cls.many_to_many(**kwargs)

...and similar for `Field` and `Filter`.

You can also add configuration via the `Style` machinery. This is useful for reusable apps.

Semantic models requires a little bit more initial setup, but for commonly used field types, it will make new views correct by default and super easy to setup.

.. warning::

    The `register_related_factory`/`register_related_multiple_factory` registrations are
    global and keyed on the model type, but the custom shortcut they point at (`user`,
    `roles`, ...) only exists on *your* subclasses of `Column`/`Field`/`Filter`. Any code
    that builds parts from the model using the *base* iommi classes will look up the
    shortcut on a class that doesn't have it and fail with
    `AttributeError: type object '...' has no attribute '<shortcut_name>'`.

    The most common place this bites is the built-in :doc:`admin`, which uses the base
    `Table`/`Form` (and therefore base `Column`/`Field`/`Filter`) by default. To make the
    admin (or anything else that auto-generates from your models) use your shortcuts, point
    it at your subclasses::

        from iommi.admin import Admin as BaseAdmin

        class Admin(BaseAdmin):
            class Meta:
                # so the list view's columns/filters/bulk-form find `.user()`, `.roles()`, ...
                table_class = MyEditTable
                # so the create/edit/delete forms find `.user()`, `.roles()`, ...
                form_class = MyForm

    Note that both `table_class` and `form_class` are needed: `table_class` covers the list
    view, while `form_class` covers the create/edit/delete views.

    The same applies anywhere the auto machinery runs against a model with one of these
    registered relations -- make sure the `Table`/`Form`/`Query` involved use your
    subclasses, not the base iommi ones.



Imports used in the iommi documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



iommi imports
=============

.. code-block:: python

    from iommi import (
        Action,
        Asset,
        Column,
        EditTable,
        EditColumn,
        Field,
        Fragment,
        Form,
        Fragment,
        Header,
        Menu,
        MenuItem,
        middleware,
        Page,
        Part,
        Query,
        Table,
        Filter,
        LAST,
        MISSING,
        register_factory,
        register_field_factory,
        register_filter_factory,
        register_column_factory,
        register_cell_formatter,
        register_style,
        register_search_fields,
        Style,
        html,
        iommi_render,
    )
    from iommi.path import (
        decode_path,
        decode_path_components,
        register_path_decoding,
    )

Django imports
==============

.. code-block:: python

    from django.template import Template
    from django.contrib.auth.models import User
    from django.shortcuts import get_object_or_404
    from django.urls import path

Documentation models
====================

.. code-block:: python

    from docs.models import (
        Artist,
        Album,
        Track,
        Musician,
    )



.. _history:

Changelog
=========
Changelog
---------

7.32.0 (2026-09-11)
~~~~~~~~~~~~~~~~~~~

* Tables now show an error overlay with a retry button when the ajax reload of the table body fails. Previously a failure was silent, and in particular hitting the 5 second `ajaxTimeout` left the stale table in place with no indication that anything went wrong. The timeout now aborts with a `TimeoutError` instead of an `AbortError`, so it is reported through the `iommi.error` event like other failures. The texts can be translated via `iommi.messages`, see the tables cookbook.

* The profiler now uses the statistical sampling engine behind CPython's own sampling profiler when it's available (Python 3.15+), instead of a tracing profiler. The page renders at full speed while being profiled, so the numbers aren't distorted by the measurement. Sampled data has no call counts, so the `ncalls` column shows the number of samples the function was on the stack for. On older Pythons the previous behavior is kept: yappi if installed, cProfile otherwise.

* Fixed: `EditTable` delete checkboxes of newly added rows all got the same id (`id_pk_delete_0`), so only the first added row could be marked for deletion (Thanks Bery!)

* Paginator `aria-label` texts are now translatable, and the `date_parse` error details ("out of range", "unexpected extra characters") are picked up by `makemessages`. Czech translation updated. (Thanks Bery!)

* The docs are restructured into tutorials, how-to guides, reference and explanation. Existing URLs still work.


7.31.0 (2026-06-27)
~~~~~~~~~~~~~~~~~~~

* Simple multi select switch for FK/OneToOne mappings

* Fix warning about `@with_meta` on `Admin`


7.30.1 (2026-06-22)
~~~~~~~~~~~~~~~~~~~

* Running `Model.full_clean` on `Form` create/edit (added in 7.28.0) is now opt-in behind the `IOMMI_FULL_CLEAN = True` setting, since it could break existing installs that rely on `clean()` not running on save. Without it, the previous behavior (validating uniqueness and constraints only) is kept and a `DeprecationWarning` is emitted; the default will switch to full validation in a future release.

* Fixed namespace stacking issue that could interfere with `Style` configuration


7.30.0 (2026-06-22)
~~~~~~~~~~~~~~~~~~~

* An item in the `auto__include` list may now be a dict instead of a plain string. The `attr` key gives the field path and the remaining keys are extra configuration passed to that generated member, e.g. `auto__include=['name', dict(attr='year', display_name='Year')]`.

* Exposed `do_post` and request helpers as public API in `iommi.test_helpers`, with documentation on testing iommi components.

* `.from_model()` resolution for `Field`/`Column`/`Filter`/`EditColumn` is now deferred to `refine_done()` of the parent container. This means you can now use `Field.from_model` without supplying `model` or `model_field`. The `from_model()` call is treated more as a flag for the `auto` machinery than something that needs to resolve the entire thing right there.

  Note: As a consequence, resolution is now deferred until the container is built, so the result is now just a lazy placeholder and any exceptions will now only occur durin `refine_done()` on the container.

* Debug panel improvements, including jump-to-code fixes for FBVs, `Fragment`, and `MainMenu`, and the pick and tree debug panel components are no longer shown for non-iommi views.


7.29.0 (2026-06-17)
~~~~~~~~~~~~~~~~~~~

* Filtering: special case for when you want to have a filter on the pk column of the table you based the model on


7.28.0 (2026-06-12)
~~~~~~~~~~~~~~~~~~~

* `Form` create/edit now runs Django model validation (`Model.full_clean`), so a model's custom `clean()`/`clean_fields()` is called on save. Errors are routed to the matching field, or to the form for non-field errors. Related model instances reached through a nested `attr` (e.g. `attr='artist__name'`) are validated too.

* French translation (Thanks new contributor Pierre de Lépinay!)

* New translatable message for `Field.integer` parsing error


7.27.1 (2026-06-08)
~~~~~~~~~~~~~~~~~~~

* `Table`: the select column should be shown by default if bulk editing is active


7.27.0 (2026-06-05)
~~~~~~~~~~~~~~~~~~~

* Smarter form "next" redirect

* Fixed typing information

* Dropped support for Python 3.11


7.26.0 (2026-06-04)
~~~~~~~~~~~~~~~~~~~

* `extra__report_columns_all=True` option for Table to dump all visible columns into a report


7.25.2 (2026-05-28)
~~~~~~~~~~~~~~~~~~~

* Flamegraph color coding based on stdlib/third-party/app

* Don't allow users to override the `name` html attribute of a form, this breaks dispatch

* Fixed an issue where automatic select_related was triggered instead of automatic prefetch_related


7.25.1 (2026-04-18)
~~~~~~~~~~~~~~~~~~~

* Optimized refinable handling. This should lead to a general speed improvement across iommi. If you accessed `iommi_namespace` directly, you will need to treat it as a dict instead of a struct, or use `.as_namespace()` to get it flattened like before.


7.25.0 (2026-04-07)
~~~~~~~~~~~~~~~~~~~

* `MainMenu`: support per-request `urlconf`

* Fix for defining `Style` directly in settings

* Preserve GET parameters for profiler URLs

* DaisyUI style added

* Moved `setup_db_compat()` back to import time, as having it in `AppConfig.ready()` could cause issues with overriding iommi default behavior.


7.24.1 (2026-03-12)
~~~~~~~~~~~~~~~~~~~

* Switched profiler backend to yappi and improved the processing of the data. This means we now don't get irrelevant output from django_watchfiles, and profiling async views should work.

* Auto `select_related` for nested foreign key access in `Table`

* Fixed handling of the value of `<textarea>` in certain situations

* Fixed duplicate help/error display for checkboxes/radio inputs

* Render `MainMenu` tags in a way that doesn't interfere with the code finder feature


7.24.0 (2026-03-06)
~~~~~~~~~~~~~~~~~~~

* Async environment support. This just means that the iommi middlewares are compatible with an async worker model, so they won't force your entire app into sync mode.

* New profiler flame graph visualizer

* New experimental `Calendar` component

* Added error message when using an `MainMenu` `M` item with `path` but without `url`

* Live edit of styles now work for projects with a custom user model

* Fixed a `Menu` active marker issue on Python 3.14


7.23.0 (2026-02-20)
~~~~~~~~~~~~~~~~~~~

* SECURITY: Fixed open redirect vulnerability

* SECURITY: Further security checks for live edit. It will now only allow localhost connections.

* Endpoints can now be called via POST

* `Query` is now a `Tag`, meaning its outer HTML element is configurable (tag, attrs, id, etc.) instead of being hard-coded to a `div` with a fixed id

* New semantic registration functions for FK/M2M relations: `register_related_factory`, `register_related_field_factory`, `register_related_filter_factory`, `register_related_column_factory`, `register_related_multiple_factory`, `register_related_multiple_field_factory`, `register_related_multiple_filter_factory`, `register_related_multiple_column_factory`

* SQL Trace: click to trigger `explain` for individual queries directly from the SQL trace output

* Fixed `limit_choices_to` for ForeignKey relations - both forward and reverse now work (fixes #441)

* Fixed attribute escape correctness (`&` was not being escaped to `&amp;`). This should not affect anything, but the old code was strictly speaking not following the HTML spec.

* Fixed `MainMenu` bug when `template` is present in style and also passed as an argument

* Live edit works for classes


7.22.1 (2026-01-19)
~~~~~~~~~~~~~~~~~~~

* `MainMenu` did not respect the `template` parameter properly

* `order_by` - don't add `pk` when the last is `-pk`

* Fixed `EditTable` row deleting with changed fields values


7.22.0 (2025-12-28)
~~~~~~~~~~~~~~~~~~~

* New drag&drop file uploader shortcuts for `Form`: `Field.dropfile`/`Field.dropimage`

* `MainMenu` and `M` are now available to import straight from `iommi`


7.21.3 (2025-12-04)
~~~~~~~~~~~~~~~~~~~

* Allow `Column.sortable=True` override. This allows you to turn on sorting for annotated columns


7.21.2 (2025-12-03)
~~~~~~~~~~~~~~~~~~~

* Fixed `SortOrderField` handling of `to`


7.21.1 (2025-12-02)
~~~~~~~~~~~~~~~~~~~

* Admin handles non-int primary keys better

* Fixed admin crash due to missing `Namespace` conversion when reading configuration

* Disallow sorting by default on non-sortable columns


7.21.0 (2025-11-28)
~~~~~~~~~~~~~~~~~~~

* SECURITY FIX: Make admin views respect `apps__*__include`. This meant that admin users that could access the admin but not see a specific model could access that model if they knew the URL.

* Allow MainMenu `assets__foo__include=False` style config

* Fix boolean filter alignment in bootstrap 5 horizontal style

* Use `LOGIN_REDIRECT_URL` instead of `/` as default in the login view

* `Field.choice_searchable` for non-ajax searchable choices


7.20.0 (2025-11-14)
~~~~~~~~~~~~~~~~~~~

* `MainMenu` promoted to stable. If you used it from the experimental import, you have to change your imports.

* Default Django view names for main menu items. This is useful for `reverse()`/`{% url %}`

* Improved FBV support. See the updated docs for FBVs.

* Bugfix for `M`: ensure parameters are satisfied before calling `include`. Thanks to first time contributor Sam Mangham!


7.19.3 (2025-11-07)
~~~~~~~~~~~~~~~~~~~

* Improved handling of language header, which makes it nicer to use FBVs with iommi parts.

* An unbound `Refinable` object will now raise an error if you try to render it in a template.

* Added an error message for invalid `default_sort_order`. The old behavior was that it was silently ignored if invalid.


7.19.2 (2025-10-29)
~~~~~~~~~~~~~~~~~~~

* Restored Python 3.11 support that was accidentally broken with an advanced f-string. This time works :P


7.19.1 (2025-10-29)
~~~~~~~~~~~~~~~~~~~

* Restored Python 3.11 support that was accidentally broken with an advanced f-string


7.19.0 (2025-10-23)
~~~~~~~~~~~~~~~~~~~

* New system to do complex layouts for forms and table rows: `Panel` + `Form.layout` + `Table.row__layout`

* Fixed a crash inside error handling when passing invalid callables to `attrs`

* Table `auto_rowspan` feature was broken if you tried to apply it to more than one column


7.18.1 (2025-10-20)
~~~~~~~~~~~~~~~~~~~

* In enhance query form, remove the actions container if it becomes empty when removing the filter button

* Cleaned up advanced filter html structure

* Render query_error div with "hidden" css class initially if there are no errors

* Don't require integer PKs in in admin urls (for example UUIDs are now also supported)

* Only report template usage once in debug menu, and make the order stable


7.18.0 (2025-10-08)
~~~~~~~~~~~~~~~~~~~

* Table headers pick up the ordering from the QuerySet/Model automatically

* `call_target` handling significantly improved. This enables easier customization for `auto__model` uses.

* Use `create_or_edit_object_redirect` in `save_nested_forms`

* Allow `redirect_to` as a callable


7.17.0 (2025-09-15)
~~~~~~~~~~~~~~~~~~~

* Manually reorderable `EditTable`

* `MainMenu`: don't render disclosure triangle for menu items where all subitems are non-rendered


7.16.0 (2025-09-12)
~~~~~~~~~~~~~~~~~~~

* `EditTable` support for `create_form.extra.new_instance`

* Fixes for `EditTable` nesting inside `Form`

* New setting for `Form`: `nested_forms_abort_save_on_fail` which will early abort instead of late abort on error.

* `M.render` option to control if a menu item should be rendered


7.15.1 (2025-09-02)
~~~~~~~~~~~~~~~~~~~

* Fixed issue with code finder when there is no current request


7.15.0 (2025-09-02)
~~~~~~~~~~~~~~~~~~~

* New debug tool: Code finder. Use this tool to jump to a place in your template close to the html element you click on.

* Removed an incorrect `form-select` CSS class on `<select>` elements for bootstrap5.

7.14.5 (2025-08-02)
~~~~~~~~~~~~~~~~~~~

* Fixed `EditTable` "Add row" button when it was the single `Part` on a page.


7.14.4 (2025-06-27)
~~~~~~~~~~~~~~~~~~~

* Fixed issue with `Table` crashing in some cases when pagination is turned off

* `EditTable` handling of adding rows is now done via ajax, improving flexibility

* `EditTable` delete button fixes

* `EditTable` fix `Field.non_rendered` and `Field.initial`

* `EditTable` should not try to save non-editable fields

* `Form`: Support overriding `model_object.save()` to be able to pass kwargs


7.14.3 (2025-06-10)
~~~~~~~~~~~~~~~~~~~

* Enable filtering on a table on itself by handling `attr=None`, and document the behavior

* Don't fail with `EditTable` having `Field.editable=False`

* Minor fix to error messages for `InvalidEndpointPathException`


7.14.2 (2025-06-04)
~~~~~~~~~~~~~~~~~~~


* `EditTable` delete button fixed for dynamically added rows

* Fixed `EditTable` not displaying new rows with validation errors

* Fixed a crash in `Table` where the code tried to read the default sort order from a model when there was no model present


7.14.1 (2025-05-21)
~~~~~~~~~~~~~~~~~~~

* `M.icon` should support callables


7.14.0 (2025-05-21)
~~~~~~~~~~~~~~~~~~~

* `MainMenu`: support for dynamic subitems for `M` objects

* Fix regression with Admin failing when there is no apps config


7.13.0 (2025-04-24)
~~~~~~~~~~~~~~~~~~~

* Basic support for `GeneratedField`

* `class Meta` handling changes. This should resolve some config stacking order surprises.

* `MainMenu`: `http` urls should also count as external links


7.12.1 (2025-03-26)
~~~~~~~~~~~~~~~~~~~

* `EditTable.create_form` should be able to be `None` to remove the add row feature

* Fixed crash on admin "all models" page


7.12.0 (2025-03-26)
~~~~~~~~~~~~~~~~~~~

* Support sorting before a named field with `after`. Specify `<foo` to sort before `foo`, and you can also explicitly sort after with `>foo`.

* `MainMenu`: added `extra` and `extra_evaluate`

* `Table` rendering is now up to 20% faster

* Fixed bulk 'all items on all pages' with multiple tables on a page

* `M` `<a>` tags should render `title` attributes, not `alt`

* `Field.password` should never render out password in the html, not even for validation errors

* Password change form should have semantic attrs to specify that it's password change

* Set autofocus via attrs instead of JS

* Admin: set password previously set the encrypted password. Now you can type the password like you'd expect.

* Admin: support `MainMenu` based apps

* Admin: styling fix for "all models" page

* Admin: should not be hardcoded to bootstrap style

* Admin: don't show add row/save on "all models" page

* Improved translations

7.11.2 (2025-03-11)
~~~~~~~~~~~~~~~~~~~

* The previously hardcoded `menu` CSS class on the `MainMenu` has been moved to the style definition, and the default changed to `main_menu`.

* The main menu template variable `menu` was renamed `main_menu`.


7.11.1 (2025-03-08)
~~~~~~~~~~~~~~~~~~~

* Introduce `Style.icon_formatter` to handle creating icons across icon libraries. So far only implemented in `MainMenu`.

* `MainMenu` external URLs fix


7.11.0 (2025-03-05)
~~~~~~~~~~~~~~~~~~~

* New `MainMenu` component added. This is marked as experimental, which means it can contain breaking changes in minor versions of iommi.

* Translation fixes for multi-language installs.

* The select2 component got some style fixes for bootstrap 5 dark mode.

* Respect declaration order of `EvaluatedRefinable`


7.10.1 (2025-02-18)
~~~~~~~~~~~~~~~~~~~

* Fixed missing end tag in error output for `Table`


7.10.0 (2025-02-17)
~~~~~~~~~~~~~~~~~~~

* Add scroll restore for `Form`

* Support `IntegerField` with `choices`

* Advanced filter js, and css as separate assets

* Stable ordering when paginating by adding automatic sorting on `ordering` plus pk

* Using `auto__rows` without `model` on an `EditTable` crashed

* Fixed incorrect rendering of global errors on `Table`

* Fixed invalid HTML output on error feedback page for `EditTable`

* Move declarations of assets and endpoints from Traversable down to Part. This can fix some obscure errors during style definitions.

* `non_editable_input` `attrs__disabled` moved to base style + added textarea. This will make some styling possible that was not possible before.


7.9.1 (2025-01-17)
~~~~~~~~~~~~~~~~~~

* Fixed crash when specifying `Field.parsed_data` callback and the field was not editable

* Improved error messages for evaluation


7.9.0 (2025-01-14)
~~~~~~~~~~~~~~~~~~

* Add support for `related_query_name`

* `auto_rowspan` on a generator gives an empty table

* Admin: configurable grouping of models


7.8.0 (2024-12-12)
~~~~~~~~~~~~~~~~~~

* Allow throwing `str` and `Template` into `Form.fields`

* Add `root` object into evaluate parameters to easier be able to access sibling components

* Allow `Table` `DataRetrievalMethods` to be specified as a string

* Fix empty QuerySet on invalid Query. To not make e.g. .annotate in postprocess_rows trip up.

* Required as a lambda on a `Field` was broken

* `Query`: on errors on ajax reload, show the errors


7.7.2 (2024-11-26)
~~~~~~~~~~~~~~~~~~

* Add support for "T" separator in `datetime_iso_formats`

* Fix `Field.hardcoded` to be hidden even when Field has template styling

* Table: header__template=None and header__include should both stop the header from rendering


7.7.1 (2024-11-20)
~~~~~~~~~~~~~~~~~~

* Added back `extra__is_create`

* SQL trace: links to switch SQL trace output mode easily


7.7.0 (2024-10-22)
~~~~~~~~~~~~~~~~~~

* Upgrade bootstrap to 5.3.3 and enable automatic dark mode

* Profiler middleware can now detect some incorrect middleware ordering

* `Field.email` should force lowercase


7.6.0 (2024-10-15)
~~~~~~~~~~~~~~~~~~

* New `crud_views()` function added

* New `login`, `logout`, and `create_password` views added. You can install them all with `auth_views()`

* Fixed a crash in `Form.delete()`

* Don't crash on label mapping missing

* Added "Vanilla CSS" CSS framework

* Make it possible to target the `<thead>` of a table with configuration


7.5.2 (2024-09-30)
~~~~~~~~~~~~~~~~~~

* `attrs__class`/`attrs__style` didn't evaluate lambdas for class names that contained `__`

* Enable inserting child parts into `Field.label`


7.5.1 (2024-09-28)
~~~~~~~~~~~~~~~~~~

* Tables: format `TextField.choices` according to the display name from the model

* `extra_params` was not evaluated if path decoding was not performed

* Enable translations for `js_select_all.html`: "Select all" etc.

* Drop support for IE11


7.5.0 (2024-09-19)
~~~~~~~~~~~~~~~~~~

* Optimized fragment rendering. This can have very significant performance improvement across all iommi views.

* Added style definition for US Web Design System

* Fix `Action.icon` rendering and customization. It now matches the api of `Column.icon` more closely.

* Nested forms save post handler should also save EditTables


7.4.0 (2024-08-21)
~~~~~~~~~~~~~~~~~~

* `Table.empty_message` and `Table.invalid_form_message` now supports callables

* Invalid filters should present empty search results in tables

* Support css class names containing `__`


7.3.0 (2024-08-06)
~~~~~~~~~~~~~~~~~~

* Added `Form.create_or_edit` shortcut.

* The default filter behavior for `Column.datetime` now filters on the date and not the exact microsecond.


7.2.2 (2024-07-15)
~~~~~~~~~~~~~~~~~~

* `EditTable` support for one-to-one fields

* Chinese translation fix


7.2.1 (2024-06-18)
~~~~~~~~~~~~~~~~~~

* Fix field grouping in bootstrap5 style

* Respect advanced search query in bulk operations


7.2.0 (2024-06-11)
~~~~~~~~~~~~~~~~~~

* Make custom row templates more useful by allowing to call the default rendering, and access the column count easily


7.1.1 (2024-05-07)
~~~~~~~~~~~~~~~~~~

* Namespace separation for `evaluate_member`. If you had a param named `obj` or `key` you could get a namespace conflict and a crash.


7.1.0 (2024-05-06)
~~~~~~~~~~~~~~~~~~

* `user` is now included in the evaluate parameters

* All params from `params` are now included in evaluate parameters

* Fix bulk form render when not needed

* Admin: remove default bulk delete

* Select all fixed

* Admin all models list should be `Table`, not `EditTable`


7.0.0 (2024-04-15)
~~~~~~~~~~~~~~~~~~

* `EditTable`s `EditColumn.edit` namespace is now called `field`. This is a breaking change. There was a namespace conflict between `Column.edit` and `EditColumn.edit`.

* `EditTable` and bulk editing and filtering now compose cleanly

* Changed default style to Bootstrap 5

* Allow styling of `EditTable`/`EditColumn`

* Nested forms respect if the parent form is non-editable

* SQL trace for N+1 problems will now print the last found query+traceback instead of the first. This should increase the odds of it showing something useful.

* Removed deprecated JavaScript functions


6.8.0 (2024-03-27)
~~~~~~~~~~~~~~~~~~

* `table.Column.boolean` changed from fontawesome icon to unicode check mark

* `<meta>` viewport by default

* `SearchVectorField` default None factory

* select2 change triggers form change, but field can be outside a form for js purpose

* Move the data-endpoint and data-iommi-id html attributes to the table container. This is to avoid them being over-written by any empty_message provided resulting in no table tag being rendered

* added `IommiBase.getContainer` in JS

* `default_sort_order` should be indicated in the table header

* Don't fail on non-integer pk values on pk lookup

* Fix for rare synthetic traceback issue


6.7.0 (2024-01-24)
~~~~~~~~~~~~~~~~~~

* Added support for DurationTime db field type

* Add missing parameters to attrs and tag callbacks (#501)

* Added option to pass kwargs for `csv.writer` (#503)

* `Field.is_valid()` respecting model field validators by default (#506)

* Fixed profiler output for function names (#502)

* Removing preserved page, to always jump to the first page after filtering (#500)


6.6.0 (2024-01-15)
~~~~~~~~~~~~~~~~~~

* Add new callback `Filter.pk_lookup_to_q` for building custom filter even when filter value is a model object.


6.5.0 (2024-01-09)
~~~~~~~~~~~~~~~~~~

* Improved HTML output of profiler. Clickable links for functions, and sorting.

* Preserving filters from other table filters and sorting (fixes #496)

* If you had `?order=` in your URL without value, you got `IndexError` (string index out of range) (fixes #495)

* Documentation fixes by first time contributor Viktor <dpedesigns@hotmail.com>


6.4.0 (2023-12-13)
~~~~~~~~~~~~~~~~~~

* Django 5.0 support

* New debug tools: Templates used. You can use this to see what templates were used, and jump to them.

* Form based choice_queryset should go pk in the query always (fixes #443)

* Translation update (fixes #457)

* Updated Swedish translation

* Debug: Don't shorten paths, as this makes links un-clickable in pycharm console

* Optimizations


6.3.0 (2023-10-24)
~~~~~~~~~~~~~~~~~~

* Edit table: support non-rendered and hardcoded column

* Edit table: create rows in the order given in the GUI

* Improvements to transaction handling in the middleware: The middleware should have the same atomic behaviour as django BaseHandler.make_view_atomic

* You can now use iommi's profiler on form POST requests. Click the "Profile POST" button then press submit on the form you wish to profile.

* Tables/queries: Filtering on numbers broken

* Fixed bootstrap styling to style numeric input as right aligned


6.2.0 (2023-09-26)
~~~~~~~~~~~~~~~~~~

* Added `iommi_head_contents_last` block to `base.html`

* Fixed `models.CharField(choices=..., blank=True, null=False)` validation

* `Column.select` didn't handle models with UUID primary keys

* Datetime rendering should be in local time format, not UTC

* Fixed for Python 3.11

* Sort links on table ajax reloads

* Fixed lazy capitalization of titles

* Added Czech translation

* Warn if user has forgotten to add iommi to `INSTALLED_APPS`

* Fixed translation context for "Filter" (The verb and the noun are the same in English, so there was some confusion)

* Fixed translations

* Prevent double save on files/images when over the in-memory limit

* Added `Form.fields_template`

* Avoid crash on admin pages when running without `iommi.middleware`


6.1.1 (2023-08-25)
~~~~~~~~~~~~~~~~~~

* `JSONField` was incorrectly handled in Django 3.1+

* Dropped support for Django 3.0


6.1.0 (2023-08-21)
~~~~~~~~~~~~~~~~~~

* `Field.checkboxes` added

* `parse_empty_string_as_none` not working properly with choice

* Fix `EmailField` / `URLField` with `required=False`

* Allow inheritance for `class Meta`

* JS crash on inter-page link navigation (like `foo/#something`)

* Don't crash if `page_size` not integer (Thanks to new contributor Oana!)


6.0.0 (2023-08-16)
~~~~~~~~~~~~~~~~~~

* JS refactoring of table filtering. This drops Axios as a dependency. (Thanks Bery!)

* `Field.is_valid` callback should handle raised `ValidationError`

* Added `Field.hardcoded`

* Fix setting `display_name` on `freetext_search` field implying required

* Fixed filter form reset (thanks Bery!)

* Dropped `invoke_deprecated_callback`

* Removed support for deprecated arguments `checked` and `checkbox_name` for `Column.select`

* Removed deprecated `register_advanced_path_decoding`, and the corresponding old syntax for `register_path_decoding`


5.13.0 (2023-05-10)
~~~~~~~~~~~~~~~~~~~

* Fix regression in 5.12.0 where tables fail to calculate filter choices on optional columns.


5.12.0 (2023-04-26)
~~~~~~~~~~~~~~~~~~~

* More blocks to customize the base template: `iommi_html_tag_attrs` and `iommi_html_tag_attrs`

* Added `Table.table_tag_wrapper` for when you want to wrap the `<table>` tag but not the paginator. This is useful for making apps work better on phone layouts.

* Insert the language code into the `<html>` tag.

* Generate deprecation warnings in all places not yet passing standard callback parameters

* Choices now passes correctly downstream from `Column(choices=...)` to the filter, the filters form, and bulk fields.

* The admin now can be inserted into the url patterns inside a named app (thanks Mickey McClellan)


5.11.0 (2023-04-08)
~~~~~~~~~~~~~~~~~~~

* Ukrainian language support (Thanks Yury Bulka!)


5.10.1 (2023-04-06)
~~~~~~~~~~~~~~~~~~~

* `OneToOneField` reverse mapping should use the singular field name. This was a regression introduced in 5.8.0 when ManyToMany reverse support was fixed. (Thanks Yury Bulka!)


5.10.0 (2023-04-05)
~~~~~~~~~~~~~~~~~~~

* Fix issue with filter fields not being hidden when the corresponding column is hidden.

* Fix `extra__redirect` not getting all parameters.

* Fix `Form.editable` to have truthy semantics, not requiring strictly `False`

* CRUD Form default title should be done lazily, since instance might be a lambda


5.9.0 (2023-03-28)
~~~~~~~~~~~~~~~~~~

* `iommi.forms.save_nested_form` added. This is useful for when you want to save multiple forms with one submit button.

* Fixed admin defaults to have lower priority so you can properly override them.

* Added dummy factory registration to not crash on `GenericRelation` and `GenericForeignKey`

* Forms: check `model.validate_constraints()` on Django 4.1+ (Thanks Yury Bulka!)

* Enable users to disable full form state sending on select2 ajax. To disable, set the `data-select2-full-state` attribute to `false` on the form.


5.8.1 (2023-02-28)
~~~~~~~~~~~~~~~~~~

* Fix bug where form submit include dispatch parameters e.g. bulk forms break after table tbody reload.


5.8.0 (2023-02-14)
~~~~~~~~~~~~~~~~~~

* ManyToMany reverse support

* Live editing of styles

* Fixed crash when using form field groups and bootstrap

* Basic support for the UIKit CSS framework added


5.7.1 (2023-02-08)
~~~~~~~~~~~~~~~~~~

* Add `request` parameter to `extra_params` callback.


5.7.0 (2023-02-01)
~~~~~~~~~~~~~~~~~~

* Make `Column.select()` more suitable to customization

* Unify callback parameters for `cell__value` and `cell__format`

* Make .as_view be lazy with refine_done to not explode import times

* Added `extra_params` callback to sneak in parameters while porting old-style view code

* Added `Field.non_rendered` shortcut

* `sort_after` raises `SortAfterException` instead of `KeyError` to improve error message rendering in debug page (`KeyError` did `repr(message)`)

* Bootstrap style fix for grouped fields when using select2

* Fixed examples project scrape code

* Move Form style template definition to be more of an overridable default


5.6.2 (2022-12-16)
~~~~~~~~~~~~~~~~~~

* CSV export and row_group didn't work together


5.6.1 (2022-12-08)
~~~~~~~~~~~~~~~~~~

* Row grouping on `EditTable` now works.


5.6.0 (2022-12-06)
~~~~~~~~~~~~~~~~~~

* Added row grouping feature on `Table`

* Allow pre-invoking `.refine_done()` on parts of pages for optimization.

* Optimization of excessive attempts to invoke callbacks


5.5.0 (2022-11-30)
~~~~~~~~~~~~~~~~~~

* Support reverse foreign key relationships

* Improved handling of unknown database field types: don't crash if they are not included anyway

* API docs are much improved, and all docs have been improved with updated tooling to automatically catch future errors

* Admin: copy to clipboard of conf. This  should make it even faster to customize your admin.

* Profiling page: links to graph and snakeviz profiling views

* Render "loaded templates" where templates are normally accepted

* Fix missing crud form header when not using `auto__`

* Add default message to delete form when there are no specified fields

* Fix Column.from_model still require model parameter

* Make `h_tag` respect `sort_after`

* Admin: Fixed display of help text

* Derive missing config when from_model only gets model_field parameter

* Some optimizations when you can reuse an object from `on_refine_done`.

* Minor bootstrap5 style fixes

* Fix cache key snafu in parameter matching cache for evaluate


5.4.0 (2022-10-26)
~~~~~~~~~~~~~~~~~~

* Add `sorter` configuration to `Table` for when rows need special handling on sorting.


5.3.1 (2022-10-24)
~~~~~~~~~~~~~~~~~~

* Fix regression in 5.3.0 moving javascript assets


5.3.0 (2022-10-20)
~~~~~~~~~~~~~~~~~~

* New path decoding API

* Form data for filled fields should be sent with select2 ajax callbacks (the documentation said we did this :P)

* Fix EditTable save on ManyToMany fields

* The default SQL tracer didn't output to the console

* If a create form is not valid the save post handler should not try to build an instance

* Drop support for django <3.0, Add tests for django 4.1

* Drop python 3.7

* Introduce Traversable.invoke_callback(...) helper function with better error reporting


5.2.1 (2022-10-03)
~~~~~~~~~~~~~~~~~~

* Fix regression in 5.2.0 after fixing include directive on filter form fields


5.2.0 (2022-09-16)
~~~~~~~~~~~~~~~~~~

* Insert arbitrary parts in Table. There is a namespace `outer` on table where you can insert things.

* Filter form fields failed to respect include directive from filter

* Fix for live edit when used with iommi path decoding

* Fixed a crash in the debug tree that sometimes happened if you had an non-editable `Field`

* Live edit internal API is now a bit more flexible, making it possible to adapt it to your own use cases better


5.1.2 (2022-09-02)
~~~~~~~~~~~~~~~~~~

* Late evaluation of `Field.editable`, so you can now give a lambda for `editable`

* Rare crash when Field.on_bind tries to access form.all_fields, that is removed

* Admin debug message was shown in non-debug


5.1.1 (2022-08-25)
~~~~~~~~~~~~~~~~~~

* Add group name of form group specifier to lambda args when rendering the corresponding tags


5.1.0 (2022-08-12)
~~~~~~~~~~~~~~~~~~

* Admin: respect django permissions system

* Compatibility with Python 3.11

* Enable usage of `reverse_lazy` with `redirect_to`

* Allow `redirect_to` to be an instance of `django.utils.functional.Promise` that is a proxy for a string (which is what `reverse_lazy` returns)

* Admin delete page should present 404 page on non-existing object

* Menus should attempt to respect query parameters when doing set_active


5.0.0 (2022-05-12)
~~~~~~~~~~~~~~~~~~

* Dependencies tri.declarative and tri.struct are merged into iommi and are thus no longer required. You should remove them from your project and fix your imports to only import from iommi if you had imports from `tri_struct` or `tri_declarative`.

* Fixes for how style definitions are merged. This fixes an issue where select2 wasn't used properly in table filters.

* Refurbished priority for settings on refinable objects. E.g style settings can now overwrite things declared by
  shortcuts.

* Fixed paginator and select2/choice/radio control when django is configured to use thousands separator

* Drop Field parameters `choice_to_option` and `empty_choice_tuple`

* Drop `Style` parameter `assets`. Assets parameters now strictly go in `root__assets`

* Silenced deprecation warning from Django for app configs

* Improved error messages

* Workaround for crash deep in pytest internals when using synthetic traceback

* Separate `Form.edit` from `auto__` machinery

* Introduced new decorator `@with_defaults` for giving parameters in shortcuts in a more natural way.

* Introduced new decorator `@superinvoking_classmethod` to enable a classmethod to call a base class implementation
  with the same name. Useful when declaring more specific shortcuts when customizing using inheritance.


4.7.0 (2022-04-01)
~~~~~~~~~~~~~~~~~~

* Improved exceptions: you now get an exception frame that points to the declaration if you use the declarative style. This makes it much easier to know what code is responsible for a crash.

* Fixed CSV rendering endpoint and added an example for it

* `EditTable` is no longer experimental!

* Fix rendering of choices in filter select widgets from CharField with choices

* Bulk editing: fields should be default None, even if the model has a default value

* Fixed rendering of disabled checkbox


4.6.0 (2022-03-02)
~~~~~~~~~~~~~~~~~~

* Chinese translation

* Base style no longer includes the select2 assets

* h_tag should be possible to set to None and to set include=False

* Fixed default handling for get_sql_debug

* Fixed issue where you couldn't set non-editable input tag to 'input'

* Fix auto rowspan. It was broken if you did multiple bind() on the same object

* Live edit improvements: Handle slower pages MUCH better, and editing of classes works

* Fixed styling for non-editable select2


4.5.1 (2022-01-12)
~~~~~~~~~~~~~~~~~~

* Minor fix for SQL tracing when function names could not be retrieved


4.5.0 (2022-01-11)
~~~~~~~~~~~~~~~~~~

* Path decoding feature added. See https://docs.iommi.rocks//path.html

* New style: `bootstrap5`. Thanks to Nigel Metheringham!

* Expose `perform_dispatch` for legacy FBVs. See https://docs.iommi.rocks//legacy_fbv.html for how to use it.

* Forms: Some asserts to make `redirect`/`redirect_to` more fool proof

* Forms: A little check to make setting `search_fields` on a `Field` more fool proof


4.4.0 (2021-12-22)
~~~~~~~~~~~~~~~~~~

* Send full state of current form when doing ajax select2 callback, enabling more advanced filtering

* Fixed bug where `auto__include=['fk__charfield']` crashes

* Fixed bug where style application on an object only had an effect on the child objects

* `Form.delete` will now show a nice error message if the object can't be deleted due to restricted rows

* `EditTable`: Add row feature added

* `EditTable`: Delete row feature added

* `EditTable`: `field` on an `EditColumn` now match the behavior of `field` for a normal `Form`


4.3.3 (2021-12-09)
~~~~~~~~~~~~~~~~~~

* `EditTable`: Fixed auto__rows

* `EditTable`: if instance.pk < 0, treat this as a create

* Passing `search_fields` to a `Field.choice_queryset` did nothing



4.3.2 (2021-12-06)
~~~~~~~~~~~~~~~~~~

* `EditTable` can now be nested inside a `Form`, similar to how forms can be nested in forms.

* Make it possible to turn off freetext_search query form field by passing `None` as config.

* Optimized writing for `EditTable`

* Several fixes for `EditTable`. Basically it works now :)


4.3.1 (2021-11-30)
~~~~~~~~~~~~~~~~~~

* Due to a mistake in packaging the experimental feature EditTable was not included in previous release. This is now fixed.


4.3.0 (2021-11-30)
~~~~~~~~~~~~~~~~~~

* Freetext field could be shown when it shouldn't, causing a crash on search

* Experimental feature: `EditTable`. Import `iommi.experimental.edit_table.EditTable`. This API can change at any time and also move away from `experimental`.

* Logout redirect for `Form.edit`/`Form.create` now follows `settings.LOGOUT_REDIRECT_URL`

* Nicer error message for missing `parso` install

* Fixed error for when you specify conf in a way that isn't supported. This would silently ignore the configuration before.


4.2.0 (2021-11-18)
~~~~~~~~~~~~~~~~~~

* Field groups in forms. There is a new string `group` member on `Field` that is used to group, a `group` namespace on `Form` you can use to set attrs, tag, etc. Global styling for form groups is done via the `FieldGroup` class. The bootstrap style has been updated to support this feature out of the box.

*  Validation could be bypassed for forms if they have been saved via `form.refine_done()`. This became the default behavior for `.as_view()` in iommi 4.1 so that release is broken.


4.1.0 (2021-11-15)
~~~~~~~~~~~~~~~~~~

* `as_view()` calls `refine_done`, giving you a nice little performance win for free

* Introduce `@iommi_render` view decorator. Use this to get correct behavior when using transactions by default in views. The iommi middleware will now produce an error if you try to use it incorrectly.

* Re-initializable select2 enhancement. If you dynamically modify with javascript you can call `iommi_init_all_select2` to re-initialize iommi select2 components

* Break out the select2 enhancement from the base style into a separate `select2_enhanced_forms` style, and added it to all the built in styles. If you have a custom style that extended `base` you must now also add `select2_enhanced_forms` to that style to get the same behavior as before.

* should_ignore_frame() is more robust against acrobatic frames. This is a rather obscure bug that won't affect normal iommi usage.


4.0.0 (2021-11-01)
~~~~~~~~~~~~~~~~~~

* Dropped support for `__` in names of declared columns/fields/filters (deprecated since 3.2.0)

* Big internal refactoring. You should see some performance improvements across the board.


3.4.0 (2021-10-22)
~~~~~~~~~~~~~~~~~~

* Ability to customize the `Cell` and `Cells` classes used by `Table` rendering

* Improved ability to customize `Table.tbody`. You can now add html after or before the rows from the table itself

* Template-based rendering should get iommi_evaluate_parameters as context. This was the case in some cases but not all, most notably when rendering a `Fragment`.


3.3.0 (2021-10-20)
~~~~~~~~~~~~~~~~~~

* Added snakeviz profiling (use it by passing `_iommi_prof=snake` as a url parameter)

* Fixed stack traces in SQL tracing

* Fixed jump to code for several scenarios

* German translation fixes and updates

* Improved error message for invalid admin config

* `write_nested_form_to_instance` now takes keyword arguments


3.2.2 (2021-10-01)
~~~~~~~~~~~~~~~~~~

* Fix bug causing any endpoint invocation of table fields to force a bind of the paginator (Which should be lazy)


3.2.1 (2021-09-24)
~~~~~~~~~~~~~~~~~~

* Fix enforcement on `required=True` on `Field.multi_choice` and others where value is a list.


3.2.0 (2021-08-23)
~~~~~~~~~~~~~~~~~~

* Names with underscore are deprecated and will be removed in the next major version. This means you can no longer write this:

.. code-block:: python

    class MyTable(Table):
        foo__bar = Column()

You must now instead write:

.. code-block:: python

    class MyTable(Table):
        some_name = Column(attr='foo__bar')

Using `foo__bar` had some weird consequences like you not being able to later target that name without getting ambiguities in what `__` meant.


3.1.1 (2021-06-18)
~~~~~~~~~~~~~~~~~~

* Expand ajax reload on filter change of tables to also include the bulk form. If not done, the bulk options are not in sync with the filtering.

* Remove reference to non-existent `errors.html` in bootstrap style

* Make `Table.visible_rows` non-lazy and not a property

* `Table.rows` is no longer a property


3.1.0 (2021-06-09)
~~~~~~~~~~~~~~~~~~

* Form: Evaluate parameters now contain instance

* Use the same redirect logic for delete as create/edit. This means you can now use `extra__redirect` and `extra__redirect_to` for delete too

* When stopping the live editing, a full runserver restart is now triggered so you get the new code you just edited


3.0.0 (2021-05-24)
~~~~~~~~~~~~~~~~~~

* Styles have a new `sub_styles` parameter. This change greatly simplifies how you set up a custom style for your project if you want to customize the query form.

* `IOMMI_DEFAULT_STYLE` can now be a `Style` object

* Breaking change: The horizontal styles are removed and replaced with the substyle feature. If you use for example `'bootstrap_horizontal'`, you need to replace it with `'horizontal'`.

* Mixed case filter fields didn't work

* Respect browsers preferred dark/light mode for profiler and sql tracer


2.8.12 (2021-05-18)
~~~~~~~~~~~~~~~~~~~

* Major bug: tables based on querysets would implicitly use the django result cache. This resulted in the contents of the table not changing until after process restart


2.8.11 (2021-05-07)
~~~~~~~~~~~~~~~~~~~

* `Fragment` should have `@with_meta`

* Fixed nesting tables inside forms. This would previously crash with a strange error message.

* Avoid infinite loop in sort_after on too large indices


2.8.10 (2021-04-28)
~~~~~~~~~~~~~~~~~~~

* Read defaults from model for initial of fields

* Increased log level of SQL logging from 11 to 21 (DEBUG+1 -> INFO+1)

* Added null factory for `JSONField`

* Fixed live editing code to use the same logic as 'jump to code' to find the code

* Fixed one case where live edit broke

* Prettier debug menu for live editing

* Prettier query help text (thanks new contributor flying_sausages!)


2.8.9 (2021-03-08)
~~~~~~~~~~~~~~~~~~

* Fixed bad html escape in SQL trace magnitude graph (this is not a security problem, as it's a developer tool with very restricted access)

* Renamed freetext to freetext_search. It was too easy to collide with a user defined model with a field called freetext


2.8.8 (2021-02-23)
~~~~~~~~~~~~~~~~~~

* Automatically generating a Query from a model with a foreign key was broken in cases where the name field wasn't the same as name field of the parent model


2.8.7 (2021-02-22)
~~~~~~~~~~~~~~~~~~

* Make it possible to pass a lambda to title of Page/Form/Table

* Improved error when trying to register an already registered style


2.8.6 (2021-02-19)
~~~~~~~~~~~~~~~~~~

* Revert to the old (pre 2.8.2) way of using `search_fields` to compose queries.

  The new approach failed for cases when there was a custom `value_to_q` definition.
  A proper fix needs to have a unified approach also when using `.pk` format.


2.8.5 (2021-02-17)
~~~~~~~~~~~~~~~~~~

* Render title of `Page` objects. To turn off the rendering of the title pass `h_tag__include=False`.

* Removed the register_search_fields warning, it was 90% annoying and 10% useful


2.8.4 (2021-02-15)
~~~~~~~~~~~~~~~~~~

* Form: support passing instance as a lambda, even in combination with `auto__model`


2.8.3 (2021-02-14)
~~~~~~~~~~~~~~~~~~

* Removed bad assert that prevented passing instance as a lambda for auto__model of Form

* SQL trace was broken for postgres

* query_from_indexes should automatically generate filters for foreign keys. This especially affected the admin.


2.8.2 (2021-02-09)
~~~~~~~~~~~~~~~~~~

* Avoid using `search_fields` when composing queries from model filter values. Always using the `.pk` fallback approach is more stable when the search field values might not be unique. This will remove a bunch of warnings that weren't very helpful too.

* Fixed crash when setting `query__include=False` on `Table`

* `capitalize()` now handles safe strings properly. This will enable you to pass safe strings to `title` for example.

* Translation of Yes/No

* Fixed error message for `register_search_fields`

* Updated to fontawesome 4.7

* Renamed live edit asset to not conflict with the name 'custom' which might be fairly common

* Nicer title in the admin for apps


2.8.1 (2021-02-01)
~~~~~~~~~~~~~~~~~~

* Auto generated tables had "ID" as the column name for foreign keys, instead of the name of the remote model.

* Profiler fixed: the bind and render of iommi objects that were handled by the middleware weren't profiled

* Fixed live edit to work for views with URL arguments

* Handle settings.BASE_DIR as Path objects

* fix bulk__include = False on table

* Make DebugMenu created on demand to avoid setting of breakpoints when debugging your own code

* Models in admin are now in alphabetical order

* `Field` is not a `Tag`, so you can render a `Form` as a div if you want.

* The root menu item for the iommi admin was broken if you inherited from Admin

* Force the live edit view to be bootstrap. This avoids the live edit feature looking a big broken for your own custom styles.

* Minor bootstrap styling fix for non-editable fields


2.8.0 (2021-01-13)
~~~~~~~~~~~~~~~~~~

* Nested forms

* The paginator is now lazy. This means we can avoid a potentially expensive `.count()` database hit in many situations

* Added `Table.bulk_container`

* `Table.post_bulk_edit` takes evaluate parameters now

* Column.include=False implies that the column shouldn't get anything in the bulk form. If you want bulk editing without a visible column use Column.render_column=False

* Support auto__include=['pk']

* Fix reinvoke/reinvoke_new_defaults when shortcut is changed

* Date/datetime parsing bugs fixed after mutation testing

* Do not do form post_validation if we are in initial display mode

* Forms now don't create a submit button by default. If you have a post handler you will get a submit button though.

* SQL trace bugfixes

* Custom raw_data callback should have same semantics as constant value (and parsed_data callback)

* Improved error message on disallowed unbound object access

* Documentation improvements, for example new pages for dev tools, and styles

* Live editing on `.as_view()` style views work in the case of an explicitly declared class

* Fixed bug where the ajax enhanced table didn't work if you used `Table.div` or otherwise changed the `tag` of `Table`

* Fixed auto__model column/filter for `CharField` with choices


2.7.0 (2020-12-14)
~~~~~~~~~~~~~~~~~~

* A `Form` can now contain non-`Field` parts. Iterate over everything to render with `form.parts` and all the fields to be validated with `form.fields`. Fields that are not direct children are also collected, so you can easily add extra structure by wrapping a bunch of fields in a `html.div` for example.

* Support Django's `CharField.choices` feature

* You can now customize the name shown in the advanced search via `Filter.query_name`

* Form submit buttons (`Actions.submit`) are now rendered as `<button>` not as `<input type="submit">`.

* Added SQL trace feature

* You can now apply styles on the root object. Example: `root__assets__my_asset=Asset(...)`

* Edit button only present in debug menu when the edit middleware is installed

* Added profile button to debug menu

* Make collected assets more accessible when rendering iommi in your own templating environment: you can now access them on the iommi objects: `my_iommi_obj.iommi_collected_assets()`

* Removed broken validation of sort columns. This validation prevented sorting on annotations which was very confusing as it worked in debug mode

* Make it possible to target the live edit page with styles (via `LiveEditPage`)

* The live edit view can be flipped between horizontal and vertical layouts

* The debug tree view is slimmed down (by not including endpoints and assets on lots of things)

* `Field.raw_data_list` is removed. You can know if it's a list or not by checking `is_list`, so `raw_data` covers the uses cases.

* Include decorators in live edit

* The debug jump to code feature should work for some more scenarios, and it will not display if it has no good guess.

* DEPRECATED: `Field.choice_to_option`. This is replaced by `choice_id_formatter` and `choice_display_name_formatter`


2.6.1 (2020-12-01)
~~~~~~~~~~~~~~~~~~

* Fixed live editing to work when distributing iommi


2.6.0 (2020-12-01)
~~~~~~~~~~~~~~~~~~

* Live editing of function based views in DEBUG. Works for both iommi views and normal django views.

* Added ajax enhanced table filtering

* You can now turn off the advanced mode on queries: `Table(query__advanced__include=False)`

* `Query` has two new refinables: `filter` and `post_process`. These are hook points if you need to further customize what query is generated.

* Enable profiling when DEBUG mode is on, even if you're not staff

* Fixed multiselect on empty list

* Added missing `get_errors()` member function on `Field`

* Fixed select2 widget when the base url do not end with `/`

* Styling fixes. Primarily for bulma.


2.5.0 (2020-11-19)
~~~~~~~~~~~~~~~~~~

* include=False on a Column should imply not generating the query filter and bulk field. If you want to not render a column but still want the filters, use the render_column=False feature

* Added callbacks for saving a form: `extra__pre_save_all_but_related_fields`, `extra__on_save_all_but_related_fields`, `extra__pre_save`

* Added `extra__new_instance` callback to `Form.create` for custom object creation

* The errors list has been changed. You should always use `add_error()` to add an error on a `Field` or a `Form`

* It is now possible to call `is_valid()` and `get_errors()` and get what you expect from `post_validation` on `Field` and `Form`

* Query forms can now have additional fields, that are ignored by the filter handling code (when you want to do additional filtering outside of the query logic)

* Bug fixes with state leaking between binds

* Fixed jump to code

* Improved error message for `is_valid_filter`

* Added a nice error message if you try to shoot in `style` or `class` as raw strings

* Fixed empty table message, and invalid query form messages


2.4.0 (2020-11-04)
~~~~~~~~~~~~~~~~~~

* The given `rows` queryset and filtering were not respected for the "Select all rows" bulk feature. This could produce some pretty bad bugs!

* Support custom bulk post_handlers on lists and not just querysets

* `Table` has a few new members:
    - `initial_rows`: the rows you pass (or that gets created by `auto__model`) is stored unchanged here
    - `sorted_rows`: `initial_rows` + sorting applied
    - `sorted_and_filtered_rows`: `sorted_rows` + filtering applied
    - `visible_rows`: `sorted_and_filtered_rows` + pagination applied
    - `rows`: this is now a property and will map to the old behavior which is the "most applied" member that exists


* Fixed passing dunder paths to `auto__include`. You got a weird crash if the target of the path was a foreign key. There are still issues to be resolved adjacent to this, but the base case now works.

* Fixed the "select all" feature for pages with multiple tables.


2.3.0 (2020-10-30)
~~~~~~~~~~~~~~~~~~

* Every part can now have assets that are added to the assets of the style and included in the head. This is particularly useful for bundling small pieces of javascript or css with the components that need them and thereby gets us closer to being able to write truly self contained "component". As a proof of concept I did so for the tables javascript parts. The naming takes care of deduplication of assets.

* Only include select2 assets when needed (possible because of the point above)

* Filtering on booleans was very broken. It always returned empty querysets and didn't produce errors when you tried to do stuff like `my_boolean<3`

* It's now possible to configure stuff on the freetext field of a query

* iommi will now grab the root page title from the text from `Header` instances in addition to `Part.title`

* Render date fields as such

* Fixed date and time formatting

* Support for optgroups in forms

* Make it possible to insert fields into the form of a query, and filters into a query

* Differentiate between primary and other actions. This should make iommi pages look more in line with the majority of design systems. If you have a custom style you probably want to add a style definition for `Action.primary`.

* Fixed a case of a silent overwrite that could be surprising. This was found during reading the code and has never happened to us in practice.

* Style fixes for bulma


2.2.0 (2020-10-16)
~~~~~~~~~~~~~~~~~~

* Fix so that style application does not alter definitions destructively. This could lead to some strange behavior if you tried to switch between styles, and it could leak over definitions between things you would not expect.

* The title of `Table` is `None` when there is no model

* Assets as first class concept. You can now insert asset definitions into your style with `assets__js=...` instead of defining a `base_template`. This change also removes the base templates for all the built in styles as they are now obsolete.

* Made it easy to hide the label of a Field by setting `display_name=None`, or `include=False`


2.1.0 (2020-10-07)
~~~~~~~~~~~~~~~~~~

* Internationalization! iommi now has i18n support and ships with English, German and Swedish languages out of the box. We welcome more translations.

* Out of the box support for the Bulma CSS framework

* Make `auto__include` specifications allow foreign key paths

* By default we now grab display_name from the model fields verbose_name (if applicable)

* Sometimes you got reordering of parts when doing a post to a form for example, this is now fixed

* The `traversable` argument to lambdas is now the leaf and not the root. This was a bug.

* Support `reverse_lazy` as url argument to MenuItem

* Two id attributes were rendered on the input tags in forms (thanks Benedikt Grundmann for reporting!)


2.0.1 (2020-09-22)
~~~~~~~~~~~~~~~~~~

* `delete_object__post_handler` accessed `instance.id` which might be valid. It should have accessed `instance.pk` which is always valid.


2.0.0 (2020-09-22)
~~~~~~~~~~~~~~~~~~

* BACKWARDS INCOMPATIBLE: `Style` must now take a `base_template` argument. This replaces the setting `IOMMI_BASE_TEMPLATE`.

* BACKWARDS INCOMPATIBLE: `IOMMI_CONTENT_BLOCK` is removed. Replaced by the `content_block` setting for `Style`.

* Allow table rows to be provided from a generator. (Disabling paginator)

* Added blocks (`iommi_head_contents`, `iommi_top`, and `iommi_bottom`) as useful hook points to add custom data in the templates if you don't need a totally new template but want to just customize a little bit.

* The default sort_key on a Column.foreign_key now looks at the searchable field of the remote field ('name' by default). This means by default sorting will mostly be more what you expect.

* Changed the error from get_search_field() for non-unique name to a warning.

* Removed <table> for layout in query advanced/simple stuff.

* Don't warn for missing register_search_fields when attr=None

* Set admin to bootstrap by default.

* Added form for changing password. Used by the admin but also usable from your code.

* Added form for login. Used by the admin but also usable from your code.

* Fixed foundation styling for query form.

* Introduced `Field.help`. This is the fragment that renders the help text for a `Field`. This means you can now style and customize this part of forms more easily. For example set a CSS class: `Field(help__attrs__class__foo='foo'`.

* Use django default date and time formatting in tables.

* New shortcut for `Table`: `Table.div` for when you want to render a `Table` as a bunch of divs. This is useful because a `Table` is really a view model of a sequence of stuff, not just a `<table>`.

* Possibility to set `Actions.tag` to `None` to not get a wrapping html tag.

* Added `Table.outer` as a tag you can style that encompasses the entire table part.

* Moved `Form.h_tag` rendering inside the form tag to make it stylable as a coherent whole.

* Grab html title from first part if no title is given explicitly. This means you'll get the `<title>` tag filled more often by what you expect automatically.

* `Template` instances are now collected properly by `Part`.

* Read admin config from modules.

* The Admin is now opt in, not opt out.

* The admin is now MUCH prettier and better.

* Actions for `Table` are now rendered above the table by default. Set `actions_below` to `True` to render them the old way.

* Many misc improvements


1.0.3 (2020-08-24)
~~~~~~~~~~~~~~~~~~

* Changed `Table.bulk_form` to `Table.bulk`. The old name was a mistake as the name was always `bulk`. This meant that styling didn't work like you expected and the pick feature also lead you down the wrong path.


1.0.2 (2020-08-21)
~~~~~~~~~~~~~~~~~~

* Support user inputted relative dates/datetimes

* Support more time formats automatically

* Introduced Filter.parse() which is a hook point for handling special parsing in the query language. The query language will no longer try to convert to integers, floats and dates for you. You have to specify a parse() method.

* Added `traversable` key to evaluate parameters. Think of it like something similar to `self`.

* `cell__format` now gets all evaluate parameters like you'd expect

* Filters: If `attr` is `None` but you've specified `value_to_q` then your filter is now included

* Various bug fixes


1.0.1 (2020-06-24)
~~~~~~~~~~~~~~~~~~

* Optimizations

* Use select2 as the default for multi_choice

* Improved usability: Make icon column behavior on falsy values more guessable

* Accidentally changed default style to foundation, change back to bootstrap

* Improved usability: Don't fall back to default template name if the user specified an explicit template name: fail on TemplateNotFound

* Style on root uses correct base template

* Allow model fields called `context`


1.0.0 (2020-06-10)
~~~~~~~~~~~~~~~~~~

* Backwards incompatible: `register_search_fields` replaces `register_name_field`. This new system is a list of field names and not just a single field. There is also new searching and filtering behavior based on this that means you will get better search results

* Backwards incompatible: `field_name` as used by model factories is replaced with `model_field_name`. If you used `register_factory` you will need to change this. The field names on `Column`, `Field` and `Filter` are also renamed.

* Support fields named `keys`, `value` or `items` on Django models

* Added basic styling support for CSS frameworks Water and Foundation

* Fix include to make None mean False

* Change Filter.text to search using icontains instead of iexact by default in the basic search mode

* Change post_validation callback to receive standard evaluate parameters

* Improved help text for queries

* Field.radio was broken in the bootstrap style: it specified the input template as the template for the entire field, so the label got erased


0.7.0 (2020-05-22)
~~~~~~~~~~~~~~~~~~

* Fixed default text argument to Fragment

* Fixed issue where endpoint dispatch parameter was left over in the pagination and sorting links

* Parts that are None should not be collected. This affected the admin where it printed "None" below the "Admin" link.

* Added header for bulk edit form in tables

* Fixed textarea readonly when field is not editable

* Fixed is_paginated function on Paginator

* Add request to evaluate parameters

* Make evaluate and evaluate_recursive match even the `**_` case by default

* No dispatch command on a POST is invalid and will now produce an error

* Lazy bind() on members. This is a performance fix.

* Fixed bug where display_name could not be overridden with a lambda due to incorrect evaluate handling

* Removed Table.rendered_columns container. You have to look at the columns and check if they have render_column=False


0.6.2 (2020-04-22)
~~~~~~~~~~~~~~~~~~

* Fixed data-endpoint attribute on table


0.6.1 (2020-04-21)
~~~~~~~~~~~~~~~~~~

* Fixed tbody endpoint and added a div to make the endpoint easier to use


0.6.0 (2020-04-17)
~~~~~~~~~~~~~~~~~~

* Fixed an issue where fragments couldn't be customized later if built with the `html` builder

* `Action` inherits from `Fragment`. This should be mostly transparent.

* You can now pass multiple argument to `Fragment`/`html.foo()`. So `html.div('foo', 'bar')` is now valid and creates two child nodes `child0` and `child1`

* Uncouple `auto__*` from `row` parameter. `auto__` only suggests a default. This avoids some confusion one could get if mixing `auto__rows`, `auto__models` and `rows` in some ways.

* Fixed setting active on nested submenus where the parent had url None


0.5.0 (2020-04-01)
~~~~~~~~~~~~~~~~~~

* Include iommi/base_bootstrap.html and iommi/base_semantic_ui.html in package, and use them if no base.html is present. This improves the out of the box experience for new projects a lot

* Support mixing of `auto__model`/`auto__row` based columns and declarative columns

* Support attrs__class and attrs__style as callables

* Added support for context namespace on Page, which is passed to the template when rendering (for now only available on the root page)

* Fixed how we set title of bulk edit and delete buttons to make configuration more obvious


0.4.0 (2020-03-30)
~~~~~~~~~~~~~~~~~~

* Fixed rendering of grouped actions for bootstrap

* Respect auto__include order

* boolean_tristate should be the default for the Field of a Column.boolean

* New class Header that is used to automatically get h1/h2/etc tags according to nesting of headers

* Table.rows should be able to be evaluated

* Added feature that you can type 'now' into date/datetime/time fields

* Feature to be able to force rendering of paginator for single page tables

* Paginator fixes: it's now no longer possible to use the Django paginator, but the iommi paginator is more full features in trade.

* Removed jQuery dependency for JS parts

* Big improvements to the Menu component

* filters that have freetext mode now hide their field by default

* Added "pick" in the debug toolbar. This is a feature to quickly find the part of the document you want to configure

* Introduced Form.choice_queryset.extra.create_q_from_value

* Changed so that Query defaults to having the Field included by default

* Renamed BoundRow/bound_row to Cells/cells

* Major improvements to the admin

* Lots and lots of cleanup and bug fixes

    :start-line: 2


=======
Credits
=======

* Johan Lübcke <johan@lubcke.se>
* Anders Hovmöller <boxed@killingar.net>
* Maren Leithe
* Fredrik Westermark <fredrik.westermark@trioptima.com>
* Tore Lundqvist <tore.lundqvist@trioptima.com>
* Gabriel Lima
* Johan Hägg
* Esse Woods <esbjorn.ekberg@trioptima.com>
* Lars-Erik Hannelius <larserik.hannelius@trioptima.com>
* Stefan Chyssler <stefan.chyssler@trioptima.com>
* Simon Percivall
* Simon Lundmark Ornstein <simon.ornstein@trioptima.com>
* Erik Sjöstedt
* Daniel Vinntreus
* Ludvig Boström <ludvig.bostrom@trioptima.com>
* Andreas Rasmusson <andreas.rasmusson@trioptima.com>
* Martin Barksten <martin.barksten@trioptima.com>
* Rasmus Spiegelberg <rasmus.spiegelberg@trioptima.com>
* Benedikt Grundmann <benedikt.grundmann@gmail.com>
* flying_sausages
* Nigel Metheringham <nigel.metheringham@gmail.com>
* Maximilian Albert <https://github.com/maxalbert>
* Yury Bulka <setthemfree@privacyrequired.com>
* Mickey McClellan <77741738+MickeyM79@users.noreply.github.com>
* Oana Fatu <oana.fatu@trioptima.com>
* Viktor <dpedesigns@hotmail.com>
* Bery <info@berycz.net>
* Sytrus Ivkus <aiueclipse@mail.com>
* Braintelligence <Braintelligence@users.noreply.github.com>
* David D Wang <duendwang@users.noreply.github.com>
* MareksNo <ulmanismareks@gmail.com>
* Milton Johansson <milton.johansson@trioptima.com>
* astrocbxy <chrisbehrmann00@gmail.com>
* yanhuixie <yanhuixie@gmail.com>
* Sam Mangham <mangham@gmail.com>
* Pierre de Lépinay <pierre@lepinay.org>



============
Contributing
============

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given. 

Issues, feature requests, etc are handled on github.




iommi
=====
.. raw:: html

    <p class="mobile-logo" align="center"><a href="#"><img class="logo" src="https://raw.githubusercontent.com/iommirocks/iommi/master/logo_with_outline.svg" alt="iommi" style="max-width: 200px" width=300></a></p>

    <h3 class="pun">Your first pick for a django power chord</h3>

.. image:: https://img.shields.io/badge/Code_on-GitHub-black
    :target: https://github.com/iommirocks/iommi

.. image:: https://img.shields.io/discord/773470009795018763?logo=discord&logoColor=fff?label=Discord&color=7389d8
    :target: https://discord.gg/ZyYRYhf7Pd

.. image:: https://github.com/iommirocks/iommi/workflows/tests/badge.svg
    :target: https://github.com/iommirocks/iommi/actions?query=workflow%3Atests+branch%3Amaster

.. image:: https://codecov.io/gh/iommirocks/iommi/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/iommirocks/iommi

.. image:: https://readthedocs.org/projects/iommi/badge/?version=latest
    :target: https://docs.iommi.rocks
    :alt: Documentation Status

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

iommi is a toolkit to build web apps faster. It's built on Django but goes a lot further.

It has:

- :doc:`forms <forms>`: that feel familiar, but can handle growing complexity better than Django's forms
- :doc:`tables <tables>`: that are powerful out of the box and scale up to arbitrary complexity
- a system to :doc:`compose parts <pages>`:, like forms, menus, and tables, into bigger pages
- tools that will speed up your development like live edit, jump to code, great feedback for missing select/prefetch related, a profiler, and more.
- great error messages when you make a mistake

.. image:: https://docs.iommi.rocks/README-demo.gif


Example:

.. code-block:: python

    class IndexPage(Page):
        title = html.h1('Supernaut')
        welcome_text = 'This is a discography of the best acts in music!'

        artists = Table(auto__model=Artist, page_size=5)
        albums = Table(
            auto__model=Album,
            page_size=5,
        )
        tracks = Table(auto__model=Album, page_size=5)


    urlpatterns = [
        path('', IndexPage().as_view()),
    ]

This creates a page with three separate tables, a header and some text:

.. image:: https://docs.iommi.rocks/README-screenshot.png

For more examples, see the `examples project <https://github.com/iommirocks/iommi/tree/master/examples/examples>`_.


Getting started
---------------

See :doc:`getting started <getting_started>`.


Running tests
-------------

.. code-block::

    make test
    make test-docs


License
-------

BSD