Bài 2.3: Advanced Model Fields - Phần 3 - Custom Model Fields

**Series Navigation:** - [Bài 2.1: JSONField](/django-advance/advanced-model-fields-phan-1) - [Bài 2.2: ArrayField & HStoreField](/django-advance/advanced-model-fields-phan-2) - **Bài 2.3 (bài này): Custom Model Fields** 👈 - [Bài 2.4: Computed Fields & Model Mixins](/django-advance/advanced-model-fields-phan-4)

Mục Tiêu Bài 2.3

Sau khi hoàn thành Bài 2.3 này, bạn sẽ:

✅ Hiểu kiến trúc của Django Field class
✅ Tạo được custom fields từ đầu
✅ Implement các core methods: to_python(), from_db_value(), get_prep_value()
✅ Thêm validation logic vào custom fields
✅ Hỗ trợ migrations với deconstruct()
✅ Tích hợp form fields với formfield()
✅ Build reusable field components cho projects

Giới Thiệu

Tại Sao Cần Custom Fields?

Django cung cấp nhiều built-in fields (CharField, IntegerField, DateField...), nhưng trong real-world projects, bạn thường gặp các use cases đặc biệt:

1. Domain-Specific Data Types:

MoneyField: Lưu tiền tệ kèm currency code
ColorField: Lưu màu với format validation
PhoneNumberField: Lưu số điện thoại theo format quốc gia
CoordinatesField: Lưu latitude/longitude

2. Complex Validation Logic:

Email với domain whitelist/blacklist
URL với protocol restrictions
Text với content filtering

3. Automatic Transformations:

Lowercase/uppercase enforcement
Trimming whitespace
Format normalization

4. Reusability:

Tạo một lần, dùng nhiều nơi
Centralized logic
Easier maintenance

Built-in Field vs Custom Field

Built-in Field:

# Simple, nhưng thiếu business logicprice = models.DecimalField(max_digits=10, decimal_places=2)currency = models.CharField(max_length=3, default='USD')

Custom Field:

# Encapsulated logic, type-safeprice = MoneyField(default_currency='USD')# Automatically handles currency conversion, validation, display

Django Field Architecture

Field Class Hierarchy

Django fields kế thừa từ django.db.models.Field base class:

Field (base class)├── CharField│   ├── EmailField│   ├── URLField│   └── SlugField├── IntegerField│   ├── BigIntegerField│   ├── SmallIntegerField│   └── AutoField├── DateTimeField│   └── DateField└── ... (many others)

Core Responsibilities of a Field

Django Field phải xử lý 4 tầng conversion:

1. Python → Database (Write Path):

Python object → get_prep_value() → Database typeExample: Decimal('99.99') → '99.99' → DECIMAL in DB

2. Database → Python (Read Path):

Database type → to_python() → Python objectExample: '99.99' from DB → Decimal('99.99')

3. User Input → Python (Form/API):

String input → to_python() → Python objectExample: "99.99" → Decimal('99.99')

4. Python → Display (Template/Serializer):

Python object → value_to_string() → StringExample: Decimal('99.99') → "$99.99 USD"

Core Methods Deep Dive

1. `init()` - Field Initialization

Purpose: Định nghĩa field parameters và default values.

Pattern:

def __init__(self, custom_param=None, *args, **kwargs):    self.custom_param = custom_param    super().__init__(*args, **kwargs)

Key Points:

Accept custom parameters
Set instance attributes
Call super().__init__() cuối cùng
Validate parameters nếu cần

Example - MoneyField:

def __init__(self, default_currency='USD', max_digits=10,              decimal_places=2, *args, **kwargs):    self.default_currency = default_currency    self.max_digits = max_digits    self.decimal_places = decimal_places    super().__init__(*args, **kwargs)

2. `deconstruct()` - Migration Support

Purpose: Serialize field definition cho migrations.

Return Value: Tuple of (name, path, args, kwargs)

Pattern:

