Registering Models with django-var-cms VarCMSModelAdmin

When var_cms starts up, it automatically iterates every entry in INSTALLED_APPS and attempts to import {app}.var_cms_admin for each app. This means you never need to manually wire up any import — simply create the file in your app directory and django-var-cms will discover and load it at startup, registering all of your models with the global var_cms_site registry.

Creating `var_cms_admin.py`

Create the file

Inside any Django app that you want to expose in the CMS, create a file named var_cms_admin.py at the root of that app:

myapp/
├── models.py
├── views.py
├── var_cms_admin.py   ← create this
└── ...

Import the registry and base class

At the top of your new file, import the global site instance and the base admin class:

# myapp/var_cms_admin.py
from var_cms.registry import var_cms_site, VarCMSModelAdmin
from .models import Article, Category

Define an admin class

Subclass VarCMSModelAdmin and declare your configuration as class attributes:

class ArticleAdmin(VarCMSModelAdmin):
    list_display  = ["title", "category", "author", "status", "created_at"]
    list_filter   = ["status", "category"]
    search_fields = ["title", "body", "author"]
    ordering      = ["-created_at"]
    icon          = "file-text"

Call var_cms_site.register() at module level, passing the model class and your admin class:

var_cms_site.register(Article, ArticleAdmin)

Class Attributes Reference

Every attribute on VarCMSModelAdmin is optional — sensible defaults are applied automatically. The table below covers all configuration options.

Attribute	Type	Default	Description
`list_display`	`list[str]`	First 6 model fields	Column names shown in the list view table
`list_filter`	`list[str]`	`[]`	Fields rendered as sidebar filter widgets
`search_fields`	`list[str]`	`[]`	Fields searched with a case-insensitive `icontains` lookup
`ordering`	`list[str]`	`[]`	Default queryset ordering (prefix `-` for descending)
`list_per_page`	`int`	`25`	Number of rows per page in the list view
`list_select_related`	`bool`	`False`	Call `select_related()` on the queryset to reduce N+1 queries
`list_image_width`	`int`	`38`	Pixel width of image thumbnails in list columns
`list_image_height`	`int`	`38`	Pixel height of image thumbnails in list columns
`readonly_fields`	`list[str]`	`[]`	Fields always displayed but never editable
`exclude_fields`	`list[str]`	`[]`	Fields hidden from the form entirely
`html_fields`	`list[str]`	`[]`	`TextField` names that get a Quill.js rich text editor
`regex_validators`	`dict[str, tuple]`	`{}`	Per-field `(pattern, message)` tuples applied client-side and server-side
`form_field_widths`	`dict[str, str]`	`{}`	Named grid-width preset per field (`"full"`, `"half"`, etc.)
`form_field_rows`	`list[list[str]]`	`[]`	Groups of fields sharing a single visual row with equal column widths
`form_field_widgets`	`dict[str, str]`	`{}`	Custom widget type per field (`"select_search"`, `"multiselect"`, etc.)
`form_widget_classes`	`dict[str, str]`	`{}`	CSS classes appended to the input/select/textarea element
`form_field_placeholders`	`dict[str, str]`	`{}`	HTML `placeholder` attribute per field
`form_field_help_texts`	`dict[str, str]`	`{}`	Help text shown beneath each field (overrides model-level help_text)
`form_field_classes`	`dict[str, str]`	`{}`	CSS classes added to the field’s wrapper `<div>`
`form_field_styles`	`dict[str, str]`	`{}`	Inline CSS styles added to the field’s wrapper `<div>`
`icon`	`str`	`""`	Lucide icon name displayed beside the model in the sidebar and dashboard
`dashboard_card`	`bool`	`False`	Whether this model appears as a card on the dashboard
`card_buttons`	`list[dict]`	`[]`	Navigation buttons on the dashboard card (see Custom Actions)
`custom_object_actions`	`list[dict]`	`[]`	Per-object action buttons on list and detail views (see Custom Actions)

The `icon` attribute

The icon value is a Lucide icon name — the same string you would use in <i data-lucide="...">. You can browse the full icon catalogue at lucide.dev. Common examples for CMS models:

class ArticleAdmin(VarCMSModelAdmin):
    icon = "file-text"      # articles / posts

