CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-django-filer

A file management application for Django that makes handling of files and images a breeze.

Pending
Overview
Eval results
Files

admin.mddocs/

Admin Interface

Django Filer provides a comprehensive admin interface with file browser, drag-and-drop uploads, folder navigation, and custom widgets for model fields. The admin interface is automatically registered and provides rich functionality for file management.

Capabilities

Auto-Registered Admin Classes

Django Filer automatically registers admin interfaces for all core models, providing full CRUD functionality with specialized features for file management.

class FileAdmin(admin.ModelAdmin):
    """
    Admin interface for File model with specialized file management features.
    
    Features:
    - File preview and thumbnail display
    - Drag-and-drop upload support
    - Bulk operations (move, delete, change permissions)
    - Advanced search and filtering
    - Permission checking integration
    """

class FolderAdmin(admin.ModelAdmin):
    """
    Admin interface for Folder model with hierarchical navigation.
    
    Features:
    - Tree-based folder navigation
    - Drag-and-drop folder organization
    - Permission management interface
    - Bulk folder operations
    """

class ImageAdmin(FileAdmin):
    """
    Admin interface for Image model extending FileAdmin.
    
    Additional Features:
    - Image preview with dimensions
    - EXIF data display
    - Thumbnail generation controls
    - Subject location editing
    """

class ClipboardAdmin(admin.ModelAdmin):
    """Admin interface for Clipboard model."""

class PermissionAdmin(admin.ModelAdmin):
    """Admin interface for FolderPermission model."""

class ThumbnailOptionAdmin(admin.ModelAdmin):
    """Admin interface for ThumbnailOption model."""

Custom Admin Widgets

Specialized widgets for integrating filer objects into other model admin interfaces.

class AdminFileWidget(ForeignKeyRawIdWidget):
    """
    Admin widget for file selection with popup browser.
    
    Features:
    - Popup file browser with folder navigation
    - File preview and metadata display
    - Search and filter capabilities
    - Drag-and-drop file upload in popup
    """
    
    def render(self, name, value, attrs=None, renderer=None):
        """
        Render widget HTML with file browser popup.
        
        Args:
            name (str): Field name
            value: Current field value (File ID)
            attrs (dict): HTML attributes
            renderer: Template renderer
            
        Returns:
            str: Rendered HTML with popup trigger and preview
        """
        
    def label_for_value(self, value):
        """
        Get display label for selected file.
        
        Args:
            value: File ID
            
        Returns:
            str: HTML label with file name and preview
        """
        
    def obj_for_value(self, value):
        """
        Get File object for given ID.
        
        Args:
            value: File ID
            
        Returns:
            File or None: File object if exists
        """
        
    class Media:
        """CSS and JavaScript requirements for the widget."""
        css = {
            'all': (
                'filer/css/admin_filer.css',
                # Icon CSS library
            )
        }
        js = (
            'admin/js/vendor/jquery/jquery.min.js',
            'admin/js/jquery.init.js', 
            'filer/js/libs/dropzone.min.js',
            'filer/js/addons/dropzone.init.js',
            'filer/js/addons/popup_handling.js',
            'filer/js/addons/widget.js',
        )

class AdminImageWidget(AdminFileWidget):
    """
    Admin widget for image selection extending AdminFileWidget.
    
    Additional Features:
    - Image thumbnail preview
    - Image-specific metadata display
    - Dimension information
    """

class AdminFolderWidget(ForeignKeyRawIdWidget):
    """
    Admin widget for folder selection with folder browser.
    
    Features:
    - Hierarchical folder tree popup
    - Folder creation capabilities
    - Permission-aware folder filtering
    - Breadcrumb navigation
    """
    
    def render(self, name, value, attrs=None, renderer=None):
        """
        Render widget HTML with folder browser popup.
        
        Args:
            name (str): Field name
            value: Current field value (Folder ID)
            attrs (dict): HTML attributes
            renderer: Template renderer
            
        Returns:
            str: Rendered HTML with folder browser popup
        """
        
    class Media:
        """CSS and JavaScript requirements."""
        css = {"all": ('filer/css/admin_filer.css',)}
        js = ('filer/js/addons/popup_handling.js',)

Admin Form Fields

Specialized form fields that work with the admin widgets to provide rich functionality.

