Skip to Content
DocumentationFeaturesAuto-Configuring ModulesDjango AdminField TypesFormatting Fields

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

Basic Prices

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

Multi-Currency

display_fields=[
    CurrencyField(name="price_usd", title="USD", currency="USD", precision=2),
    CurrencyField(name="price_eur", title="EUR", currency="EUR", precision=2),
    CurrencyField(name="price_gbp", title="GBP", currency="GBP", precision=2),
]

Crypto Prices

display_fields=[
    CurrencyField(
        name="current_price_usd",
        title="Price",
        currency="USD",
        precision=2,
    ),
    CurrencyField(
        name="market_cap_usd",
        title="Market Cap",
        currency="USD",
        precision=0,  # No decimals for large numbers
    ),
]

Renders as: $1,234 (no decimals)

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

Basic Decimals

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

Percentages

display_fields=[
    DecimalField(
        name="confidence",
        title="Confidence",
        decimal_places=2,
        suffix="%",
    ),
    DecimalField(
        name="change_24h",
        title="24h Change",
        decimal_places=2,
        suffix="%",
        show_sign=True,
    ),
]

Renders as: 95.50%, +3.25%

Crypto Amounts

display_fields=[
    DecimalField(
        name="btc_amount",
        title="BTC",
        decimal_places=8,
        suffix=" BTC",
    ),
    DecimalField(
        name="eth_amount",
        title="ETH",
        decimal_places=18,
        suffix=" ETH",
    ),
]

Renders as: 0.12345678 BTC, 1.500000000000000000 ETH

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

With Relative Time

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

Without Relative Time

display_fields=[
    DateTimeField(
        name="posted_at",
        title="Posted",
        show_relative=False,
    ),
]

Renders as:

2025-11-25
16:06:03 KST

Keep UTC

display_fields=[
    DateTimeField(
        name="server_timestamp",
        title="Server Time",
        use_local_tz=False,  # Keep original timezone
        show_relative=False,
    ),
]

Renders as:

2025-11-25
08:06:03 UTC

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

Basic UUID

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

Renders as: a1b2c3d4 (with full UUID on hover)

Custom Length

display_fields=[
    ShortUUIDField(
        name="transaction_id",
        title="Transaction",
        length=12,
        ordering="transaction_id",
    ),
]

Renders as: a1b2c3d4e5f6

Multiple IDs

display_fields=[
    ShortUUIDField(name="id", title="ID", length=8),
    ShortUUIDField(name="parent_id", title="Parent", length=8),
    ShortUUIDField(name="reference_id", title="Reference", length=10),
]

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

Display FieldsAdvanced Fields