def deconstruct(self):    name, path, args, kwargs = super().deconstruct()    # Add custom parameters to kwargs    if self.custom_param != default_value:        kwargs['custom_param'] = self.custom_param    return name, path, args, kwargs

Key Points:

Always call super().deconstruct() first
Only include non-default values
Keep migrations clean và readable
Handle backward compatibility

Example - MoneyField:

def deconstruct(self):    name, path, args, kwargs = super().deconstruct()    if self.default_currency != 'USD':        kwargs['default_currency'] = self.default_currency    kwargs['max_digits'] = self.max_digits    kwargs['decimal_places'] = self.decimal_places    return name, path, args, kwargs

Why Important?

Django sử dụng để generate migration files
Không implement đúng → migration errors
Affects model history và deployment

3. `db_type()` - Database Column Type

Purpose: Xác định SQL column type trong database.

Pattern:

def db_type(self, connection):    return 'VARCHAR(255)'  # or 'INTEGER', 'TEXT', etc.

Key Points:

Return SQL type string
Can vary by database backend (connection.vendor)
Return None to inherit from base field

Example - ColorField (storing hex codes):

def db_type(self, connection):    return 'VARCHAR(7)'  # #RRGGBB format

Example - MoneyField (using PostgreSQL JSONB):

def db_type(self, connection):    if connection.vendor == 'postgresql':        return 'JSONB'    return 'TEXT'  # Fallback for other databases

4. `to_python()` - Convert to Python Object

Purpose: Convert database value hoặc user input thành Python object.

Called When:

Reading from database
Deserializing (fixtures, API)
Form cleaning
Setting attribute directly

Pattern:

def to_python(self, value):    # Already correct type?    if isinstance(value, ExpectedType):        return value        # None/empty check    if value is None or value == '':        return None        # Convert from various input formats    try:        return convert_to_expected_type(value)    except (ValueError, TypeError):        raise ValidationError('Invalid value')

Example - MoneyField:

def to_python(self, value):    # Already a Money object    if isinstance(value, Money):        return value        # None/empty    if value is None or value == '':        return None        # From database (JSONB dict)    if isinstance(value, dict):        return Money(            amount=Decimal(value['amount']),            currency=value['currency']        )        # From string "99.99 USD"    if isinstance(value, str):        parts = value.split()        if len(parts) == 2:            return Money(                amount=Decimal(parts[0]),                currency=parts[1]            )        # Invalid format    raise ValidationError(f'Invalid money format: {value}')

Key Points:

Handle multiple input formats
Type checking first (avoid redundant conversion)
Clear error messages
Return None for empty values

5. `from_db_value()` - Database to Python

Purpose: Convert raw database value thành Python object.

Called When:

Loading objects from database (only)

Pattern:

def from_db_value(self, value, expression, connection):    if value is None:        return value    return self.to_python(value)

Key Points:

Similar to to_python() but specifically for DB reads
Often delegates to to_python()
Required nếu field lưu custom format trong DB

Example - ColorField (storing as integer):

def from_db_value(self, value, expression, connection):    if value is None:        return None    # Convert integer (RGB) to hex string    return f'#{value:06X}'  # e.g., 16711680 → '#FF0000'

When to Implement?

✅ Custom database storage format
✅ Database-specific transformations
❌ Standard fields often don't need this

6. `get_prep_value()` - Python to Database

Purpose: Convert Python object thành database-compatible value.

Called When:

Saving to database
Querying (lookups, filters)

Pattern:

def get_prep_value(self, value):    value = super().get_prep_value(value)    if value is None:        return None    # Convert Python object to DB-compatible format    return prepare_for_database(value)

Example - MoneyField:

def get_prep_value(self, value):    value = super().get_prep_value(value)    if value is None:        return None        # Convert Money object to JSONB dict    if isinstance(value, Money):        return {            'amount': str(value.amount),  # Decimal → string            'currency': value.currency        }        return value

Example - ColorField (hex to integer):

