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

User Flags


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)

Permissions


display_fields=[
    StatusBadgesField(
        name="permissions",
        title="Access",
        badge_rules=[
            BadgeRule(
                condition_field="can_edit",
                condition_value=True,
                label="Edit",
                variant="primary",
                icon=Icons.EDIT
            ),
            BadgeRule(
                condition_field="can_delete",
                condition_value=True,
                label="Delete",
                variant="danger",
                icon=Icons.DELETE
            ),
            BadgeRule(
                condition_field="can_publish",
                condition_value=True,
                label="Publish",
                variant="success",
                icon=Icons.PUBLISH
            ),
        ],
        empty_text="Read Only",
    ),
]

Feature Flags


display_fields=[
    StatusBadgesField(
        name="features",
        title="Features",
        badge_rules=[
            BadgeRule(
                condition_field="feature_ai",
                condition_value=True,
                label="AI",
                variant="warning",
                icon=Icons.PSYCHOLOGY
            ),
            BadgeRule(
                condition_field="feature_api",
                condition_value=True,
                label="API",
                variant="info",
                icon=Icons.API
            ),
            BadgeRule(
                condition_field="feature_analytics",
                condition_value=True,
                label="Analytics",
                variant="success",
                icon=Icons.ANALYTICS
            ),
        ],
    ),
]

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

Messages with Link


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)

Likes Counter


display_fields=[
    CounterBadgeField(
        name="likes",
        title="Likes",
        count_field="like_count",
        variant="danger",
        icon=Icons.FAVORITE,
        empty_display=True,  # Show "-" instead of hiding
    ),
]

Renders as:

If count is 42: Badge showing 42 with heart icon
If count is 0: Badge showing -

Error Counter


display_fields=[
    CounterBadgeField(
        name="errors",
        title="Errors",
        count_field="error_count",
        variant="danger",
        icon=Icons.ERROR,
        link_url_template="/admin/app/log/?object_id={obj.id}&level=ERROR",
        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

Simple Markdown


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

Renders as: Collapsible markdown content with syntax highlighting and styling

Static Documentation


# Add method to admin class
@computed_field("API Docs")
def api_documentation(self, obj):
    return "docs/api.md"  # Returns file path
 
# In config
display_fields=[
    MarkdownField(
        name="api_documentation",
        title="API Documentation",
        source_file="docs/api.md",
        default_open=True,
    ),
]

Renders as: Static markdown file shown for all objects

Dynamic Content


# Model method that generates markdown
class MyModel(models.Model):
    def get_help_text(self):
        return f"""
        # Help for {self.name}
 
        - **Status**: {self.status}
        - **Created**: {self.created_at}
 
        ## Actions
        - Edit settings
        - View logs
        """
 
# In config
display_fields=[
    MarkdownField(
        name="get_help_text",
        title="Help",
        collapsible=True,
        enable_plugins=True
    ),
]

Renders as: Dynamically generated markdown for each object

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

Field Types Reference - Complete field types reference
Basic Fields - Basic field types
Display Fields - Display field types