Display Field Types

from django_cfg.modules.django_admin import AvatarField
 
# Basic avatar - IMPORTANT: name must be a real model field!
AvatarField(
    name="first_name",  # Real model field, not virtual
    photo_field="photo_file",
    name_field="display_name",
    initials_field="first_name",
)
 
# Avatar with subtitle
AvatarField(
    name="username",  # Real model field
    photo_field="avatar",
    name_field="full_name",
    initials_field="username",
    subtitle_field="email",
    show_as_card=True,
)
 
# Avatar with custom sizing and variant mapping
AvatarField(
    name="first_name",  # Real model field
    photo_field="profile_picture",
    name_field="name",
    initials_field="first_name",
    avatar_size=48,
    variant_field="user_type",
    variant_map={
        "admin": "success",
        "user": "secondary",
        "bot": "info",
    },
)

display_fields=[
    AvatarField(
        name="username",  # Real model field
        photo_field="photo",
        name_field="username",
        initials_field="first_name",
    ),
]

display_fields=[
    AvatarField(
        name="first_name",  # Real model field
        photo_field="avatar",
        name_field="full_name",
        initials_field="first_name",
        subtitle_field="email",
        show_as_card=True,
        avatar_size=48,
    ),
]

display_fields=[
    AvatarField(
        name="username",  # Real model field
        photo_field="photo",
        name_field="name",
        initials_field="username",
        variant_field="role",
        variant_map={
            "admin": "success",
            "moderator": "primary",
            "user": "secondary",
            "bot": "info",
        },
        default_variant="secondary",
    ),
]

from django_cfg.modules.django_admin import UserField
 
# Simple user display
UserField(
    name="author",
    title="Author",
    ordering="author__username",
)
 
# User with avatar header
UserField(
    name="owner",
    title="Owner",
    header=True,
    ordering="owner__username",
)

display_fields=[
    UserField(
        name="author",
        title="Author",
        ordering="author__username",
    ),
]

display_fields=[
    UserField(
        name="owner",
        title="Owner",
        header=True,
        ordering="owner__username",
    ),
]

display_fields=[
    UserField(name="created_by", title="Created By", header=True),
    UserField(name="assigned_to", title="Assigned To"),
    UserField(name="approved_by", title="Approved By"),
]

from django_cfg.modules.django_admin import ForeignKeyField, Icons
 
# Basic FK display
ForeignKeyField(
    name="machine",
    display_field="name",
)
 
# FK with custom link field
ForeignKeyField(
    name="workspace",
    link_field="id",
    display_field="name",
)
 
# FK with admin link and icon
ForeignKeyField(
    name="category",
    display_field="name",
    link_to_admin=True,
    link_icon=Icons.OPEN_IN_NEW,
)
 
# FK with subtitle (single field)
ForeignKeyField(
    name="machine",
    display_field="name",
    subtitle_field="hostname",
    link_to_admin=True,
)
 
# FK with subtitle template
ForeignKeyField(
    name="workspace",
    display_field="name",
    subtitle_template="{description} • {member_count} members",
)

display_fields=[
    ForeignKeyField(
        name="machine",
        display_field="name",
        title="Machine",
    ),
]

display_fields=[
    ForeignKeyField(
        name="machine",
        display_field="name",
        subtitle_field="hostname",
        title="Machine",
        ordering="machine__name",
    ),
]

Machine Name ↗
machine.example.com

display_fields=[
    ForeignKeyField(
        name="workspace",
        display_field="name",
        subtitle_fields=["description", "member_count"],
        subtitle_separator=" • ",
        title="Workspace",
    ),
]

My Workspace ↗
Team workspace • 5 members

display_fields=[
    ForeignKeyField(
        name="workspace",
        display_field="name",
        subtitle_template="{description} • {member_count} members",
        title="Workspace",
    ),
]

Development Team ↗
Development workspace • 12 members

from django_cfg.modules.django_admin import Icons
 
display_fields=[
    ForeignKeyField(
        name="user",
        display_field="username",
        subtitle_field="email",
        link_to_admin=True,
        link_icon=Icons.OPEN_IN_NEW,
        title="User",
    ),
]

john_doe 🔗
[email protected]

display_fields=[
    ForeignKeyField(
        name="category",
        display_field="name",
        link_to_admin=False,  # No link
        title="Category",
    ),
]

# Option 1: Single field
ForeignKeyField(
    name="machine",
    display_field="name",
    subtitle_field="hostname",  # Shows hostname below name
)
 
# Option 2: Multiple fields with separator
ForeignKeyField(
    name="workspace",
    display_field="name",
    subtitle_fields=["description", "member_count"],
    subtitle_separator=" • ",  # Joins with " • "
)
 
# Option 3: Template with placeholders
ForeignKeyField(
    name="workspace",
    display_field="name",
    subtitle_template="{description} • {member_count} members",
)