def get_prep_value(self, value):    value = super().get_prep_value(value)    if value is None:        return None        # Convert hex string to integer    # '#FF0000' → 16711680    if value.startswith('#'):        value = value[1:]    return int(value, 16)

Key Points:

Always call super().get_prep_value() first
Return database-compatible types (str, int, dict...)
Handle None explicitly

7. `formfield()` - Form Field Integration

Purpose: Return form field for ModelForm integration.

Pattern:

def formfield(self, **kwargs):    defaults = {        'form_class': CustomFormField,        'custom_param': self.custom_param,    }    defaults.update(kwargs)    return super().formfield(**defaults)

Example - MoneyField:

def formfield(self, **kwargs):    from myapp.forms import MoneyFormField    defaults = {        'form_class': MoneyFormField,        'default_currency': self.default_currency,    }    defaults.update(kwargs)    return super().formfield(**defaults)

Key Points:

Create corresponding form field
Pass field-specific parameters
Allow override via kwargs
Returns forms.Field subclass

Validation in Custom Fields

Field-Level Validation

1. Using Validators:

from django.core.validators import MinValueValidator class RatingField(models.IntegerField):    def __init__(self, *args, **kwargs):        kwargs.setdefault('validators', [            MinValueValidator(1),            MaxValueValidator(5)        ])        super().__init__(*args, **kwargs)

2. Custom Validator Functions:

def validate_hex_color(value):    if not re.match(r'^#[0-9A-Fa-f]{6}$', value):        raise ValidationError('Invalid hex color format') class ColorField(models.CharField):    def __init__(self, *args, **kwargs):        kwargs['max_length'] = 7        kwargs.setdefault('validators', [validate_hex_color])        super().__init__(*args, **kwargs)

3. Override validate() Method:

class EmailDomainField(models.EmailField):    def __init__(self, allowed_domains=None, *args, **kwargs):        self.allowed_domains = allowed_domains or []        super().__init__(*args, **kwargs)        def validate(self, value, model_instance):        super().validate(value, model_instance)                if self.allowed_domains and value:            domain = value.split('@')[1]            if domain not in self.allowed_domains:                raise ValidationError(                    f'Email domain must be one of: {self.allowed_domains}'                )

Pre-Save Transformations

Use Case: Normalize data before saving.

Pattern - Override pre_save():

class LowercaseEmailField(models.EmailField):    def pre_save(self, model_instance, add):        value = getattr(model_instance, self.attname)        if value:            value = value.lower()            setattr(model_instance, self.attname, value)        return super().pre_save(model_instance, add)

Example - Auto-slug Field:

class AutoSlugField(models.SlugField):    def __init__(self, source_field, *args, **kwargs):        self.source_field = source_field        kwargs['editable'] = False        kwargs['blank'] = True        super().__init__(*args, **kwargs)        def pre_save(self, model_instance, add):        # Auto-generate slug from source field        source_value = getattr(model_instance, self.source_field)        if source_value:            slug = slugify(source_value)            setattr(model_instance, self.attname, slug)            return slug        return super().pre_save(model_instance, add)

Real-World Custom Field Examples

Example 1: MoneyField với Currency Support

Requirements:

Store amount và currency together
Type-safe operations
Currency conversion support
Format display based on locale

Implementation Outline:

Step 1 - Money Value Object:

from decimal import Decimal class Money:    def __init__(self, amount, currency='USD'):        self.amount = Decimal(str(amount))        self.currency = currency.upper()        def __str__(self):        return f'{self.amount} {self.currency}'        def __repr__(self):        return f'Money({self.amount}, {self.currency})'        def __eq__(self, other):        if not isinstance(other, Money):            return False        return (self.amount == other.amount and                 self.currency == other.currency)

Step 2 - MoneyField:

from django.db import modelsfrom django.core.exceptions import ValidationErrorimport json class MoneyField(models.Field):    def __init__(self, default_currency='USD', max_digits=10,                  decimal_places=2, *args, **kwargs):        self.default_currency = default_currency        self.max_digits = max_digits        self.decimal_places = decimal_places        super().__init__(*args, **kwargs)        def deconstruct(self):        name, path, args, kwargs = super().deconstruct()        if self.default_currency != 'USD':            kwargs['default_currency'] = self.default_currency        kwargs['max_digits'] = self.max_digits        kwargs['decimal_places'] = self.decimal_places        return name, path, args, kwargs        def db_type(self, connection):        # Use JSONB for PostgreSQL, TEXT for others        if connection.vendor == 'postgresql':            return 'JSONB'        return 'TEXT'        def to_python(self, value):        if isinstance(value, Money):            return value        if value is None or value == '':            return None                # From database (dict/JSON)        if isinstance(value, dict):            return Money(value['amount'], value['currency'])        if isinstance(value, str):            try:                data = json.loads(value)                return Money(data['amount'], data['currency'])            except (json.JSONDecodeError, KeyError):                raise ValidationError('Invalid money format')                raise ValidationError(f'Cannot convert {value} to Money')        def from_db_value(self, value, expression, connection):        return self.to_python(value)        def get_prep_value(self, value):        if value is None:            return None        if isinstance(value, Money):            data = {                'amount': str(value.amount),                'currency': value.currency            }            # Return dict for PostgreSQL JSONB, JSON string for others            if hasattr(self, '_db_type') and self._db_type == 'JSONB':                return data            return json.dumps(data)        return value

Usage:

class Product(models.Model):    name = models.CharField(max_length=200)    price = MoneyField(default_currency='USD') # Createproduct = Product.objects.create(    name='Laptop',    price=Money(999.99, 'USD')) # Queryexpensive_products = Product.objects.filter(    price__amount__gte=500)

Example 2: ColorField với Hex Validation

Requirements:

Store colors as hex codes
Validate format (#RRGGBB)
Support RGB tuple conversion
Color picker form widget

Implementation Outline:

Step 1 - ColorField:

import refrom django.db import modelsfrom django.core.exceptions import ValidationError def validate_hex_color(value):    """Validate hex color format #RRGGBB"""    if not re.match(r'^#[0-9A-Fa-f]{6}$', value):        raise ValidationError(            f'{value} is not a valid hex color. Use format #RRGGBB'        ) class ColorField(models.CharField):    def __init__(self, *args, **kwargs):        kwargs['max_length'] = 7        kwargs.setdefault('validators', [validate_hex_color])        super().__init__(*args, **kwargs)        def deconstruct(self):        name, path, args, kwargs = super().deconstruct()        del kwargs['max_length']  # Always 7        return name, path, args, kwargs        def to_python(self, value):        value = super().to_python(value)        if value:            value = value.upper()  # Normalize to uppercase        return value        def formfield(self, **kwargs):        from myapp.forms import ColorFormField        kwargs['form_class'] = ColorFormField        return super().formfield(**kwargs)

Step 2 - Helper Methods (add to ColorField):

def to_rgb(self):    """Convert hex to RGB tuple"""    if not self:        return None    hex_color = self.lstrip('#')    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) @classmethoddef from_rgb(cls, r, g, b):    """Create hex from RGB values"""    return f'#{r:02X}{g:02X}{b:02X}'

Usage:

class Theme(models.Model):    name = models.CharField(max_length=100)    primary_color = ColorField(default='#007BFF')    background_color = ColorField(default='#FFFFFF') # Createtheme = Theme.objects.create(    name='Ocean',    primary_color='#0077BE',    background_color='#F0F8FF') # Convert to RGBrgb = theme.primary_color.to_rgb()  # (0, 119, 190)

Example 3: PhoneNumberField với International Format

Requirements:

Store phone numbers với country code
Validate format per country
Format display consistently
Support search by partial number

Implementation Strategy:

Use Existing Library:

phonenumbers library by Google
Handles international formats
Validation included
Format conversion

Field Implementation:

