Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rahul-baberwal/django-var-cms/llms.txt

Use this file to discover all available pages before exploring further.

The list view is the primary browsing interface for any registered model. django-var-cms gives you fine-grained control over which columns appear, how sidebar filters are rendered, how full-text search queries are applied, and how rows are paginated and sorted — all through declarative class attributes on your VarCMSModelAdmin subclass.

​
list_display — Table Columns

list_display is a list of field names (or double-underscore traversal paths) that appear as columns in the list view table. If you leave it empty, django-var-cms automatically uses the first six fields returned by model._meta.get_fields(), skipping any many-to-many or reverse relation fields. 
class ArticleAdmin(VarCMSModelAdmin):
    list_display = ["title", "category", "author", "status", "is_featured", "view_count", "created_at"]

​
Special field rendering

The list view applies automatic display logic based on the underlying Django field type:

ImageField

Rendered as a thumbnail <img> tag with the CSS class preview-thumb and a data-preview attribute. Thumbnail dimensions default to 38 × 38 px and are controlled by list_image_width and list_image_height.

FileField

Rendered as a clickable icon link. The Lucide icon changes by extension: video for MP4/WebM, music for MP3/WAV, file-text for PDF, and paperclip for all other types.

BooleanField

Rendered as a green Lucide check icon for True and a red Lucide x icon for False.
Long string values (over 80 characters) are automatically truncated with an ellipsis, and the full value is accessible via the HTML title tooltip attribute. You can also traverse related model fields using the double-underscore notation: 
class ArticleAdmin(VarCMSModelAdmin):
    # Display the name of the related Category FK
    list_display = ["title", "category__name", "author", "status"]
If django.contrib.gis is installed and a field is a GIS geometry type, the list view renders the geometry type name and coordinate count (e.g., Point (1pts)).

​
list_image_width / list_image_height

Control the pixel size of image thumbnails rendered in list columns. Both default to 38. 
class MediaAssetAdmin(VarCMSModelAdmin):
    list_display      = ["title", "asset_type", "image", "file", "tags", "created_at"]
    list_image_width  = 60
    list_image_height = 60

​
list_filter — Sidebar Filters

list_filter is a list of field names for which django-var-cms will render a filter widget in the sidebar. The widget type is determined automatically by the build_filter_widgets() function in registry.py based on the field’s type:
Field typeWidget rendered
CharField / IntegerField with .choicesselect — dropdown of available choices
ForeignKey / OneToOneFieldselect — dropdown of all related objects (up to 300)
BooleanFieldboolean — yes / no / any toggle buttons
DateField / DateTimeFielddate_range — from/to date pickers
IntegerField / FloatField / DecimalFieldnumber_range — min/max numeric inputs
All other field typestext — a plain text input for substring matching
class ArticleAdmin(VarCMSModelAdmin):
    list_filter = ["status", "is_featured", "category"]
    #              ^^^^^^^^   ^^^^^^^^^^^   ^^^^^^^^
    #              choices    BooleanField  ForeignKey
    #              → select   → boolean     → select
Filter parameters are appended to the URL as query string values (e.g., ?status=published&is_featured=1). Multiple filters stack together, narrowing the queryset cumulatively.

​
search_fields — Full-Text Search

search_fields lists the fields that are searched when the user types a query in the search bar. Each listed field is queried with a case-insensitive __icontains lookup, and results matching any field are returned (OR logic). 
class ArticleAdmin(VarCMSModelAdmin):
    search_fields = ["title", "body", "author"]
With the configuration above, typing "django" would return any article where the title, body, or author contains the string “django” (case-insensitively). The search query is passed as the q query parameter in the URL.
You can search across related model fields by using double-underscore traversal:
search_fields = ["title", "category__name"]

​
ordering — Default Sort Order

ordering sets the default queryset order when no column sort is active. Use a leading - for descending order, matching Django’s standard order_by() syntax. 
class ArticleAdmin(VarCMSModelAdmin):
    ordering = ["-created_at"]        # newest first

class CategoryAdmin(VarCMSModelAdmin):
    ordering = ["name"]               # alphabetical

​
list_per_page — Pagination

list_per_page controls how many rows appear on each page of the list view. The default is 25. The paginator uses Django’s built-in Paginator class. 
class ArticleAdmin(VarCMSModelAdmin):
    list_per_page = 20   # show 20 articles per page
When list_display includes fields from related models (via FK traversal), enabling list_select_related adds a select_related() call to the queryset, eliminating N+1 database queries. 
class ArticleAdmin(VarCMSModelAdmin):
    list_display         = ["title", "category__name", "author"]
    list_select_related  = True   # JOIN category in a single query

​
Column Sorting

Every column header in the list view is clickable. Clicking a header sorts the list by that field ascending; clicking again toggles to descending. The sort state is tracked with two URL query parameters:
ParameterDescription
oThe field name to sort by (must be in list_display)
otSort direction — "asc" (default) or "desc"
Example URL after clicking the created_at column header twice: 
/var-cms/demo/article/?o=created_at&ot=desc

​
Complete Example

The following CategoryAdmin, ArticleAdmin, and MediaAssetAdmin classes from the demo app illustrate every list-view option working together: 
# demo/var_cms_admin.py
from var_cms.registry import var_cms_site, VarCMSModelAdmin
from .models import Category

class CategoryAdmin(VarCMSModelAdmin):
    # Columns in the list table
    list_display  = ["name", "slug", "is_active", "created_at"]
    #                                ^^^^^^^^^^   ^^^^^^^^^^
    #                                BooleanField → check/x icon
    #                                             DateTimeField → plain string

    # Sidebar filter widgets
    list_filter   = ["is_active"]
    #                ^^^^^^^^^^ BooleanField → yes / no / any toggle

    # Search bar (OR across all listed fields)
    search_fields = ["name", "slug", "description"]

    # Default ordering: A → Z by name
    ordering      = ["name"]

    # Mark created_at as read-only (shown in form but not editable)
    readonly_fields = ["created_at"]

    icon           = "folder"
    dashboard_card = True

var_cms_site.register(Category, CategoryAdmin)
Sorting is only available for fields that are direct model fields — not for computed properties or double-underscore traversals. The list view checks that the o parameter is present in list_display before applying the order.

Build docs developers (and LLMs) love

Get started for freeTalk to us