django-var-cms 1.0.5

A modern, role-based Django CMS registry with rich media previews

django-var-cms

A modern, highly customizable administrative Control Panel and CMS registry for Django projects. Built with premium glassmorphic aesthetics, role-based security, and rich media processing.

Created by Rahul Baberwal.

---

🚀 Key Features

• 🎨 Modern Design System: Responsive glassmorphic layout, collapsible navigation sidebar with localStorage persistent state, and custom HSL accent color configurations.
• 🔑 Role & User Permissions: Manage fine-grained view, list, edit, add, and delete actions matching Django Groups or specific user accounts.
• 📝 HTML Editor: Integrated Quill.js rich text editor out of the box.
• ✅ Regex Field Validation: Easily enforce custom regular expression patterns both client-side and server-side.
• 🖼️ Media Previews & Image Cropper:
  • Modal-based previews for images, video, audio, and PDFs.
  • Built-in Image Cropper (rotate, flip, custom aspect ratio crops).
  • API endpoints for media conversion (JPEG, PNG, WebP, WAV, MP3, MP4).

---

⚙️ Setup & Installation

1. Install Dependencies

Install django-var-cms along with required media dependencies:

# Using pip
pip install django-var-cms pillow whitenoise

# Using uv
uv add django-var-cms pillow whitenoise

2. Configure settings.py

Register "var_cms" in your Django INSTALLED_APPS and specify static/media paths:

# settings.py

INSTALLED_APPS = [
    # ... Django standard apps
    "var_cms",
    # "demo", (optional demo app)
]

# Media settings for handling file uploads/crops
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

# Static files settings
STATIC_URL = "/static/"
STATICFILES_DIRS = [BASE_DIR / "static"]
STATIC_ROOT = BASE_DIR / "staticfiles"

# Redirect paths for authentication
LOGIN_URL = "/var-cms/login/"
LOGIN_REDIRECT_URL = "/var-cms/"

3. Add URL Routing

Include the var_cms routes in your project's main urls.py:

# urls.py
from django.urls import path, include

urlpatterns = [
    # ... other paths
    path("var-cms/", include("var_cms.urls", namespace="var_cms")),
]

---

🧪 Seeding the Demo App (Optional)

If you are developing or exploring features in the source repository:

1. Run migrations to initialize the database:

   python manage.py migrate
   

2. Run the seed management command to generate default database models, pages, media, and test accounts:

   python manage.py seed_demo
   

3. Start the server:

   python manage.py runserver
   

4. Access the dashboard at http://127.0.0.1:8000/var-cms/.

Demo User Accounts

Username	Password	Role / Group	Permissions
admin	admin	superuser	Full unrestricted access
editor	editor	editor	Add + Edit (Cannot delete)
author	author	author	Add + Edit specific fields (Cannot delete)
viewer	viewer	viewer	List + View records only
alice	alice	viewer	Viewer permissions, with delete override

---

🛠️ Registering Models (Example)

Create a file named var_cms_admin.py in any of your Django apps. It is automatically discovered on startup.

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

# Customize branding globally
var_cms_site.site_header = "My CMS"
var_cms_site.site_sub    = "Control Center"
var_cms_site.site_url    = "https://example.com"
var_cms_site.logo_url    = "/static/var_cms/var.png"  # Custom brand logo

class ArticleAdmin(VarCMSModelAdmin):
    list_display  = ["title", "category", "author", "status", "created_at"]
    list_filter   = ["status", "category"]
    search_fields = ["title", "body", "author"]
    readonly_fields = ["created_at", "updated_at", "view_count"]
    
    # Enable Quill.js Rich Text Editor on body field
    html_fields = ["body"]
    
    # Custom icon from Lucide
    icon = "file-text"
    
    # Regex validator: client-side + server-side validation
    regex_validators = {
        "slug": (r"^[a-z0-9-]+$", "Slug must consist of lowercase letters, numbers, and hyphens only.")
    }
    
    # Define role permissions
    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),
        UserPermission("alice",     add=True,  list=True, view=True, edit=True,  delete=True),
    ]
    
    # Limit editable fields by user role
    role_editable_fields = {
        "superuser": "__all__",
        "editor":    ["title", "slug", "body", "status", "category"],
        "author":    ["title", "body", "status"],
        "*":         [],
    }

# Register the model on the custom site
var_cms_site.register(Article, ArticleAdmin)

---

🎨 Layout Customizations

You can customize the accent color scheme using HSL values on the global var_cms_site registry:

# Custom accent color (Emerald green)
var_cms_site.accent_color = "142, 72%, 45%"

---

📁 URL Structure

/var-cms/                          → Admin Dashboard
/var-cms/{app}/{model}/            → Paginated List view
/var-cms/{app}/{model}/add/        → Object Creation Form
/var-cms/{app}/{model}/{pk}/       → Object Modification Form
/var-cms/{app}/{model}/{pk}/view/  → Read-only Details view
/var-cms/{app}/{model}/{pk}/delete/→ Object Delete confirmation
/var-cms/api/media/crop/           → POST endpoint: crop image
/var-cms/api/media/convert/        → POST endpoint: convert media file type

---

📖 Detailed Integration & How To Use Guide

For detailed reference on branding customizations, optional two-factor authentication (OTP), and role-based permissions, see below:

🎨 Branding & Customization Settings

You can customize the header, subtitle, favicon, and email verification options on the global registry singleton.

Inside your var_cms_admin.py or startup setup, modify the settings on the singleton instance var_cms_site:

from var_cms.registry import var_cms_site

# ── Change Name & Subtitle ───────────────────────────────────────────────
var_cms_site.site_header = "CMS"              # Default: "VAR CMS"
var_cms_site.site_sub    = "DASHBOARD"        # Default: "CONTROL PANEL"

# ── Customize "View Site" Link ───────────────────────────────────────────
var_cms_site.site_url    = "https://myblog.com" # Default: "/"

# ── Custom Image Logo & Favicon ──────────────────────────────────────────
var_cms_site.logo_url    = "/static/var_cms/var.png"  # Serves var.png as the brand logo & tab favicon

# ── Optional OTP 2FA Verification ────────────────────────────────────────
var_cms_site.enable_otp  = True               # Requires SMTP settings. Sends 6-digit OTP code to email.

🔑 Authentication & Password Tools

1. Custom Glassmorphic Login

• A premium, modern dark login interface is provided out-of-the-box at /var-cms/login/.

2. Optional OTP Verification (2FA)

• When enable_otp = True, successful user logins redirect to an OTP verification view.
• The system sends a 6-digit code to the user's email.
• Development Tip: If SMTP parameters are not configured in settings.py, the code prints directly to your terminal console as [VAR CMS OTP]: ****** to prevent developers from getting locked out.

3. Forgot Password Request

• Includes a "Forgot Password" link on the login screen. It prompts users to enter their email or username, generates a password reset OTP, and allows defining a new password securely.

4. Logged-in Password Reset

• Users can change their password directly inside the dashboard. Click the User profile badge -> select Reset Password. It renders a custom password modification form embedded within the base CMS template.

---

👥 Credits & Authors

Created and maintained by Rahul Baberwal — rahulbaberwal.com.