from django_cfg.modules.django_admin import (
    AdminConfig,
    ForeignKeyField,
    BadgeField,
    DateTimeField,
    Icons,
)
 
session_config = AdminConfig(
    model=Session,
 
    # Optimize queries
    select_related=["machine", "workspace", "user"],
 
    list_display=["id", "machine", "workspace", "status", "created_at"],
 
    display_fields=[
        ForeignKeyField(
            name="machine",
            display_field="name",
            subtitle_field="hostname",
            link_to_admin=True,
            link_icon=Icons.COMPUTER,
            title="Machine",
            ordering="machine__name",
        ),
        ForeignKeyField(
            name="workspace",
            display_field="name",
            subtitle_template="{description} • {member_count} members",
            link_to_admin=True,
            title="Workspace",
        ),
        BadgeField(name="status", label_map={...}),
        DateTimeField(name="created_at", show_relative=True),
    ],
)

from django_cfg.modules.django_admin import LinkField, Icons
 
# Basic link
LinkField(
    name="username",
    title="Username",
    link_field="profile_url",
)
 
# Link with icon
LinkField(
    name="display_name",
    title="User",
    link_field="telegram_link",
    link_icon=Icons.OPEN_IN_NEW,
)
 
# Link with subtitle from single field
LinkField(
    name="title",
    title="Article",
    link_field="url",
    link_icon=Icons.ARTICLE,
    subtitle_field="author",
)
 
# Link with subtitle from multiple fields
LinkField(
    name="display_name",
    title="User Info",
    link_field="telegram_link",
    link_icon=Icons.OPEN_IN_NEW,
    subtitle_fields=["full_name", "phone"],
    ordering="username",
)

display_fields=[
    LinkField(
        name="website_url",
        title="Website",
        link_field="website_url",  # Can link to itself
        link_icon=Icons.OPEN_IN_NEW,
    ),
]

https://example.com 🔗

# Real-world example: Telegram user with link
# NOTE: display_name is a @property, use a real model field instead!
display_fields=[
    LinkField(
        name="username",  # Real model field
        title="User Info",
        link_field="telegram_link",
        link_icon=Icons.OPEN_IN_NEW,
        subtitle_fields=["full_name", "phone"],
        subtitle_separator=" • ",
        ordering="username",
    ),
]

@username 🔗
John Doe • +1234567890

display_fields=[
    LinkField(
        name="channel_title",
        title="Channel",
        link_field="channel_url",
        link_icon=Icons.OPEN_IN_NEW,
        subtitle_template="ID: {channel_id} • Subscribers: {subscriber_count}",
    ),
]

My Channel 🔗
ID: 123456 • Subscribers: 1,234

# Option 1: Single field
LinkField(
    name="username",
    link_field="profile_url",
    subtitle_field="email",  # Shows email below username
)
 
# Option 2: Multiple fields with separator
LinkField(
    name="display_name",
    link_field="telegram_link",
    subtitle_fields=["full_name", "phone", "email"],
    subtitle_separator=" • ",  # Joins with " • "
)
 
# Option 3: Template with placeholders
LinkField(
    name="product_name",
    link_field="product_url",
    subtitle_template="Price: ${price} | Stock: {stock_count}",
)

from django_cfg.modules.django_admin import AdminConfig, LinkField, Icons
 
telegram_user_config = AdminConfig(
    model=TelegramUser,
 
    list_display=["first_name", "username", "status_badges", "messages_badge"],
 
    display_fields=[
        LinkField(
            name="username",  # Real model field
            title="User Info",
            link_field="telegram_link",
            link_icon=Icons.OPEN_IN_NEW,
            subtitle_fields=["full_name", "phone"],
            ordering="username",
        ),
    ],
)

from django_cfg.modules.django_admin import ImageField
 
# Simple image
ImageField(
    name="photo_url",
    title="Photo",
    max_width="200px",
)
 
# Image with static caption
ImageField(
    name="thumbnail",
    title="Thumbnail",
    max_width="100px",
    caption="Product Image",
)
 
# Image with caption from field
ImageField(
    name="avatar_url",
    title="Avatar",
    width="50px",
    height="50px",
    border_radius="50%",
    caption_field="username",
)

# QR code with template caption
display_fields=[
    ImageField(
        name="get_qr_code_url",  # Can be a method
        title="QR Code",
        max_width="200px",
        caption_template="Scan to pay: <code>{pay_address}</code>",
    ),
]

<img src="https://api.qrserver.com/..." alt="Image" style="max-width: 200px;">
<br><small>Scan to pay: <code>0x1234...5678</code></small>

# Circular avatar with username
display_fields=[
    ImageField(
        name="profile_picture",
        title="Avatar",
        width="50px",
        height="50px",
        border_radius="50%",
        caption_field="full_name",
    ),
]

