Equivalence

In iommi there are multiple ways to accomplish the same thing. The two most obvious ways are declarative and programmatic. But there are different paths even within those two main paths. This page is an overview of a few of those ways. Hopefully you will see the philosophy through these examples. Let’s get started!

First a model:

class Album(Model):
    name = CharField(max_length=255, db_index=True)
    artist = ForeignKey(Artist, on_delete=CASCADE, related_name='albums')
    year = IntegerField(default=1980)

    genres = ManyToManyField(Genre, related_name='albums')

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):

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

▼ Hide result

form = Form.create(
    auto=dict(
        model=Album,
        exclude=['artist'],
    ),
)

► Show result

form = Form.create(
    auto__model=Album,
    fields__artist__include=False,
)

► Show result

class AlbumForm(Form):
    class Meta:
        auto__model = Album
        auto__exclude = ['artist']

form = AlbumForm.create()

► Show result

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

form = AlbumForm.create()

► Show result

class AlbumForm(Form):
    class Meta:
        auto__model = Album
        fields__artist__include = False

form = AlbumForm.create()

► Show result

Without using the auto features:

class AlbumForm(Form):
    name = Field()
    year = Field.integer()

    class Meta:
        title = 'Create album'
        actions__submit__post_handler = create_album

form = AlbumForm()

► Show result

form = Form(
    fields__name=Field(),
    fields__year=Field.integer(),
    title='Create album',
    actions__submit__post_handler=create_album,
)

► Show result

You can read more about this in the philosophy section under Declarative/programmatic hybrid API.