GitHubEmailContact
Skip to main content

Basic Field Types

Essential field types for common use cases in Django Admin.

BadgeField​

Display values as colored badges with optional icons.

Parameters​

class BadgeField(FieldConfig):
    name: str                                    # Field name
    title: str | None = None                     # Display title
    variant: Literal[                            # Badge color
        "primary", "secondary", "success",
        "danger", "warning", "info"
    ] = "primary"
    icon: str | None = None                      # Material icon name
    label_map: dict[str, str] | None = None      # Value → variant mapping
    empty_value: str = "—"                       # Value when None
    ordering: str | None = None                  # Sort field

Basic Usage​

from django_cfg.modules.django_admin import BadgeField, Icons

# Simple badge
BadgeField(
    name="status",
    title="Status",
    variant="primary",
)

# Badge with icon
BadgeField(
    name="category",
    title="Category",
    variant="info",
    icon=Icons.CATEGORY,
)

# Badge with conditional colors
BadgeField(
    name="status",
    title="Status",
    label_map={
        "pending": "warning",
        "approved": "success",
        "rejected": "danger",
    },
    icon=Icons.CHECK_CIRCLE,
)

Examples​

display_fields=[
    BadgeField(
        name="status",
        title="Status",
        label_map={
            "draft": "secondary",
            "pending": "warning",
            "published": "success",
            "archived": "info",
        },
        icon=Icons.ARTICLE,
    ),
]
When to Use label_map

Use label_map when you need different colors for different values. The map translates field values to badge variants.

BooleanField​

Display boolean values with checkmark/cross icons.

Parameters​

class BooleanField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Basic Usage​

from django_cfg.modules.django_admin import BooleanField

# Simple boolean
BooleanField(
    name="is_active",
    title="Active",
)

# With ordering
BooleanField(
    name="is_published",
    title="Published",
    ordering="is_published",
)

Examples​

display_fields=[
    BooleanField(name="is_active", title="Active"),
    BooleanField(name="is_verified", title="Verified"),
    BooleanField(name="email_confirmed", title="Email Confirmed"),
]
Automatic Rendering

BooleanField automatically renders as:

  • ✅ Green checkmark for True
  • ❌ Red cross for False
  • "—" for None

TextField​

Display text with truncation, CSS styling, and tooltip on hover.

Parameters​

class TextField(FieldConfig):
    name: str                          # Field name
    title: str | None = None           # Display title
    truncate: int | None = None        # Truncate after N characters
    monospace: bool = False            # Use monospace font (for code, hashes)
    nowrap: bool = True                # Prevent line wrapping (default: True)
    max_width: str = "300px"           # CSS max-width for text cell
    show_tooltip: bool = True          # Show full text on hover when truncated
    empty_value: str = "—"             # Value when None
    ordering: str | None = None        # Sort field

Basic Usage​

from django_cfg.modules.django_admin import TextField

# Simple text with default settings
TextField(
    name="description",
    title="Description",
)

# Truncated text (shows "..." and tooltip on hover)
TextField(
    name="content",
    title="Content",
    truncate=80,
    max_width="400px",
)

# Monospace for hashes/code
TextField(
    name="hash",
    title="Hash",
    truncate=16,
    monospace=True,
)

# Allow wrapping (for multi-line content)
TextField(
    name="message",
    title="Message",
    truncate=200,
    nowrap=False,
)

Examples​

display_fields=[
    TextField(
        name="description",
        title="Description",
        truncate=50,
    ),
]

Result: Text truncated to 50 chars with "..." and full text in tooltip.

Styling Details​

TextField renders with smart CSS:

white-space: nowrap;      /* No line breaks (when nowrap=True) */
overflow: hidden;         /* Hide overflow */
text-overflow: ellipsis;  /* Show "..." */
max-width: 300px;         /* Configurable width */
Best Practices
  • Use truncate for long text to keep list views compact
  • Set max_width="400px" or larger for important content like messages
  • Enable monospace=True for technical content (hashes, IDs, code)
  • Set nowrap=False only for detail views where multi-line is acceptable
  • Hover over truncated text to see full content in tooltip

Next Steps​

Last updated on