GitHubEmailContact
Skip to main content

Formatting Field Types

Learn about specialized field types that format and display values in Django Admin.

CurrencyField​

Format numbers as currency with symbols and precision.

Parameters​

class CurrencyField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    currency: str = "USD"              # Currency code (USD, EUR, etc.)
    precision: int = 2                 # Decimal places
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Basic Usage​

from django_cfg.modules.django_admin import CurrencyField

# USD with 2 decimals
CurrencyField(
    name="price",
    title="Price",
    currency="USD",
    precision=2,
)

# EUR with 2 decimals
CurrencyField(
    name="total",
    title="Total",
    currency="EUR",
    precision=2,
)

# No decimals for large amounts
CurrencyField(
    name="market_cap",
    title="Market Cap",
    currency="USD",
    precision=0,
)

Examples​

display_fields=[
    CurrencyField(
        name="price",
        title="Price",
        currency="USD",
        precision=2,
    ),
    CurrencyField(
        name="discount",
        title="Discount",
        currency="USD",
        precision=2,
    ),
    CurrencyField(
        name="total",
        title="Total",
        currency="USD",
        precision=2,
        ordering="total",
    ),
]

Renders as: $1,234.56

DecimalField​

Format decimal numbers with custom precision and optional prefix/suffix.

Parameters​

class DecimalField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    decimal_places: int = 2            # Decimal places to display
    prefix: str | None = None          # Prefix symbol (e.g., "$")
    suffix: str | None = None          # Suffix symbol (e.g., "%", "BTC")
    show_sign: bool = False            # Show +/- sign
    thousand_separator: bool = True    # Use thousand separator
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Basic Usage​

from django_cfg.modules.django_admin import DecimalField

# Basic decimal
DecimalField(
    name="price",
    title="Price",
    decimal_places=8,
)

# Percentage
DecimalField(
    name="confidence",
    title="Confidence",
    decimal_places=2,
    suffix="%",
)

# With prefix
DecimalField(
    name="amount",
    title="Amount",
    decimal_places=2,
    prefix="$",
    show_sign=True,
)

Examples​

display_fields=[
    DecimalField(
        name="price",
        title="Price",
        decimal_places=8,
    ),
    DecimalField(
        name="quantity",
        title="Quantity",
        decimal_places=4,
    ),
]

Renders as: 1,234.56789012, 100.5000

When to use DecimalField vs CurrencyField
  • Use DecimalField for generic decimal numbers, percentages, or crypto amounts with custom suffixes
  • Use CurrencyField specifically for fiat currency display with currency symbols (USD, EUR, etc.)

DateTimeField​

Format datetime values with timezone support and relative time display.

Parameters​

class DateTimeField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    datetime_format: str | None = None # Custom format (default: "%Y-%m-%d %H:%M:%S")
    show_relative: bool = True         # Show relative time ("2 hours ago")
    use_local_tz: bool = True          # Convert to local timezone (default: True)
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Timezone Support​

DateTimeField automatically converts times to the local timezone:

  1. First tries DjangoConfig.admin_timezone if configured
  2. Falls back to system timezone via tzlocal

Configure in your Django config:

class MyConfig(DjangoConfig):
    admin_timezone = "Asia/Seoul"  # Or None for system timezone

Display Format​

DateTimeField renders in a clean multi-line format:

2025-11-25        ← Date (bold)
16:06:03 KST      ← Time + timezone (gray)
2 hours ago       ← Relative time (gray, optional)

Basic Usage​

from django_cfg.modules.django_admin import DateTimeField

# With relative time (default)
DateTimeField(
    name="created_at",
    title="Created",
    show_relative=True,
)

# Without relative time
DateTimeField(
    name="posted_at",
    title="Posted",
    show_relative=False,
)

# Keep UTC (don't convert to local timezone)
DateTimeField(
    name="server_time",
    title="Server Time",
    use_local_tz=False,
)

Examples​

display_fields=[
    DateTimeField(
        name="created_at",
        title="Created",
        show_relative=True,
        ordering="created_at",
    ),
]

Renders as:

2025-11-25
16:06:03 KST
2 hours ago
Timezone Best Practices
  • Use use_local_tz=True (default) for user-facing timestamps
  • Set use_local_tz=False for server/system timestamps that should stay in UTC
  • Configure admin_timezone in DjangoConfig for consistent display across all admins

ShortUUIDField​

Display shortened UUIDs with hover tooltip showing full value.

Parameters​

class ShortUUIDField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    length: int = 8                    # Number of characters to display
    copy_on_click: bool = True         # Enable click-to-copy
    show_full_on_hover: bool = True    # Show full UUID in tooltip
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Basic Usage​

from django_cfg.modules.django_admin import ShortUUIDField

# Simple shortened UUID
ShortUUIDField(
    name="id",
    title="ID",
    length=8,
)

# Longer display
ShortUUIDField(
    name="uuid",
    title="UUID",
    length=12,
)

# With ordering
ShortUUIDField(
    name="id",
    title="ID",
    length=8,
    ordering="id",
)

Examples​

display_fields=[
    ShortUUIDField(
        name="id",
        title="ID",
        length=8,
    ),
]

Renders as: a1b2c3d4 (with full UUID on hover)

Perfect for List Views

ShortUUIDField is ideal for admin list views where you need to display UUIDs without taking up too much space. Users can hover to see the full UUID or click to copy it.

Automatic Formatting

ShortUUIDField automatically:

  • Removes dashes for cleaner display
  • Shows tooltip with full UUID on hover
  • Enables click-to-copy functionality
  • Styles as inline code block

Next Steps​

Last updated on