<img src="/media/avatars/john.jpg" alt="Image"
     style="width: 50px; height: 50px; border-radius: 50%;">
<br><small>John Doe</small>

# Product photo with multiple fields in caption
display_fields=[
    ImageField(
        name="image_url",
        title="Product",
        max_width="150px",
        max_height="150px",
        caption_template="{name} - ${price}",
    ),
]

<img src="/media/products/laptop.jpg" alt="Image"
     style="max-width: 150px; max-height: 150px;">
<br><small>Laptop Pro - $1299</small>

class Payment(models.Model):
    pay_address = models.CharField(max_length=100)
 
    def get_qr_code_url(self, size=200):
        """Generate QR code URL dynamically."""
        from urllib.parse import quote
        data = quote(self.pay_address)
        return f"https://api.qrserver.com/v1/create-qr-code/?size={size}x{size}&data={data}"
 
# Use method in ImageField
ImageField(
    name="get_qr_code_url",  # Method will be called automatically
    title="Payment QR",
    max_width="200px",
    caption_template="Address: <code>{pay_address}</code>",
)

# Single field
caption_template="Scan: {address}"
 
# Multiple fields
caption_template="User: {username} | ID: {user_id}"
 
# With HTML
caption_template="Pay to: <code>{wallet_address}</code>"

# Fixed size
ImageField(width="100px", height="100px")
 
# Maximum constraints
ImageField(max_width="300px", max_height="200px")
 
# Circular/rounded
ImageField(border_radius="50%")    # Circle
ImageField(border_radius="8px")    # Rounded corners
 
# Combined
ImageField(
    width="80px",
    height="80px",
    border_radius="50%",
    max_width="100px",
)

from django_cfg.modules.django_admin import ImagePreviewField
 
# Simple preview for ImageField
ImagePreviewField(
    name="photo",
    title="Photo",
    thumbnail_max_width=150,
)
 
# Smaller thumbnails
ImagePreviewField(
    name="thumbnail",
    title="Preview",
    thumbnail_max_width=100,
    thumbnail_max_height=100,
)
 
# Circular preview (avatar style)
ImagePreviewField(
    name="avatar",
    title="Avatar",
    thumbnail_max_width=80,
    thumbnail_max_height=80,
    border_radius=40,  # Half of width for circle
)

# Preview only for images, show badge for other files
ImagePreviewField(
    name="file",
    title="Media",
    url_method="get_download_url",  # Use method to get URL
    condition_field="is_image",      # Only show preview if is_image=True
    fallback_text="Not an image",    # Badge text for non-images
)
 
# Preview only for specific media types
ImagePreviewField(
    name="media_file",
    title="Preview",
    condition_field="media_type",
    condition_value="photo",         # Only for photos
    fallback_text="No preview",
)
 
# Preview for multiple types (list of values)
ImagePreviewField(
    name="result_url",
    title="Result",
    condition_field="task_type",
    condition_value=["image", "portrait", "composite"],  # All image-based types
    fallback_text="—",
)

display_fields=[
    ImagePreviewField(
        name="photo",
        title="Photo",
        thumbnail_max_width=150,
        thumbnail_max_height=150,
    ),
]

# TelegramMedia admin - preview only for images
display_fields=[
    ImagePreviewField(
        name="file",
        title="Preview",
        thumbnail_max_width=100,
        thumbnail_max_height=100,
        url_method="get_download_url",
        condition_field="is_image",
        fallback_text="Not image",
    ),
]

display_fields=[
    ImagePreviewField(
        name="product_image",
        title="Product",
        thumbnail_max_width=200,
        caption_field="product_name",
    ),
]

config = AdminConfig(
    model=Product,
    readonly_fields=["id", "photo", "created_at"],  # photo gets auto-preview!
    fieldsets=[
        FieldsetConfig(
            title="Media",
            fields=["photo"],  # Will show clickable preview with modal
        ),
    ],
)

# 1. Direct ImageField/FileField
ImagePreviewField(name="photo")  # Uses photo.url
 
# 2. URL CharField
ImagePreviewField(name="image_url")  # Uses field value directly
 
# 3. Model method
ImagePreviewField(
    name="file",
    url_method="get_download_url",  # Calls obj.get_download_url()
)
 
# 4. Property
ImagePreviewField(name="thumbnail_url")  # Uses @property value

from django_cfg.modules.django_admin import (
    AdminConfig,
    ImagePreviewField,
    ShortUUIDField,
    BadgeField,
    DateTimeField,
)
 