import phonenumbersfrom django.db import modelsfrom django.core.exceptions import ValidationError class PhoneNumberField(models.CharField):    def __init__(self, region='VN', *args, **kwargs):        self.region = region  # Default country code        kwargs['max_length'] = 20        super().__init__(*args, **kwargs)        def deconstruct(self):        name, path, args, kwargs = super().deconstruct()        if self.region != 'VN':            kwargs['region'] = self.region        del kwargs['max_length']        return name, path, args, kwargs        def to_python(self, value):        if value is None or value == '':            return None                try:            # Parse with default region            phone = phonenumbers.parse(value, self.region)            # Validate            if not phonenumbers.is_valid_number(phone):                raise ValidationError(f'Invalid phone number: {value}')            # Return international format            return phonenumbers.format_number(                phone,                 phonenumbers.PhoneNumberFormat.E164            )        except phonenumbers.NumberParseException:            raise ValidationError(f'Cannot parse phone number: {value}')        def pre_save(self, model_instance, add):        # Ensure consistent format before save        value = getattr(model_instance, self.attname)        if value:            value = self.to_python(value)            setattr(model_instance, self.attname, value)        return super().pre_save(model_instance, add)

Usage:

class Contact(models.Model):    name = models.CharField(max_length=100)    phone = PhoneNumberField(region='VN') # Create with various formatscontact = Contact.objects.create(    name='Nguyen Van A',    phone='0912345678'  # Auto-formatted to +84912345678) # International numbercontact2 = Contact.objects.create(    name='John Doe',    phone='+1-555-123-4567'  # Stored as +15551234567)

Best Practices for Custom Fields

1. Naming Conventions

Field Class Names:

End with "Field": MoneyField, ColorField
Descriptive: EmailDomainField not EField

Parameters:

Use lowercase with underscores: default_currency
Prefix field-specific params: color_format not just format

2. Documentation

Always Document:

Purpose và use cases
Parameters và defaults
Database storage format
Example usage

Example:

class MoneyField(models.Field):    """    Field for storing monetary values with currency.        Stores amount as Decimal and currency code as string.    Database storage: JSONB (PostgreSQL) or TEXT (others)        Parameters:        default_currency (str): Default currency code (default: 'USD')        max_digits (int): Max total digits (default: 10)        decimal_places (int): Decimal places (default: 2)        Example:        price = MoneyField(default_currency='VND', max_digits=15)    """

3. Error Handling

Clear Error Messages:

# Badraise ValidationError('Invalid value') # Goodraise ValidationError(    f'Invalid money format: {value}. '    f'Expected format: {{"amount": "99.99", "currency": "USD"}}')

Handle Edge Cases:

None values
Empty strings
Type mismatches
Database read failures

4. Testing Custom Fields

Test Coverage Should Include:

1. Basic Operations:

Create objects
Update values
Delete objects
Query by field

2. Validation:

Valid inputs
Invalid inputs
Edge cases (None, empty, extreme values)

3. Database Round-trip:

Save và reload
Verify data integrity

4. Form Integration:

Form field creation
Form validation
Widget rendering

Example Test Structure:

from django.test import TestCasefrom django.core.exceptions import ValidationError class MoneyFieldTests(TestCase):    def test_create_with_money_object(self):        product = Product.objects.create(            name='Test',            price=Money(99.99, 'USD')        )        self.assertEqual(product.price.amount, Decimal('99.99'))        self.assertEqual(product.price.currency, 'USD')        def test_database_roundtrip(self):        product = Product.objects.create(            name='Test',            price=Money(99.99, 'USD')        )        # Reload from database        product.refresh_from_db()        self.assertIsInstance(product.price, Money)        self.assertEqual(product.price.amount, Decimal('99.99'))        def test_invalid_format_raises_error(self):        with self.assertRaises(ValidationError):            Product.objects.create(                name='Test',                price='invalid'            )

5. Performance Considerations

Avoid Heavy Operations in:

to_python() - called frequently
get_prep_value() - called on every query

Cache Expensive Computations:

