Semantic support for FK+M2M registration

Author: boxed

docs/test_doc_semantic_models.py

@@ -1,15 +1,20 @@
 from django.db.models import (
+    BooleanField,
     CASCADE,
     CharField,
     ForeignKey,
+    ManyToManyField,
     Model,
 )
 
+import iommi
 from iommi import (
     register_factory,
-    Style,
+    register_related_factory,
+    register_related_multiple_factory,
 )
-from iommi.style_bootstrap5 import bootstrap5
+from iommi.shortcut import with_defaults
+from tests.helpers import req
 
 
 def test_semantic_models():
@@ -26,76 +31,135 @@ def test_semantic_models():
     """
 
     # @test
-    class Location(Model):
+    class Role(Model):
         pass
-
     # @end
 
     class User(Model):
+        is_active = BooleanField()
         name = CharField()
         person_number = CharField()
-        birth_place = ForeignKey(Location, on_delete=CASCADE)
         manager = ForeignKey('self', on_delete=CASCADE)
+        roles = ManyToManyField(Role, blank=True)
 
-    # language=rst
-    """
-    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:
-
-    """
-
-    class PersonNumberField(CharField):
-        pass
-
-    # language=rst
-    """
-    This field can then be registered in iommi:
-
-    """
-    register_factory(PersonNumberField, shortcut_name='person_number')
-
-    # language=rst
-    """
-    For foreign key fields it would be cumbersome to make custom classes, so registrations are done slightly differently:
-
-    """
-
-    register_foreign_key_factory(Location, shortcut_name='location')
-    register_foreign_key_factory(User, shortcut_name='user')
-
-    # language=rst
-    """
-    You will then need to add shortcuts for these in your subclasses of `Column`, `Field`, and `Filter`. These can start out empty, and configuration can be done in the style definition:
-
-    """
+    # @test
+    try:
+        # @end
+
+        # language=rst
+        """
+        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:
+    
+        """
+
+        class PersonNumberField(CharField):
+            pass
+
+        # language=rst
+        """
+        This field can then be registered in iommi:
+
+        """
+        register_factory(PersonNumberField, shortcut_name='person_number')
+
+        # language=rst
+        """
+        Then change the model to use `PersonNumberField`:
+        """
+
+        class User(Model):
+            is_active = BooleanField()
+            name = CharField()
+            person_number = PersonNumberField()
+            manager = ForeignKey('self', on_delete=CASCADE)
+
+        # @test
+        # Fix Django model registry issue: redefining a model class causes ForeignKey('self')
+        # to resolve to the old class, so we manually fix the reference.
+        User._meta.get_field('manager').remote_field.model = User
+        # @end
+
+        # language=rst
+        """
+        For foreign key, and many-to-many fields it would be cumbersome to make custom classes, so registrations are done slightly differently:
+
+
+        """
+
+        # 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')
+
+        # @test
+        person_number__parse = lambda **_: None
+        # @end
+
+        # language=rst
+        """
+        You will then need to add shortcuts for these in your subclasses of `Column`, `Field`, and `Filter`.
+        """
+
+        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)
+
+        # language=rst
+        """
+        ...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.
+        """
+
+        # @test
+        class Form(iommi.Form):
+            class Meta:
+                member_class = Field
+
+        f = Form.create(auto__model=User).bind(request=req('get'))
+        assert str(f.fields.manager.choices.query) == str(User.objects.filter(is_active=True).query)
+        # @end
 
     # @test
-    person_number__parse = lambda **_: None
+    finally:
+        from iommi.form import (
+            _related_field_factory_by_model,
+            _related_multiple_field_factory_by_model,
+        )
+        _related_field_factory_by_model.pop(User)
+
+        _related_multiple_field_factory_by_model.pop(Role)
     # @end
-
-    your_style = Style(
-        bootstrap5,
-        Field=dict(
-            shortcuts=dict(
-                person_number__parse=person_number__parse,
-            ),
-        ),
-    )
-
-    # language=rst
-    """
-    It 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 set up.
-    """

examples/examples/apps.py

@@ -1,5 +1,6 @@
 from django.apps import AppConfig
 
+from iommi import register_related_factory
 from iommi.path import register_path_decoding
 
 
@@ -19,3 +20,4 @@ def ready(self):
         register_search_fields(model=Album, search_fields=['name'], allow_non_unique=True)
         register_path_decoding(artist_pk=Artist)
         register_path_decoding(album_pk=Album)
+        register_related_factory(Artist, shortcut_name='artist')

examples/examples/iommi.py

@@ -0,0 +1,79 @@
+from django.template import Template
+
+import iommi
+from iommi.shortcut import with_defaults
+
+
+class Page(iommi.Page):
+    pass
+
+
+class Action(iommi.Action):
+    pass
+
+
+class Field(iommi.Field):
+    @classmethod
+    @with_defaults()
+    def artist(cls, **kwargs):
+        return cls.foreign_key(**kwargs)
+
+
+class Form(iommi.Form):
+    class Meta:
+        member_class = Field
+        page_class = Page
+        action_class = Action
+
+
+class Filter(iommi.Filter):
+    @classmethod
+    @with_defaults()
+    def artist(cls, **kwargs):
+        return cls.foreign_key(**kwargs)
+
+
+class Query(iommi.Query):
+    class Meta:
+        member_class = Filter
+        form_class = Form
+
+
+class Column(iommi.Column):
+    @classmethod
+    @with_defaults()
+    def artist(cls, **kwargs):
+        return cls.foreign_key(**kwargs)
+
+
+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):
+    @classmethod
+    @with_defaults()
+    def artist(cls, **kwargs):
+        return cls.foreign_key(**kwargs)
+
+
+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

examples/examples/main_menu.py

@@ -1,22 +1,21 @@
+from examples import (
+    playground,
+    storybook,
+    supernaut,
+)
+from examples.iommi import Form
 from examples.models import (
     Album,
     Artist,
     Track,
 )
-from iommi import Form
 from iommi.admin import Admin
-from iommi.main_menu import (
+from iommi.experimental.main_menu import (
     EXTERNAL,
     M,
     MainMenu,
 )
 
-from examples import (
-    playground,
-    storybook,
-    supernaut,
-)
-
 main_menu = MainMenu(
     items=dict(
         albums=M(

examples/examples/supernaut.py

@@ -4,18 +4,15 @@
 )
 from django.utils.translation import gettext_lazy as _
 
-from iommi import (
+from examples.iommi import (
     Action,
     Column,
     Form,
-    Menu,
-    MenuItem,
     Page,
     Table,
-    html,
 )
+from iommi import html
 from iommi.path import register_path_decoding
-
 from .models import (
     Album,
     Artist,
@@ -103,7 +100,7 @@ class ArtistPage(Page):
     title = html.h1(lambda params, **_: params.artist.name)
 
     albums = AlbumTable(auto__model=Album, rows=lambda params, **_: Album.objects.filter(artist=params.artist))
-    tracks = TrackTable(auto__model=Track, rows=lambda params, **_: Track.objects.filter(album__artist=params.artist))
+    # tracks = TrackTable(auto__model=Track, rows=lambda params, **_: Track.objects.filter(album__artist=params.artist))
 
 
 class AlbumPage(Page):

examples/examples/templates/base.html

@@ -0,0 +1,13 @@
+{% extends "iommi/base.html" %}
+
+{% block iommi_head_contents_last %}
+    {% if request.iommi_example_source_css %}
+        <style>{{ request.iommi_example_source_css }}</style>
+    {% endif %}
+{% endblock %}
+
+{% block iommi_top %}
+    {% if request.iommi_example_source %}
+        {{ request.iommi_example_source }}
+    {% endif %}
+{% endblock %}