0
# Django Filer
1

2
A comprehensive file and image management application for Django that provides advanced file handling capabilities through a user-friendly admin interface. Django Filer offers hierarchical folder organization, advanced file metadata management, polymorphic file models supporting various file types, integration with Django CMS, and thumbnail generation with customizable processors.
3

4
## Package Information
5

6
- **Package Name**: django-filer
7
- **Language**: Python
8
- **Installation**: `pip install django-filer`
9
- **Django Version**: Compatible with Django 3.2+
10
- **Python Version**: Compatible with Python 3.8+
11

12
## Core Imports
13

14
```python
15
# Model imports
16
from filer.models import File, Folder, Image
17

18
# Field imports for use in your models
19
from filer.fields import FilerFileField, FilerImageField, FilerFolderField
20
```
21

22
Template tag imports:
23

24
```django
25
{% load filer_tags %}
26
{% load filer_image_tags %}
27
```
28

29
## Basic Usage
30

31
```python
32
from django.db import models
33
from filer.fields import FilerFileField, FilerImageField
34

35
class Article(models.Model):
36
    title = models.CharField(max_length=200)
37
    content = models.TextField()
38
    
39
    # File attachment
40
    attachment = FilerFileField(
41
        null=True, 
42
        blank=True,
43
        related_name="article_attachments",
44
        on_delete=models.SET_NULL
45
    )
46
    
47
    # Featured image
48
    featured_image = FilerImageField(
49
        null=True,
50
        blank=True, 
51
        related_name="article_images",
52
        on_delete=models.SET_NULL
53
    )
54

55
# Working with files programmatically
56
from filer.models import File, Folder
57
from django.core.files.base import ContentFile
58

59
# Create a folder
60
folder = Folder.objects.create(name="My Documents")
61

62
# Upload a file
63
content = ContentFile(b"Hello, World!")
64
file_obj = File.objects.create(
65
    file=content,
66
    name="hello.txt",
67
    folder=folder
68
)
69

70
# Access file properties
71
print(file_obj.url)  # Public URL
72
print(file_obj.size)  # File size in bytes
73
print(file_obj.extension)  # File extension
74
```
75

76
## Architecture
77

78
Django Filer uses a polymorphic model hierarchy for flexible file type handling:
79

80
- **File**: Base polymorphic model for all file types with common fields and methods
81
- **BaseImage**: Abstract base extending File with image-specific functionality
82
- **Image**: Default concrete image model (swappable via FILER_IMAGE_MODEL setting)
83
- **Folder**: Hierarchical folder model for organizing files with permission system
84
- **Permission System**: Granular folder-level permissions (read, edit, add children)
85

86
The library integrates seamlessly with Django's admin interface, providing drag-and-drop upload, folder navigation, and file preview capabilities. It supports both public and private file storage through configurable storage backends.
87

88
## Capabilities
89

90
### Core Models
91

92
Django Filer's polymorphic model system for files, folders, and images with full metadata support and admin integration.
93

94
```python { .api }
95
class File(PolymorphicModel):
96
    folder = models.ForeignKey(Folder, ...)
97
    file = MultiStorageFileField(...)
98
    name = models.CharField(max_length=255, ...)
99
    owner = models.ForeignKey(settings.AUTH_USER_MODEL, ...)
100
    is_public = models.BooleanField(...)
101
    
102
    def has_read_permission(self, user): ...
103
    def has_edit_permission(self, user): ...
104
    
105
    @property
106
    def url(self): ...
107
    @property
108
    def size(self): ...
109

110
class Folder(models.Model):
111
    parent = models.ForeignKey('self', ...)
112
    name = models.CharField(max_length=255, ...)
113
    owner = models.ForeignKey(settings.AUTH_USER_MODEL, ...)
114
    
115
    def has_read_permission(self, user): ...
116
    def has_edit_permission(self, user): ...
117
    def has_add_children_permission(self, user): ...
118

119
class Image(BaseImage):
120
    date_taken = models.DateTimeField(...)
121
    author = models.CharField(max_length=255, ...)
122
    
123
    @property
124
    def width(self): ...
125
    @property
126
    def height(self): ...
127
```
128

129
[Core Models](./models.md)
130

131
### Django Form Fields
132

133
Custom Django model fields for integrating filer objects into your models with admin widgets.
134

135
```python { .api }
136
class FilerFileField(models.ForeignKey):
137
    def __init__(self, **kwargs): ...
138

139
class FilerImageField(FilerFileField):
140
    def __init__(self, **kwargs): ...
141

142
class FilerFolderField(models.ForeignKey):
143
    def __init__(self, **kwargs): ...
144
```
145

146
[Form Fields](./fields.md)
147

148
### Configuration and Settings
149

150
Comprehensive settings system for storage backends, permissions, validation, and admin interface customization.
151

152
```python { .api }
153
# Core Settings
154
FILER_IMAGE_MODEL = 'filer.Image'
155
FILER_ENABLE_PERMISSIONS = True
156
FILER_IS_PUBLIC_DEFAULT = True
157

158
# Storage Configuration
159
FILER_STORAGES = {
160
    'public': {...},
161
    'private': {...}
162
}
163

164
# Upload Settings
165
FILER_UPLOADER_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
166
FILER_MIME_TYPE_WHITELIST = ['image/jpeg', 'image/png', ...]
167
```
168

169
[Configuration](./configuration.md)
170

171
### Admin Interface and Widgets
172

173
Rich Django admin integration with file browser, drag-and-drop uploads, and custom widgets for model fields.
174

175
```python { .api }
176
class AdminFileWidget(ForeignKeyRawIdWidget):
177
    def render(self, name, value, attrs=None, renderer=None): ...
178

179
class AdminImageWidget(AdminFileWidget): ...
180

181
class AdminFolderWidget(ForeignKeyRawIdWidget):
182
    def render(self, name, value, attrs=None, renderer=None): ...
183
```
184

185
[Admin Interface](./admin.md)
186

187
### Template Tags and Utilities
188

189
Template tags for file handling, image processing, and utility functions for file operations.
190

191
```python { .api }
192
# Template filters
193
{% load filer_tags %}
194
{{ file.size|filesize }}
195

196
{% load filer_image_tags %}
197
{{ image.width|divide_x_by:2 }}
198

199
# Utility functions
200
from filer.utils.files import handle_upload, get_valid_filename
201
from filer.validation import validate_upload
202
```
203

204
[Template Tags and Utilities](./template-utils.md)