GitHubEmailContact
Skip to main content

Advanced Field Types

Advanced field types for displaying complex status information, counters, and conditional badges.

StatusBadgesField​

Display multiple conditional badges based on model field values. Perfect for showing multiple status flags like permissions, features, or user attributes.

Parameters​

class StatusBadgesField(FieldConfig):
    name: str                                   # Field name
    title: str | None = None                    # Display title
    badge_rules: list[BadgeRule]                # List of badge rules
    empty_text: str | None = None               # Text when no badges match
    empty_variant: str = "secondary"            # Variant for empty badge
    separator: str = " "                        # Separator between badges

BadgeRule​

class BadgeRule:
    condition_field: str                        # Field to check (e.g., "is_bot")
    condition_value: Any = True                 # Value that triggers badge
    label: str                                  # Badge text
    variant: Literal["primary", "secondary", "success", "danger", "warning", "info"]
    icon: str | None = None                     # Material icon name

Basic Usage​

from django_cfg.modules.django_admin import StatusBadgesField, BadgeRule, Icons

# User status badges
StatusBadgesField(
    name="status_badges",
    title="Status",
    badge_rules=[
        BadgeRule(
            condition_field="is_bot",
            condition_value=True,
            label="Bot",
            variant="info",
            icon=Icons.SMART_TOY
        ),
        BadgeRule(
            condition_field="is_verified",
            condition_value=True,
            label="Verified",
            variant="success",
            icon=Icons.VERIFIED
        ),
        BadgeRule(
            condition_field="is_premium",
            condition_value=True,
            label="Premium",
            variant="warning",
            icon=Icons.STAR
        ),
    ],
    empty_text="Regular",
    empty_variant="secondary"
)

Examples​

display_fields=[
    StatusBadgesField(
        name="user_flags",
        title="Flags",
        badge_rules=[
            BadgeRule(
                condition_field="is_bot",
                condition_value=True,
                label="Bot",
                variant="info",
                icon=Icons.SMART_TOY
            ),
            BadgeRule(
                condition_field="is_verified",
                condition_value=True,
                label="Verified",
                variant="success",
                icon=Icons.VERIFIED
            ),
            BadgeRule(
                condition_field="is_scam",
                condition_value=True,
                label="Scam",
                variant="danger",
                icon=Icons.WARNING
            ),
        ],
        empty_text="None",
    ),
]

Renders as:

  • If is_bot=True and is_verified=True: Bot (blue) Verified (green)
  • If all flags are False: None (gray)
Replaces @computed_field

StatusBadgesField eliminates the need for imperative @computed_field methods with conditional badge logic. Everything is declarative!

Flexible Conditions

BadgeRule supports any field value, not just booleans. You can check string values, numbers, or any other type.

CounterBadgeField​

Display a counter value as a badge with optional link. Perfect for showing counts like messages, views, or notifications with clickable links to filtered lists.

Parameters​

class CounterBadgeField(FieldConfig):
    name: str                                    # Field name
    title: str | None = None                     # Display title
    count_field: str                             # Field containing the count
    variant: Literal["primary", "secondary", "success", "danger", "warning", "info"] = "primary"
    icon: str | None = None                      # Material icon name
    link_url_template: str | None = None         # URL with {obj.field} placeholders
    link_target: str = "_self"                   # Link target
    format_thousands: bool = True                # Format with thousands separator
    hide_on_zero: bool = False                   # Hide when count is 0
    empty_display: bool = False                  # Show dash when count is 0
    empty_text: str = "-"                        # Text for zero count

Basic Usage​

from django_cfg.modules.django_admin import CounterBadgeField, Icons

# Messages count with link
CounterBadgeField(
    name="messages_badge",
    title="Messages",
    count_field="messages_count",
    variant="primary",
    icon=Icons.MESSAGE,
    link_url_template="/admin/app/message/?user__id={obj.id}",
    hide_on_zero=True,
)

# Simple counter without link
CounterBadgeField(
    name="views",
    title="Views",
    count_field="view_count",
    variant="info",
    icon=Icons.VISIBILITY,
)

Examples​

display_fields=[
    CounterBadgeField(
        name="messages_badge",
        title="Messages",
        count_field="messages_count",
        variant="primary",
        icon=Icons.MESSAGE,
        link_url_template="/admin/telegram_spy/telegrammessage/?sender__id__exact={obj.id}",
        hide_on_zero=True,
        format_thousands=True,
    ),
]

Renders as:

  • If count is 1,234: Clickable badge showing 1,234 with message icon
  • If count is 0: Nothing (hidden due to hide_on_zero=True)
Automatic Formatting

CounterBadgeField automatically:

  • Formats large numbers with thousands separator (1,234)
  • Makes the entire badge clickable if link_url_template is provided
  • Supports template variables like {obj.id}, {obj.username}, etc.
  • Hides or shows empty state based on configuration
Replaces format_html + Badge

Previously you needed @computed_field with format_html() to wrap a badge in a link. Now it's fully declarative!

MarkdownField​

Render markdown content with beautiful styling and optional collapsible UI.

Parameters​

class MarkdownField(FieldConfig):
    name: str                              # Field name (or method name)
    title: str | None = None               # Display title
    collapsible: bool = True               # Wrap in collapsible details/summary
    default_open: bool = False             # Open by default if collapsible
    max_height: str | None = "500px"       # Max height with scrolling
    source_file: str | None = None         # Static file path (e.g., "docs/api.md")
    source_field: str | None = None        # Alternative field name for content
    enable_plugins: bool = True            # Enable mistune plugins (tables, etc.)
    header_icon: str | None = Icons.DESCRIPTION  # Material icon for header

Basic Usage​

from django_cfg.modules.django_admin import MarkdownField, Icons

# From model field (markdown string)
MarkdownField(
    name="description",
    title="Documentation",
    collapsible=True
)

# From file path field
MarkdownField(
    name="docs_path",
    title="User Guide",
    collapsible=True,
    default_open=True
)

# Static file (same for all objects)
MarkdownField(
    name="static_doc",  # method that returns file path
    title="API Documentation",
    source_file="docs/api.md",  # relative to app root
    max_height="500px"
)

# Dynamic markdown with custom title
MarkdownField(
    name="get_help_text",  # method that generates markdown
    title="Help",
    collapsible=True,
    enable_plugins=True
)

Examples​

display_fields=[
    MarkdownField(
        name="description",
        title="Documentation",
        collapsible=True,
        max_height="400px"
    ),
]

Renders as: Collapsible markdown content with syntax highlighting and styling

Use Cases

Perfect for:

  • Documentation - API docs, user guides, help text
  • Rich descriptions - Product descriptions with formatting
  • Change logs - Version history with markdown
  • Instructions - Step-by-step guides
Auto-Detection

MarkdownField automatically detects whether the content is:

  • A file path (.md extension or exists as file) → loads and renders file
  • A markdown string → renders directly

Next Steps​

Last updated on