Nhom

Notes

Here’s an explanation of the forms in your classified_ads app:

1. ClassifiedAdForm

• Model form for creating/editing classified ads.
• Includes fields for English/Vietnamese title and description, category, ad type, contact info, location, price, translation status, and translator.
• Uses crispy-forms for layout and styling.
• Pre-fills contact info if the user is logged in.

2. AdImageForm & AdImageFormSet

• Model form for uploading ad images (image, caption, is_primary).
• Formset allows multiple images per ad (up to 10).

3. AdSearchForm

• Regular form for searching/filtering ads.
• Fields: query, category, ad type, location, popular location, price range, sort order.
• Uses crispy-forms for a multi-row search bar layout.

4. AdInquiryForm

• Model form for sending inquiries to ad owners.
• Fields: name, email, phone, message.
• Pre-fills name and email if the user is logged in.
• Uses crispy-forms for layout.

5. CategoryForm

• Model form for creating/editing categories.
• Fields: name, description, parent, icon, slug, is_active.
• Uses crispy-forms for layout.

All forms are styled for Bootstrap and provide user-friendly input, validation, and layout for managing classified ads, images, categories, and inquiries.

1. ClassifiedAdForm - Main Ad Creation/Editing Form

Purpose & Scope

This is the core form for creating and editing classified advertisements with full multilingual support (English/Vietnamese) and translation management.

Model Fields Included

fields = [

    'title', 'title_vi', 'description', 'description_vi',  # Multilingual content

    'category', 'ad_type',                                 # Classification

    'contact_name', 'contact_email', 'contact_phone', 'location',  # Contact info

    'price', 'price_negotiable', 'expires_at',            # Pricing & timing

    'translation_status', 'translated_by'                 # Translation management

]

Key Features:

A. Multilingual Support

'title': forms.TextInput(attrs={'placeholder': 'Enter a descriptive title in English'}),

'title_vi': forms.TextInput(attrs={'placeholder': 'Enter Vietnamese title (Tiêu đề tiếng Việt)'}),

• Parallel Fields: English and Vietnamese versions for title and description
• Optional Translation: Vietnamese fields can be left blank initially
• Rich Text Support: Uses CKEditor for formatted descriptions

B. Translation Management System

'translation_status': forms.Select(attrs={'class': 'form-control'}),

'translated_by': forms.TextInput(attrs={'placeholder': 'Translator name'}),

• Status Tracking: 'pending', 'translated', 'reviewed'
• Attribution: Records who performed the translation
• Workflow Integration: Connects with view logic for automatic status updates

C. User Experience Enhancements

def __init__(self, *args, **kwargs):

    user = kwargs.pop('user', None)

    # Pre-populate contact info with user data

    if user and user.is_authenticated:

        if not self.instance.pk:  # Only for new ads

            self.fields['contact_name'].initial = f"{user.first_name} {user.last_name}".strip() or user.username

            self.fields['contact_email'].initial = user.email

• Auto-Population: Contact fields pre-filled from user profile
• Smart Defaults: Intelligent field initialization
• Help Text: Contextual guidance for translation fields

D. Advanced Layout with Crispy Forms

self.helper.layout = Layout(

    Row(Column('title', css_class='col-12')),

    Row(

        Column('category', css_class='col-md-6'),

        Column('ad_type', css_class='col-md-6'),

    ),

    HTML('<h5 class="mt-4 mb-3">Contact Information</h5>'),

    # ... more sections

    FormActions(

        Submit('save_draft', 'Save as Draft', css_class='btn btn-secondary'),

        Submit('publish', 'Publish Ad', css_class='btn btn-primary'),

    )

)

• Sectioned Layout: Logical grouping with visual separators
• Responsive Grid: Bootstrap columns for mobile-first design
• Dual Submission: Draft vs. Publish workflow
• Visual Hierarchy: HTML sections for better organization

E. Input Validation & Formatting

'price': forms.NumberInput(attrs={'class': 'form-control', 'step': '0.01'}),

'expires_at': forms.DateTimeInput(attrs={'type': 'datetime-local'}),

'price_negotiable': forms.CheckboxInput(attrs={'class': 'form-check-input'}),

• Precision Control: Decimal step for accurate pricing
• Modern Inputs: HTML5 datetime-local picker
• Bootstrap Integration: Consistent styling across all fields

2. AdImageForm & AdImageFormSet - Image Management

Image Upload System

class AdImageForm(forms.ModelForm):

    class Meta:

        model = AdImage

        fields = ['image', 'caption', 'is_primary']

        widgets = {

            'image': forms.FileInput(attrs={'accept': 'image/*'}),

            'caption': forms.TextInput(attrs={'placeholder': 'Optional caption'}),

        }

AdImageFormSet = forms.inlineformset_factory(

    ClassifiedAd, AdImage, form=AdImageForm,

    extra=3, max_num=10, can_delete=True

)

Advanced Features:

• Multiple Images: Up to 10 images per ad
• Primary Image Selection: Designate main thumbnail
• Captions: Optional descriptions for each image
• File Type Restriction: Only image files accepted
• Dynamic Addition: Extra forms for new images
• Deletion Support: Remove existing images during editing

Usage in Views:

# In AdCreateView and AdUpdateView

formset = AdImageFormSet(self.request.POST, self.request.FILES, instance=self.object)

if formset.is_valid():

    formset.save()

3. AdSearchForm - Advanced Search Interface

Comprehensive Search Capabilities