class CategoryAdmin(VarCMSModelAdmin):
    icon = "folder"         # categories / folders

class MediaAssetAdmin(VarCMSModelAdmin):
    icon = "image"          # media / images

class PageAdmin(VarCMSModelAdmin):
    icon = "book-open"      # pages / documents

The `dashboard_card` attribute

By default every registered model is hidden from the dashboard (dashboard_card = False). Set it to True to show a stats card for that model on the home screen:

class InvoiceAdmin(VarCMSModelAdmin):
    dashboard_card = True    # will appear on the dashboard

class AuditLogAdmin(VarCMSModelAdmin):
    dashboard_card = False   # hidden from dashboard (default)

You can also control visibility globally from settings.py without touching individual admin classes:

# settings.py

# Hide specific model cards by app.model or model name:
VAR_CMS_HIDDEN_DASHBOARD_CARDS = ["demo.category", "logentry"]

# Show ONLY these model cards (all others are hidden):
VAR_CMS_SHOWN_DASHBOARD_CARDS  = ["article", "invoice"]

Unregistering a Model

Call var_cms_site.unregister() to remove a previously registered model. This is useful when you want to override a registration made in a third-party app:

from var_cms.registry import var_cms_site, VarCMSModelAdmin
from third_party_app.models import SomeModel

# Remove the default registration
var_cms_site.unregister(SomeModel)

# Optionally re-register with your own admin class
class MySomeModelAdmin(VarCMSModelAdmin):
    list_display = ["name", "created_at"]

var_cms_site.register(SomeModel, MySomeModelAdmin)

`save_model()` and `delete_model()` Hooks

VarCMSModelAdmin exposes two lifecycle hooks that you can override for custom save or delete behaviour.

`save_model(request, obj, form, change)`

Called whenever an object is saved (both create and update). The default implementation checks whether the model has a slug field and, if it is empty, auto-generates a slug from the first non-empty value found in title, name, or headline, then calls obj.save().

Parameter	Description
`request`	The current `HttpRequest`
`obj`	The unsaved model instance
`form`	The bound `ModelForm` instance
`change`	`True` when updating an existing record; `False` on create

class ArticleAdmin(VarCMSModelAdmin):
    def save_model(self, request, obj, form, change):
        if not change:
            # Auto-assign the current user as author on creation
            obj.author = request.user.get_username()
        super().save_model(request, obj, form, change)

`delete_model(request, obj)`

Called when an object is deleted. The default implementation calls obj.delete().

class ArticleAdmin(VarCMSModelAdmin):
    def delete_model(self, request, obj):
        # Archive instead of hard-delete
        obj.status = "archived"
        obj.save()

Complete Example

The following example is taken directly from the demo app and shows CategoryAdmin and ArticleAdmin with realistic field configurations, permissions, and lifecycle hooks.

models.py
var_cms_admin.py

# demo/models.py
from django.db import models

class Category(models.Model):
    name        = models.CharField(max_length=100)
    slug        = models.SlugField(unique=True)
    description = models.TextField(blank=True)
    is_active   = models.BooleanField(default=True)
    created_at  = models.DateTimeField(auto_now_add=True)

    class Meta:
        verbose_name = "category"
        verbose_name_plural = "categories"
        ordering = ["name"]

    def __str__(self):
        return self.name


STATUS_CHOICES = [
    ("draft",     "Draft"),
    ("published", "Published"),
    ("archived",  "Archived"),
]

class Article(models.Model):
    title       = models.CharField(max_length=255)
    slug        = models.SlugField(unique=True)
    category    = models.ForeignKey(Category, on_delete=models.SET_NULL, null=True, blank=True)
    author      = models.CharField(max_length=120)
    body        = models.TextField()
    status      = models.CharField(max_length=20, choices=STATUS_CHOICES, default="draft")
    is_featured = models.BooleanField(default=False)
    view_count  = models.PositiveIntegerField(default=0)
    rating      = models.DecimalField(max_digits=3, decimal_places=1, null=True, blank=True)
    created_at  = models.DateTimeField(auto_now_add=True)
    updated_at  = models.DateTimeField(auto_now=True)

    class Meta:
        verbose_name = "article"
        verbose_name_plural = "articles"
        ordering = ["-created_at"]

    def __str__(self):
        return self.title