class AdminFileFormField(forms.ModelChoiceField):
    """
    Form field for file selection in admin interface.
    
    Integrates with AdminFileWidget to provide:
    - File browser popup
    - Search and filtering
    - Permission-aware file selection
    """
    
    def __init__(self, rel, queryset, to_field_name, *args, **kwargs):
        """
        Initialize form field with admin widget.
        
        Args:
            rel: Field relation object
            queryset: Available files QuerySet
            to_field_name: Target field name
        """

class AdminImageFormField(AdminFileFormField):
    """Form field for image selection extending AdminFileFormField."""

class AdminFolderFormField(forms.ModelChoiceField):
    """
    Form field for folder selection in admin interface.
    
    Integrates with AdminFolderWidget to provide:
    - Folder tree popup
    - Permission-aware folder selection
    - Folder creation capabilities
    """

Directory Listing and File Browser

Core admin views providing the file browser interface used throughout the admin.

# Admin URL patterns (internal)
urlpatterns = [
    path('admin:filer-directory_listing-last', DirectoryListingView.as_view()),
    path('admin:filer-directory_listing-unfiled_images', UnfiledImagesView.as_view()), 
    path('admin:filer-directory_listing-images_with_missing_data', ImagesWithMissingDataView.as_view()),
]

class DirectoryListingView:
    """
    Main file browser view providing:
    - Folder navigation with breadcrumbs
    - File and folder listing with previews
    - Drag-and-drop upload
    - Bulk operations (move, delete, permissions)
    - Search and filtering
    - Permission checking
    """

class FilePickerView:
    """
    File selection popup view for widgets providing:
    - Modal file browser
    - File selection and confirmation
    - Upload capabilities within popup
    """

Usage Examples

Using Admin Widgets in Custom Admin

from django.contrib import admin
from filer.fields import FilerFileField, FilerImageField
from .models import Article

class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title', 'created_at', 'featured_image_preview']
    list_filter = ['created_at'] 
    search_fields = ['title', 'content']
    
    # Organize fields in fieldsets
    fieldsets = (
        ('Content', {
            'fields': ('title', 'content', 'author')
        }),
        ('Media', {
            'fields': ('featured_image', 'attachment', 'gallery_folder'),
            'classes': ('collapse',),  # Collapsible section
        }),
        ('Metadata', {
            'fields': ('created_at', 'updated_at'),
            'classes': ('collapse',),
        }),
    )
    
    readonly_fields = ['created_at', 'updated_at']
    
    def featured_image_preview(self, obj):
        """Show image preview in list view."""
        if obj.featured_image:
            return f'<img src="{obj.featured_image.icons["32"]}" alt="Preview" />'
        return "No image"
    featured_image_preview.allow_tags = True
    featured_image_preview.short_description = "Preview"

admin.site.register(Article, ArticleAdmin)

Customizing Widget Behavior

from django import forms
from filer.fields import FilerImageField
from filer.models import Image

class CustomArticleForm(forms.ModelForm):
    # Override widget for more control
    featured_image = forms.ModelChoiceField(
        queryset=Image.objects.filter(is_public=True),
        widget=AdminImageWidget(rel=FilerImageField().remote_field),
        required=False
    )
    
    class Meta:
        model = Article
        fields = '__all__'
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        
        # Customize widget attributes
        self.fields['featured_image'].widget.attrs.update({
            'class': 'custom-image-widget',
            'data-placeholder': 'Select an image...'
        })

class ArticleAdmin(admin.ModelAdmin):
    form = CustomArticleForm

Bulk Operations in File Admin

from django.contrib import admin
from filer.models import File

class CustomFileAdmin(admin.ModelAdmin):
    list_display = ['name', 'folder', 'owner', 'is_public', 'file_size']
    list_filter = ['is_public', 'folder', 'mime_type']
    search_fields = ['name', 'original_filename']
    
    # Enable bulk operations
    actions = ['make_public', 'make_private', 'move_to_folder']
    
    def make_public(self, request, queryset):
        """Bulk action to make files public."""
        updated = queryset.update(is_public=True)
        self.message_user(request, f'{updated} files made public.')
    make_public.short_description = "Make selected files public"
    
    def make_private(self, request, queryset):
        """Bulk action to make files private.""" 
        updated = queryset.update(is_public=False)
        self.message_user(request, f'{updated} files made private.')
    make_private.short_description = "Make selected files private"
    
    def move_to_folder(self, request, queryset):
        """Bulk action to move files to a folder."""
        # Custom logic for folder selection and moving
        pass
    move_to_folder.short_description = "Move selected files to folder"

