django-glue-forms

name: django-glue-forms description: Django Glue Alpine.js integration for reactive Django forms

Django Glue Forms

Overview

Django Glue Forms provides seamless Alpine.js integration for Django forms, enabling reactive, two-way data binding between server-side Django forms and client-side JavaScript. It bridges the gap between Django's server-side validation and Alpine.js's reactive UI capabilities.

Key Features

• ModelObjectGlue: Bind Django model instances or form data to Alpine.js reactive objects
• Automatic Field Generation: Model fields auto-converted to Alpine.js compatible formats
• Session Management: Persistent state across requests with keep-alive functionality
• Permission Control: View, change, and delete access levels
• Form Field Templates: 20+ pre-built field templates for common Django field types

Core Concepts

Two Form Approaches

1. ModelObjectGlue - When your form is backed by a model
2. Frontend Field Initialization - Collecting data that is not related to a Django Model

Note: Both approaches can be used together in the same form.

Access Levels

from django_glue.access.access import Access

# Permission hierarchy (lowest to highest)
Access.VIEW    # Read-only access
Access.CHANGE  # Read and modify access
Access.DELETE  # Full access including delete

Session Storage

All glue objects are stored in Django session with:

• Unique encoded key (includes request path for isolation)
• Automatic cleanup via middleware
• Keep-alive mechanism to prevent expiration during active use

Field Templates Available

Located in django_glue/templates/django_glue/form/field/:

All field templates extend base_field.html which handles:

• Field initialization from session
• Attribute binding (required, disabled, etc.)
• Error display
• Help text tooltips

How It Works

1. Server Initialization

dg.glue_model_object(request, 'company', company_instance, 'change')

What happens:

1. Creates ModelObjectGlue object with model metadata
2. Serializes field definitions (name, type, label, choices, validation rules)
3. Stores in Django session under encoded unique name
4. Sets "keep-alive" flag to maintain session

2. Client Initialization

company: new ModelObjectGlue('company')

What happens:

1. Alpine.js component loads
2. init() calls this.company.get()
3. Makes AJAX request to fetch field data from session
4. Populates reactive object with field definitions and values
5. Fields become available for binding

3. Field Binding

{% include 'django_glue/form/field/char_field.html' with glue_model_field='company.name' %}

What happens:

1. Base template (base_field.html) sets up Alpine.js data binding
2. x-model="value" binds to company.name.value
3. Field attributes (required, disabled, etc.) are applied dynamically
4. Validation errors display automatically
5. Changes sync between Alpine.js and session

4. Form Submission

<form method="post">

What happens:

1. Standard Django form submission
2. Alpine.js values sent as POST data
3. Django form validates against cleaned_data
4. Server-side validation errors displayed via show_form_errors()
5. On success, redirect or update model

Real-World Examples

Your Codebase: Company Form (ModelForm)

View (app/company/views/form_views.py):

def _form_view(request: WSGIRequest, pk: int):
    company = get_object_or_null_obj(models.Company, pk=pk)
    
    dg.glue_model_object(request, 'company', company, 'view')
    
    if request.method == 'POST':
        form = forms.CompanyForm(request.POST, instance=company)
        
        if form.is_valid():
            company, _ = company.services.save_model_obj(**form.cleaned_data)
            add_form_activity(company, pk, request.user)
            return redirect(return_url)
        
        show_form_errors(request, form)
    else:
        form = forms.CompanyForm(instance=company)
    
    return portal_views.form_view(
        request,
        form=form,
        obj=company,
        template='company/page/form_page.html',
    )

Template (templates/company/form/form.html):

<form method="post" x-data="{
    async init() {
        await this.company.get()
    },
    company: new ModelObjectGlue('company')
}">
    {% csrf_token %}
    
    {% include 'django_glue/form/field/char_field.html' with glue_model_field='company.name' %}
    {% include 'django_glue/form/field/text_field.html' with glue_model_field='company.description' %}
    
    {% include 'django_spire/contrib/form/button/form_submit_button.html' %}
</form>

Frontend Field Initialization

There are two ways to bind form fields with Django Glue:

1. ModelObjectGlue - Bind entire model objects (all fields at once)
2. Manual Field Initialization - Initialize individual fields directly in Alpine.js