class ComplexField(models.Field):    def to_python(self, value):        if hasattr(self, '_cached_value') and self._cached_value[0] == value:            return self._cached_value[1]                result = expensive_operation(value)        self._cached_value = (value, result)        return result

Database Considerations:

Choose appropriate column type
Consider indexing needs
Monitor query performance

Tóm Tắt Bài 2.3

Trong Bài 2.3 này, bạn đã học:

✅ Field Architecture:

Field class hierarchy
4 conversion paths: Python ↔ Database ↔ Forms ↔ Display
Core responsibilities

✅ Core Methods:

__init__(): Field initialization và parameters
deconstruct(): Migration support
db_type(): Database column type
to_python(): Convert to Python object
from_db_value(): Database to Python
get_prep_value(): Python to database
formfield(): Form integration

✅ Validation:

Field-level validators
Custom validator functions
Override validate() method
Pre-save transformations với pre_save()

✅ Real-World Examples:

MoneyField: Currency support với value object
ColorField: Hex validation và RGB conversion
PhoneNumberField: International format với library

✅ Best Practices:

Naming conventions
Comprehensive documentation
Clear error handling
Thorough testing
Performance optimization

Exercises

Exercise 1: URLField với Protocol Restriction

Requirements:

Extend Django's URLField
Only allow HTTPS URLs (no HTTP)
Validate domain is not in blacklist
Store normalized URL (lowercase domain)

Hints:

Override validate() method
Use pre_save() for normalization
Use urlparse from Python stdlib

Expected Behavior:

class Website(models.Model):    url = SecureURLField(blacklist=['example.com']) # Validsite = Website.objects.create(url='https://django.com') # Invalid - HTTP protocolsite = Website.objects.create(url='http://django.com')  # ValidationError # Invalid - blacklisted domainsite = Website.objects.create(url='https://example.com')  # ValidationError

Exercise 2: PercentageField

Requirements:

Store percentage as decimal (0.0 to 1.0 in DB)
Accept input as percentage (0-100) or decimal (0.0-1.0)
Display as percentage with symbol (e.g., "75%")
Validate range 0-100

Hints:

Subclass DecimalField
Override to_python() to handle both formats
Override get_prep_value() to store as decimal
Add custom __str__() method to value object

Expected Behavior:

class Product(models.Model):    discount = PercentageField() # Accept percentageproduct = Product.objects.create(discount=25)  # Stores 0.25 # Accept decimalproduct = Product.objects.create(discount=0.25)  # Stores 0.25 # Displayprint(product.discount)  # "25%" # QueryProduct.objects.filter(discount__gte=0.20)  # 20% or more

Exercise 3: TagsField Wrapper

Requirements:

Wrap ArrayField để create specialized tags field
Automatic lowercase conversion
Unique tags enforcement
Maximum 10 tags
Helper methods: add_tag(), remove_tag(), has_tag()

Hints:

Use ArrayField as base
Override pre_save() for transformations
Add validation in validate()
Create helper methods (not field methods, model methods)

Expected Behavior:

class Article(models.Model):    title = models.CharField(max_length=200)    tags = TagsField()        def add_tag(self, tag):        # Implementation        pass # Createarticle = Article.objects.create(    title='Test',    tags=['Python', 'Django']) # Add tag (helper method)article.add_tag('Web Development') # Tags auto-lowercasedarticle.tags  # ['python', 'django', 'web development'] # QueryArticle.objects.filter(tags__contains=['python'])

Next Steps

Trong Bài 2.4, bạn sẽ học:

Computed fields với @property
Cached properties cho expensive operations
Model Mixins (TimestampMixin, SoftDeleteMixin, AuditMixin)
Abstract Models vs concrete inheritance
Model Managers và Custom QuerySets
Signals: pre_save, post_save, pre_delete, post_delete

Navigation:

← Bài 2.2: ArrayField & HStoreField
Bài 2.3: Custom Model Fields (current)
Bài 2.4: Computed Fields & Model Mixins →

#field-development

Advanced Model Fields - Phần 3 - Custom Model Fields