# Unregister default and register custom
admin.site.unregister(File)
admin.site.register(File, CustomFileAdmin)

Custom File Upload Handling

from django.contrib import admin
from django.urls import path
from django.http import JsonResponse
from filer.models import File, Folder

class CustomFilerAdmin(admin.ModelAdmin):
    def get_urls(self):
        """Add custom upload endpoint."""
        urls = super().get_urls()
        custom_urls = [
            path('bulk-upload/', self.admin_site.admin_view(self.bulk_upload_view), 
                 name='filer_file_bulk_upload'),
        ]
        return custom_urls + urls
    
    def bulk_upload_view(self, request):
        """Custom bulk upload handler."""
        if request.method == 'POST':
            files = request.FILES.getlist('files')
            folder_id = request.POST.get('folder_id')
            
            folder = None
            if folder_id:
                folder = Folder.objects.get(pk=folder_id)
            
            uploaded_files = []
            for file in files:
                file_obj = File.objects.create(
                    file=file,
                    name=file.name,
                    folder=folder,
                    owner=request.user
                )
                uploaded_files.append({
                    'id': file_obj.id,
                    'name': file_obj.name,
                    'url': file_obj.url
                })
            
            return JsonResponse({
                'success': True,
                'files': uploaded_files
            })
        
        return JsonResponse({'success': False})

Permission-Aware Admin Views

from django.contrib import admin
from filer.models import File, Folder

class PermissionAwareFileAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        """Filter files based on user permissions."""
        qs = super().get_queryset(request)
        
        if request.user.is_superuser:
            return qs
        
        # Filter files user has read permission for
        allowed_files = []
        for file in qs:
            if file.has_read_permission(request.user):
                allowed_files.append(file.pk)
        
        return qs.filter(pk__in=allowed_files)
    
    def has_change_permission(self, request, obj=None):
        """Check edit permission for specific file."""
        if obj is None:
            return True  # Allow viewing list
        
        return obj.has_edit_permission(request.user)

class PermissionAwareFolderAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        """Filter folders based on user permissions."""
        qs = super().get_queryset(request)
        
        if request.user.is_superuser:
            return qs
        
        # Filter folders user has read permission for
        allowed_folders = []
        for folder in qs:
            if folder.has_read_permission(request.user):
                allowed_folders.append(folder.pk)
        
        return qs.filter(pk__in=allowed_folders)

Customizing File Display

from django.contrib import admin
from django.utils.html import format_html
from filer.models import File, Image

class RichFileAdmin(admin.ModelAdmin):
    list_display = [
        'file_preview', 'name', 'folder', 'size_formatted', 
        'mime_type', 'is_public', 'uploaded_at'
    ]
    
    def file_preview(self, obj):
        """Show file preview or icon."""
        if hasattr(obj, 'icons') and obj.icons:
            # For images, show thumbnail
            return format_html(
                '<img src="{}" alt="{}" style="max-width: 48px; max-height: 48px;" />',
                obj.icons.get('48', obj.icons.get('32', '')),
                obj.name
            )
        else:
            # For other files, show type icon
            return format_html(
                '<span class="filer-file-icon filer-file-icon-{}" title="{}"></span>',
                obj.extension or 'unknown',
                obj.mime_type
            )
    file_preview.short_description = "Preview"
    
    def size_formatted(self, obj):
        """Show formatted file size."""
        if obj.size:
            return f"{obj.size:,} bytes"
        return "Unknown"
    size_formatted.short_description = "Size"
    
    # Custom filter for file types
    class FileTypeFilter(admin.SimpleListFilter):
        title = 'File Type'
        parameter_name = 'file_type'
        
        def lookups(self, request, model_admin):
            return (
                ('image', 'Images'),
                ('document', 'Documents'),
                ('video', 'Videos'),
                ('audio', 'Audio'),
            )
        
        def queryset(self, request, queryset):
            if self.value() == 'image':
                return queryset.filter(mime_type__startswith='image/')
            elif self.value() == 'document':
                return queryset.filter(mime_type__in=[
                    'application/pdf', 'application/msword',
                    'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
                ])
            # Add more filter logic as needed
            return queryset
    
    list_filter = [FileTypeFilter, 'is_public', 'folder']

admin.site.register(File, RichFileAdmin)

Install with Tessl CLI

npx tessl i tessl/pypi-django-filer

docs

admin.md

configuration.md

fields.md

index.md

models.md

template-utils.md

tile.json