Both approaches use the same field templates. The difference is how you initialize the data in x-data.

Available Glue Field Types

Common Field Properties

All Glue fields support these properties:

Manual Field Initialization

Initialize any field type directly in Alpine.js x-data:

<form method="post" x-data="{
    async init() {
        // Set initial value
        this.partner_field.value = {{ partner.pk|default_if_none:'null' }}
        
        // Load choices dynamically
        this.partner_field.choices = await this.partners.to_choices()
        
        // Modify field properties
        this.partner_field.label = 'Partner'
        this.partner_field.required = true
        
        // Watch for changes
        this.$watch('partner_field.value', async () => {
            this.agreement_field.choices = await this.get_agreements.call({
                'partner_id': this.partner_field.value
            })
        })
    },
    
    // Initialize standalone fields
    partner_field: new GlueCharField('partner'),
    agreement_field: new GlueCharField('agreement'),
    
    // Supporting objects
    partners: new QuerySetGlue('partners'),
    get_agreements: new FunctionGlue('get_agreements'),
}">
    {% csrf_token %}
    
    <!-- Use glue_field parameter for standalone fields -->
    {% include 'django_glue/form/field/search_and_select_field.html' with glue_field='partner_field' %}
    {% include 'django_glue/form/field/search_and_select_field.html' with glue_field='agreement_field' %}
    
    <button class="btn btn-app-primary">Submit</button>
</form>

Mixing Both Approaches

You can use ModelObjectGlue and standalone fields in the same form:

<form method="post" x-data="{
    async init() {
        // Load model object
        await this.scope_of_work.get()
        
        // Initialize standalone fields
        this.partner_field.choices = await this.partners.to_choices()
    },
    
    // Model-backed fields
    scope_of_work: new ModelObjectGlue('scope_of_work'),
    
    // Standalone fields
    partner_field: new GlueCharField('partner'),
    
    // Supporting objects
    partners: new QuerySetGlue('partners'),
}">
    {% csrf_token %}
    
    <!-- Model field (uses glue_model_field) -->
    {% include 'django_glue/form/field/char_field.html' with glue_model_field='scope_of_work.name' %}
    
    <!-- Standalone field (uses glue_field) -->
    {% include 'django_glue/form/field/search_and_select_field.html' with glue_field='partner_field' %}
    
    <button class="btn btn-app-primary">Submit</button>
</form>

Key Points:

• Model fields use glue_model_field='object.field'
• Standalone fields use glue_field='field_name'
• Both use the same field templates
• Initialize standalone fields in x-data with new Glue*Field('name')

Advanced Features

Field Inclusion/Exclusion

# Only include specific fields
dg.glue_model_object(request, 'obj', instance, fields=('name', 'email'))

# Exclude specific fields
dg.glue_model_object(request, 'obj', instance, exclude=('password', 'secret'))

# Include all except some
dg.glue_model_object(request, 'obj', instance, 
                     fields=('__all__',), 
                     exclude=('internal_notes',))

Exposing Model Methods

def my_view(request):
    obj = MyModel.objects.get(pk=1)
    dg.glue_model_object(request, 'obj', obj, methods=('get_full_name',))

# In template
<div x-text="company.get_full_name()"></div>

Exclude Sensitive Fields

Always exclude sensitive data:

dg.glue_model_object(
    request,
    'user',
    user_instance,
    exclude=('password', 'secret_key', 'internal_notes')
)

Code Review Checklist

When reviewing Django Glue Forms code, verify the following:

1. Glue Initialization: All views using Glue call dg.glue_model_object() before rendering
2. Name Consistency: The unique_name parameter matches between server and client code
3. Async Initialization: Alpine.js components use async init() with .get() call
4. CSRF Token: All forms include {% csrf_token %}
5. Field Parameter: Using glue_model_field for all ModelObjectGlue fields
6. Access Level: Appropriate access level ('view', 'change', 'delete') is set
7. Sensitive Fields: Password and secret fields are excluded from glue objects
8. Field Templates: Appropriate field template is used for each field type
9. Empty Instance for New Objects: Regular forms initialize Glue with empty model instance