# demo/var_cms_admin.py
from var_cms.registry import var_cms_site, VarCMSModelAdmin
from var_cms.permissions import RolePermission, UserPermission
from .models import Article, Category


class CategoryAdmin(VarCMSModelAdmin):
    list_display    = ["name", "slug", "is_active", "created_at"]
    list_filter     = ["is_active"]
    search_fields   = ["name", "slug", "description"]
    readonly_fields = ["created_at"]
    ordering        = ["name"]
    icon            = "folder"
    dashboard_card  = True

    # Regex validation for the slug field (client-side + server-side)
    regex_validators = {
        "slug": (r"^[a-z0-9-]+$", "Slug must consist of lowercase letters, numbers, and hyphens only.")
    }

    permissions = [
        RolePermission("superuser", add=True,  list=True, view=True, edit=True,  delete=True),
        RolePermission("editor",    add=True,  list=True, view=True, edit=True,  delete=False),
        RolePermission("viewer",    add=False, list=True, view=True, edit=False, delete=False),
    ]
    role_editable_fields = {
        "superuser": "__all__",
        "editor":    ["name", "description", "is_active"],
    }


class ArticleAdmin(VarCMSModelAdmin):
    list_display    = ["title", "category", "author", "status", "is_featured", "view_count", "created_at"]
    list_filter     = ["status", "is_featured", "category"]
    search_fields   = ["title", "body", "author"]
    readonly_fields = ["created_at", "updated_at", "view_count"]
    ordering        = ["-created_at"]
    list_per_page   = 20
    html_fields     = ["body"]   # Quill.js rich text editor
    icon            = "file-text"
    dashboard_card  = True

    card_buttons = [
        {"label": "All Articles", "action": "list"},
        {"label": "Write Draft",  "action": "add"},
    ]

    permissions = [
        RolePermission("superuser", add=True,  list=True, view=True, edit=True,  delete=True),
        RolePermission("editor",    add=True,  list=True, view=True, edit=True,  delete=False),
        RolePermission("author",    add=True,  list=True, view=True, edit=True,  delete=False),
        RolePermission("viewer",    add=False, list=True, view=True, edit=False, delete=False),
        # Per-user override — "alice" can delete even though she is in the viewer group
        UserPermission("alice",     add=True,  list=True, view=True, edit=True,  delete=True),
    ]
    role_editable_fields = {
        "superuser": "__all__",
        "editor":    ["title", "slug", "body", "status", "category", "is_featured"],
        "author":    ["title", "body", "status"],   # authors can't touch slug/category
        "*":         [],                             # all other roles: read-only
    }

    def save_model(self, request, obj, form, change):
        if not change:
            obj.author = request.user.get_username()
        super().save_model(request, obj, form, change)


var_cms_site.register(Category, CategoryAdmin)
var_cms_site.register(Article,  ArticleAdmin)

If you want every model in an app to use default settings with no customisation, you can pass VarCMSModelAdmin directly as the second argument — or omit it entirely, since None defaults to the base class:

var_cms_site.register(MySimpleModel, VarCMSModelAdmin)

Get Started

Model Registration

Permissions

Features

Integrations

Registering Models with django-var-cms VarCMSModelAdmin

Creating `var_cms_admin.py`

Class Attributes Reference

The `icon` attribute

The `dashboard_card` attribute

Unregistering a Model

`save_model()` and `delete_model()` Hooks

`save_model(request, obj, form, change)`

`delete_model(request, obj)`

Complete Example

Build docs developers (and LLMs) love

Get Started

Model Registration

Permissions

Features

Integrations

Documentation Index

​Creating var_cms_admin.py

​Class Attributes Reference

​The icon attribute

​The dashboard_card attribute

​Unregistering a Model

​save_model() and delete_model() Hooks

​save_model(request, obj, form, change)

​delete_model(request, obj)

​Complete Example

Build docs developers (and LLMs) love

Creating `var_cms_admin.py`

Class Attributes Reference

The `icon` attribute

The `dashboard_card` attribute

Unregistering a Model

`save_model()` and `delete_model()` Hooks

`save_model(request, obj, form, change)`

`delete_model(request, obj)`

Complete Example