telegram_media_config = AdminConfig(
    model=TelegramMedia,
 
    list_display=["id", "file", "media_type", "storage_status", "created_at"],
 
    display_fields=[
        ShortUUIDField(name="id"),
        ImagePreviewField(
            name="file",
            title="Preview",
            thumbnail_max_width=100,
            thumbnail_max_height=100,
            url_method="get_download_url",
            condition_field="is_image",
            fallback_text="Not image",
        ),
        BadgeField(name="media_type", label_map={...}),
        DateTimeField(name="created_at", show_relative=True),
    ],
 
    readonly_fields=["id", "file", "created_at"],  # file gets auto-preview in fieldsets!
)

# Small thumbnails for list view
ImagePreviewField(
    thumbnail_max_width=80,
    thumbnail_max_height=80,
    border_radius=4,
)
 
# Larger preview
ImagePreviewField(
    thumbnail_max_width=200,
    thumbnail_max_height=150,
    border_radius=8,
)
 
# Circular (avatar style)
ImagePreviewField(
    thumbnail_max_width=60,
    thumbnail_max_height=60,
    border_radius=30,  # Half for circle
)

from django_cfg.modules.django_admin import ImagePreviewDisplay, computed_field
 
@computed_field("Preview")
def custom_preview(self, obj):
    if not obj.is_image:
        return self.html.badge("No preview", variant="secondary")
 
    return ImagePreviewDisplay.render(
        obj.get_download_url(),
        config={'thumbnail_max_width': '100px', 'thumbnail_max_height': '100px'}
    )

from django_cfg.modules.django_admin import VideoField
 
# Simple video thumbnail
VideoField(name="video_url")
 
# Custom size
VideoField(
    name="promo_video",
    thumbnail_width=320,
    thumbnail_height=180,
)
 
# Inline player (embedded)
VideoField(
    name="tutorial_video",
    show_inline=True,
)

display_fields=[
    VideoField(
        name="youtube_url",
        title="Video",
        thumbnail_width=200,
    ),
]

from django_cfg.modules.django_admin import VideoDisplay, computed_field
 
@computed_field("Media")
def media_preview(self, obj):
    if obj.media_type == 'video':
        return VideoDisplay.render(obj.media_url)
    return self.html.badge("Not video", variant="secondary")

from django_cfg.modules.django_admin import (
    AdminConfig,
    AvatarField,
    BadgeField,
    CurrencyField,
    DateTimeField,
    Icons,
    LinkField,
    UserField,
)
 
config = AdminConfig(
    model=Order,
    select_related=["user", "product"],
 
    list_display=["order_number", "user", "product", "total", "status", "created_at"],
 
    display_fields=[
        AvatarField(
            name="user",  # In this case, user is a ForeignKey field, which is valid
            title="Customer",
            photo_field="profile_picture",
            name_field="username",
            initials_field="first_name",
            subtitle_field="email",
            show_as_card=True,
            ordering="user__username",
        ),
        UserField(
            name="assigned_to",
            title="Assigned To",
            header=True,
            ordering="assigned_to__username",
        ),
        LinkField(
            name="product_name",
            title="Product",
            link_field="product_url",
            link_icon=Icons.OPEN_IN_NEW,
            subtitle_template="SKU: {product_sku}",
        ),
        BadgeField(
            name="status",
            title="Status",
            label_map={
                "pending": "warning",
                "shipped": "primary",
                "delivered": "success",
            },
            icon=Icons.SHOPPING_CART,
        ),
    ],
)

# ✅ Good - Real model field
AvatarField(
    name="first_name",  # CharField in model
    photo_field="photo",
    name_field="display_name",  # Can be @property
    initials_field="first_name",
)
 
# ❌ Bad - Virtual field
AvatarField(
    name="user_avatar",  # Doesn't exist in model
    ...
)

# ✅ Good - Include ForeignKey relations
config = AdminConfig(
    model=Order,
    select_related=["user", "assigned_to"],  # Important!
    display_fields=[
        UserField(name="user", header=True),
        UserField(name="assigned_to"),
    ],
)

# ✅ Good - External links open in new tab
LinkField(
    name="website",
    link_field="url",
    link_target="_blank",  # Default
)
 
# ✅ Good - Internal links stay in same tab
LinkField(
    name="related_order",
    link_field="order_admin_url",
    link_target="_self",
)

# For user listings - use AvatarField
AvatarField(
    name="username",
    photo_field="photo",
    name_field="full_name",
    initials_field="first_name",
    show_as_card=True,  # Rich display
)
 
# For ForeignKey relations - use UserField
UserField(
    name="author",  # ForeignKey to User
    header=True,  # Show avatar
)

# ✅ Good - Informative captions
ImageField(
    name="qr_code",
    caption_template="Scan to pay: <code>{address}</code>",
)
 
# ✅ Good - Field-based captions
ImageField(
    name="photo",
    caption_field="description",
)
 
# ⚠️ OK - Static captions
ImageField(
    name="thumbnail",
    caption="Product Image",
)