class AdSearchForm(forms.Form):

    q = forms.CharField(required=False)  # Text search

    category = forms.ModelChoiceField(queryset=Category.objects.filter(is_active=True))

    ad_type = forms.ChoiceField(choices=[('', 'All Types')] + list(AdType.choices))

    location = forms.CharField(required=False)

    popular_location = forms.ModelChoiceField(queryset=Location.objects.filter(is_popular=True))

    price_min = forms.DecimalField(required=False, min_value=0)

    price_max = forms.DecimalField(required=False, min_value=0)

    sort_by = forms.ChoiceField(choices=[...], initial='newest')

Smart Search Features:

A. Dual Location Input

location = forms.CharField(

    widget=forms.TextInput(attrs={'list': 'popular-locations'})

)

popular_location = forms.ModelChoiceField(

    queryset=Location.objects.filter(is_popular=True),

    help_text="Quick select from popular locations"

)

• Text Input: Free-form location entry with autocomplete
• Dropdown: Quick selection from popular locations
• Priority Logic: Dropdown overrides text input in views

B. Price Range Filtering

price_min = forms.DecimalField(

    widget=forms.NumberInput(attrs={'step': '0.01', 'placeholder': 'Min price'})

)

price_max = forms.DecimalField(

    widget=forms.NumberInput(attrs={'step': '0.01', 'placeholder': 'Max price'})

)

• Flexible Ranges: Either min, max, or both
• Decimal Precision: Accurate price filtering
• User-Friendly: Clear placeholders

C. Advanced Layout & User Experience

self.helper.layout = Layout(

    Row(

        Column('q', css_class='col-md-3'),

        Column('category', css_class='col-md-2'),

        Column('ad_type', css_class='col-md-2'),

        Column('location', css_class='col-md-3'),

        Column('popular_location', css_class='col-md-2'),

    ),

    Row(

        Column('price_min', css_class='col-md-2'),

        Column('price_max', css_class='col-md-2'),

        Column('sort_by', css_class='col-md-3'),

        Column(Submit('search', 'Search'), css_class='col-md-2'),

        Column(HTML('<a href="?" class="btn btn-outline-secondary">Clear</a>'), css_class='col-md-3'),

    )

)

• Compact Layout: Efficient use of horizontal space
• Clear Action: Dedicated clear button for resetting filters
• GET Method: Preserves search state in URL for bookmarking

4. AdInquiryForm - Contact Communication

Structured Communication System

class AdInquiryForm(forms.ModelForm):

    class Meta:

        model = AdInquiry

        fields = ['name', 'email', 'phone', 'message']

        widgets = {

            'message': forms.Textarea(attrs={

                'rows': 4,

                'placeholder': 'Your message to the seller...'

            }),

        }

User Experience Features:

def __init__(self, *args, **kwargs):

    user = kwargs.pop('user', None)

    # Pre-populate with user data if logged in

    if user and user.is_authenticated:

        self.fields['name'].initial = f"{user.first_name} {user.last_name}".strip() or user.username

        self.fields['email'].initial = user.email

• Auto-Fill: Logged-in users get pre-populated fields
• Fallback Logic: Username if no first/last name available
• Contact Tracking: Links inquiries to specific ads

Integration Points:

• Ad Detail View: Embedded in ad detail page
• Email Notifications: Triggers seller notifications
• Admin Interface: Inquiry management for sellers

5. CategoryForm - Administrative Category Management

Hierarchical Category System

class CategoryForm(forms.ModelForm):

    class Meta:

        model = Category

        fields = ['name', 'description', 'parent', 'icon', 'slug', 'is_active']

        widgets = {

            'icon': forms.TextInput(attrs={'placeholder': 'e.g., fas fa-car'}),

            'slug': forms.TextInput(attrs={'class': 'form-control'}),

        }

Administrative Features:

• Parent-Child Relationships: Hierarchical category structure
• Icon Integration: Font Awesome class specification
• SEO-Friendly: Slug field for clean URLs
• Status Control: Active/inactive toggle
• Visual Guidelines: Icon placeholder examples

Form Integration Patterns

1. View Integration

# In views.py

def get_form_kwargs(self):

    kwargs = super().get_form_kwargs()

    kwargs['user'] = self.request.user  # Pass user context

    return kwargs

2. Template Usage

<!-- In templates -->

{{ form|crispy }}

{{ formset|crispy }}

3. AJAX Enhancement

// JavaScript integration for dynamic features

function toggleFavorite(adId) {

    // AJAX calls work with form data

}

Advanced Form Features

1. Validation Logic

• Custom Validators: Price range validation
• Cross-Field Validation: Translation completeness checks
• File Upload Validation: Image format and size restrictions

2. Internationalization

• Language Detection: Dynamic labels based on user locale
• Translation Helpers: Built-in translation workflow support
• Cultural Adaptation: Vietnamese-specific input patterns

3. Performance Optimizations

• Lazy Loading: Category and location querysets
• Cached Choices: Static choice fields for better performance
• Efficient Formsets: Optimized for multiple image handling

4. Security Features

• CSRF Protection: All forms include CSRF tokens
• File Upload Security: Image validation and sanitization
• Input Sanitization: XSS prevention in text fields

Usage Scenarios

1. New Ad Creation

1. User accesses create form → Pre-populated contact info
2. Fills English content → Optional Vietnamese translation
3. Uploads images → Multiple files with captions
4. Chooses Draft/Publish → Status-based workflow

2. Ad Search & Filtering

1. User accesses search form → Persistent filter state
2. Applies multiple criteria → Combined query execution
3. Results with pagination → Maintains search context

3. User Communication

1. Visitor finds interesting ad → Embedded inquiry form
2. Submits inquiry → Seller notification triggered
3. Conversation tracking → Admin interface management

This form system provides a complete, user-friendly interface for all classified ads operations with advanced features like multilingual support, image management, and sophisticated search capabilities.