Django FileBrowser Documentation

Release 3.5.3

Patrick Kranzlmueller

January 28, 2014

 Contents

1 Installation and Setup 3

1.1 Quick start guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 API 11
2.1 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 Fields & Widgets 19

3.1 Fields & Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4 Admin Interface 23
4.1 Admin Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5 Image Versions 29
5.1 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6 Help 33
6.1 Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7 Main Features 39

8 Code 41

9 Discussion 43

10 Versions and Compatibility 45

i
ii
 Django FileBrowser Documentation, Release 3.5.3

Media-Management with Grappelli.

Note: FileBrowser 3.5.3 requires Django 1.4 or 1.5 or 1.6 and Grappelli 2.4 or 2.5.

Contents 1
Django FileBrowser Documentation, Release 3.5.3

2 Contents
 CHAPTER 1

Installation and Setup

1.1 Quick start guide

For using the FileBrowser, Django needs to be installed and an Admin Site has to be activated.

1.1.1 Requirements

• Django 1.4/1.5/1.6, http://www.djangoproject.com

• Grappelli 2.4/2.5, https://github.com/sehmaschine/django-grappelli
• Pillow, https://github.com/python-imaging/Pillow

1.1.2 Installation

Install the FileBrowser:

pip install django-filebrowser

Add the filebrowser to your INSTALLED_APPS (before django.contrib.admin):

INSTALLED_APPS = (
’grappelli’,
’filebrowser’,
’django.contrib.admin’,
)

Add the FileBrowser site to your url-patterns (before any admin-urls):

from filebrowser.sites import site

urlpatterns = patterns(’’,
(r’^admin/filebrowser/’, include(site.urls)),
(r’^grappelli/’, include(’grappelli.urls’)),
(r’^admin/’, include(admin.site.urls)),
)

Collect the static files (please refer to the Staticfiles Documentation for more information):
python manage.py collectstatic

3
Django FileBrowser Documentation, Release 3.5.3

1.1.3 Settings

Check the Settings.

Note: You need to add a folder “uploads” within site.storage.location when using the default settings.
And we strongly recommend to define a VERSIONS_BASEDIR.

1.1.4 Testing

Run the FileBrowser tests:

python manage.py test filebrowser

Warning: Please note that the tests will copy files to your filesystem.

Start the devserver and login to your admin site:

python manage.py runserver <IP-address>:8000

Goto /admin/filebrowser/browse/ and check if everything looks/works as expected. If you’re having problems, see
Troubleshooting.

1.2 Settings

There are some settings in order to customize the FileBrowser. Nonetheless, you should be able to start with the default
settings.
All settings can be defined in your projects settings-file. In that case, you have to use the prefix FILEBROWSER_ for
every setting (e.g. FILEBROWSER_EXTENSIONS instead of EXTENSIONS).

1.2.1 Main URL/Paths Settings

MEDIA_ROOT

Warning: Will be removed with version 3.6.0. Since 3.4, MEDIA_ROOT is defined with your storage engine.

The absolute path to the directory that holds the media-files you want to browse:
MEDIA_ROOT = getattr(settings, "FILEBROWSER_MEDIA_ROOT", settings.MEDIA_ROOT)

MEDIA_URL

Warning: Will be removed with version 3.6.0. Since 3.4, MEDIA_URL is defined with your storage engine.

URL that handles the media served from MEDIA_ROOT:

MEDIA_URL = getattr(settings, "FILEBROWSER_MEDIA_URL", settings.MEDIA_URL)

4 Chapter 1. Installation and Setup

 Django FileBrowser Documentation, Release 3.5.3

DIRECTORY (relative to storage location)

Main FileBrowser Directory. Leave empty in order to browse all files and folders within a storage location:
DIRECTORY = getattr(settings, "FILEBROWSER_DIRECTORY", ’uploads/’)

You can override this setting on a per–site basis:

from filebrowser.sites import site
site.directory = "uploads/"

1.2.2 FileBrowser Media, TinyMCE Media

Deprecated since version 3.5.3: Use staticfiles instead.

1.2.3 Extensions and Formats

EXTENSIONS

Allowed extensions for file upload:

EXTENSIONS = getattr(settings, "FILEBROWSER_EXTENSIONS", {
’Folder’: [’’],
’Image’: [’.jpg’,’.jpeg’,’.gif’,’.png’,’.tif’,’.tiff’],
’Document’: [’.pdf’,’.doc’,’.rtf’,’.txt’,’.xls’,’.csv’],
’Video’: [’.mov’,’.wmv’,’.mpeg’,’.mpg’,’.avi’,’.rm’],
’Audio’: [’.mp3’,’.mp4’,’.wav’,’.aiff’,’.midi’,’.m4p’]
})

SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser:

SELECT_FORMATS = getattr(settings, "FILEBROWSER_SELECT_FORMATS", {
’file’: [’Folder’,’Image’,’Document’,’Video’,’Audio’],
’image’: [’Image’],
’document’: [’Document’],
’media’: [’Video’,’Audio’],
})

When using the browse-function for selecting Files/Folders, you can use an additional query-attribute type in order
to restrict the choices.

1.2.4 Versions

VERSIONS_BASEDIR (relative to storage location)

Changed in version 3.4.0.

Directory to save image versions (and thumbnails). If no directory is given, versions are stored at the same location as
the original image:

1.2. Settings 5
Django FileBrowser Documentation, Release 3.5.3

VERSIONS_BASEDIR = getattr(settings, ’FILEBROWSER_VERSIONS_BASEDIR’, ’’)

We do recommend the following structure for media files:

-- media # site.storage.location (e.g. MEDIA_ROOT)
-- _versions # VERSIONS_BASEDIR (outside of site.directory)
-- uploads # site.directory

Warning: If VERSIONS_BASEDIR is within site.directory it will be browsed.

Warning: With the next major release (3.6.0), the default setting will be “_versions”.

VERSIONS

Define the versions according to your websites grid:

VERSIONS = getattr(settings, "FILEBROWSER_VERSIONS", {
’admin_thumbnail’: {’verbose_name’: ’Admin Thumbnail’, ’width’: 60, ’height’: 60, ’opts’: ’crop’}
’thumbnail’: {’verbose_name’: ’Thumbnail (1 col)’, ’width’: 60, ’height’: 60, ’opts’: ’crop’},
’small’: {’verbose_name’: ’Small (2 col)’, ’width’: 140, ’height’: ’’, ’opts’: ’’},
’medium’: {’verbose_name’: ’Medium (4col )’, ’width’: 300, ’height’: ’’, ’opts’: ’’},
’big’: {’verbose_name’: ’Big (6 col)’, ’width’: 460, ’height’: ’’, ’opts’: ’’},
’large’: {’verbose_name’: ’Large (8 col)’, ’width’: 680, ’height’: ’’, ’opts’: ’’},
})

VERSION_QUALITY

Quality of saved versions:

VERSION_QUALITY = getattr(settings, ’FILEBROWSER_VERSION_QUALITY’, 90)

ADMIN_VERSIONS

The versions you want to show with the admin interface:

ADMIN_VERSIONS = getattr(settings, ’FILEBROWSER_ADMIN_VERSIONS’, [’thumbnail’, ’small’, ’medium’, ’bi

ADMIN_THUMBNAIL

The version being used as the admin thumbnail:

ADMIN_THUMBNAIL = getattr(settings, ’FILEBROWSER_ADMIN_THUMBNAIL’, ’admin_thumbnail’)

1.2.5 Placeholder

With your locale environment, you don’t necessarily have access to all media files (e.g. images uploaded by your
client). Therefore, you can use a PLACEHOLDER.

6 Chapter 1. Installation and Setup

 Django FileBrowser Documentation, Release 3.5.3

PLACEHOLDER

Path to placeholder image (relative to storage location):

PLACEHOLDER = getattr(settings, "FILEBROWSER_PLACEHOLDER", "")

SHOW_PLACEHOLDER

Show placeholder (instead of a version) if the original image does not exist:
SHOW_PLACEHOLDER = getattr(settings, "FILEBROWSER_SHOW_PLACEHOLDER", False)

FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists):

FORCE_PLACEHOLDER = getattr(settings, "FILEBROWSER_FORCE_PLACEHOLDER", False)

1.2.6 Extra Settings

SAVE_FULL_URL

Deprecated since version 3.4.0: With custom storage engines, saving the full URL doesn’t make sense anymore.
Moreover, removing this settings allows for easily replacing a FileBrowseField with Djangos File- or ImageField.

STRICT_PIL

If set to True, the FileBrowser will not try to import a mis-installed PIL:
STRICT_PIL = getattr(settings, ’FILEBROWSER_STRICT_PIL’, False)

IMAGE_MAXBLOCK

see http://mail.python.org/pipermail/image-sig/1999-August/000816.html:
IMAGE_MAXBLOCK = getattr(settings, ’FILEBROWSER_IMAGE_MAXBLOCK’, 1024*1024)

EXCLUDE

Exclude-patterns for files you don’t want to show:

EXTENSION_LIST = []
for exts in EXTENSIONS.values():
EXTENSION_LIST += exts
EXCLUDE = getattr(settings, ’FILEBROWSER_EXCLUDE’, (r’_(%(exts)s)_.*_q\d{1,3}\.(%(exts)s)’ % {’exts’:

1.2. Settings 7
Django FileBrowser Documentation, Release 3.5.3

MAX_UPLOAD_SIZE

Max. Upload Size in Bytes:

MAX_UPLOAD_SIZE = getattr(settings, "FILEBROWSER_MAX_UPLOAD_SIZE", 10485760)

NORMALIZE_FILENAME

True if you want to normalize filename on upload and remove all non-alphanumeric characters (except for under-
scores, spaces & dashes):
NORMALIZE_FILENAME = getattr(settings, "FILEBROWSER_NORMALIZE_FILENAME", False)

CONVERT_FILENAME

True if you want to convert the filename on upload (replace spaces and convert to lowercase):
CONVERT_FILENAME = getattr(settings, "FILEBROWSER_CONVERT_FILENAME", True)

LIST_PER_PAGE

How many items appear on each paginated list:

LIST_PER_PAGE = getattr(settings, "FILEBROWSER_LIST_PER_PAGE", 50)

DEFAULT_SORTING_BY

Default sorting attribute:

DEFAULT_SORTING_BY = getattr(settings, "FILEBROWSER_DEFAULT_SORTING_BY", "date")

Options are: date, filesize, filename_lower, filetype_checked

DEFAULT_SORTING_ORDER

Default sorting order:

DEFAULT_SORTING_ORDER = getattr(settings, "FILEBROWSER_DEFAULT_SORTING_ORDER", "desc")

Options are: asc or desc

FOLDER_REGEX

regex to clean directory names before creation:

FOLDER_REGEX = getattr(settings, "FILEBROWSER_FOLDER_REGEX", r’^[\w._\ /-]+$’)

8 Chapter 1. Installation and Setup

 Django FileBrowser Documentation, Release 3.5.3

SEARCH_TRAVERSE

True if you want to traverse all subdirectories when searching. Please note that with thousands of files/directories,
this might take a while:
SEARCH_TRAVERSE = getattr(settings, "FILEBROWSER_SEARCH_TRAVERSE", False)

DEFAULT_PERMISSIONS

Default upload and version permissions:

DEFAULT_PERMISSIONS = getattr(settings, "FILEBROWSER_DEFAULT_PERMISSIONS", 0755)

OVERWRITE_EXISTING

New in version 3.5.1.

True in order to overwrite existing files. False to use the behaviour of the storage engine:
OVERWRITE_EXISTING = getattr(settings, "FILEBROWSER_OVERWRITE_EXISTING", True)

1.2. Settings 9
Django FileBrowser Documentation, Release 3.5.3

10 Chapter 1. Installation and Setup

 CHAPTER 2

API

2.1 API

2.1.1 FileListing

class FileListing(path, filter_func=None, sorting_by=None, sorting_order=None)

Returns a list of FileObjects for a server path, see FileObject.
Parameters
• path – Relative path to a location within site.storage.location.
• filter_func – Filter function, see example below.
• sorting_by – Sort the files by any attribute of FileObject.
• sorting_order – Sorting order, either “asc” or “desc”.
If you want to list all files within a storage location you do:
from filebrowser.sites import site
from filebrowser.base import FileListing
filelisting = FileListing(site.storage.location, sorting_by=’date’, sorting_order=’desc’)

Use a custom filter function to limit the list of files:

def filter_filelisting(item):
# item is a FileObject
return item.filetype != "Folder"

filelisting = FileListing(site.storage.location, filter_func=filter_listing, sorting_by=’date’, sorti

Methods

For the below examples, we’re using this folder-structure.:

/media/uploads/testfolder/testimage.jpg
/media/uploads/blog/1/images/blogimage.jpg

Note: We defined filter_browse as filter_func (see sites.py). And we did not define a
VERSIONS_BASEDIR for this demonstration, though it is highly recommended to use one.

11
Django FileBrowser Documentation, Release 3.5.3

listing()
Returns all items for the given path with os.listdir(path):
>>> for item in filelisting.listing():
... print item
blog
testfolder

walk()
Returns all items for the given path with os.walk(path):
>>> for item in filelisting.walk():
... print item
blog
blog/1
blog/1/images
blog/1/images/blogimage.jpg
blog/1/images/blogimage_admin_thumbnail.jpg
blog/1/images/blogimage_medium.jpg
blog/1/images/blogimage_small.jpg
blog/1/images/blogimage_thumbnail.jpg
testfolder
testfolder/testimage.jpg

files_listing_total()
Returns a sorted list of FileObjects for listing():
>>> for item in filelisting.files_listing_total():
... print item
uploads/blog/
uploads/testfolder/

files_walk_total()
Returns a sorted list of FileObjects for walk():
>>> for item in filelisting.files_walk_total():
... print item
uploads/blog/
uploads/blog/1/
uploads/blog/1/images/
uploads/blog/1/images/blogimage.jpg
uploads/blog/1/images/blogimage_admin_thumbnail.jpg
uploads/blog/1/images/blogimage_medium.jpg
uploads/blog/1/images/blogimage_small.jpg
uploads/blog/1/images/blogimage_thumbnail.jpg
uploads/testfolder/
uploads/testfolder/testimage.jpg

files_listing_filtered()
Returns a sorted and filtered list of FileObjects for listing():
>>> for item in filelisting.files_listing_filtered():
... print item
uploads/blog/
uploads/testfolder/

files_walk_filtered()
Returns a sorted and filtered list of FileObjects for walk():

12 Chapter 2. API
 Django FileBrowser Documentation, Release 3.5.3

>>> for item in filelisting.files_walk_filtered():

... print item
uploads/blog/
uploads/blog/1/
uploads/blog/1/images/
uploads/blog/1/images/blogimage.jpg
uploads/testfolder/
uploads/testfolder/testimage.jpg

Note: The versions are not listed (compared with files_walk_total) because of filter_func.

results_listing_total()
Number of total files, based on files_listing_total():
>>> filelisting.results_listing_total()
2

results_walk_total()
Number of total files, based on files_walk_total():
>>> filelisting.results_walk_total()
10

results_listing_filtered()
Number of filtered files, based on files_listing_filtered():
>>> filelisting.results_listing_filtered()
2

results_walk_filtered()
Number of filtered files, based on files_walk_filtered():
>>> filelisting.results_walk_filtered()
6

2.1.2 FileObject

class FileObject(path, site=None)

An object representing a media file.
Parameters
• path – Relative path to a location within site.storage.location.
• site – An optional FileBrowser Site.
For example:
from filebrowser.sites import site
from filebrowser.base import FileObject
fileobject = FileObject(os.path.join(site.directory,"testfolder","testimage.jpg"))
version = FileObject(os.path.join(fileobject.versions_basedir, "testfolder", "testimage_medium.jpg"))

2.1. API 13
Django FileBrowser Documentation, Release 3.5.3

Attributes

Initial Attributes

path
Path relative to a storage location (including site.directory):
>>> fileobject.path
’uploads/testfolder/testimage.jpg’

head
The directory name of pathname path:
>>> fileobject.head
’uploads/testfolder’

filename
Name of the file (including the extension) or name of the folder:
>>> fileobject.filename
’testimage.jpg’

filename_lower
Lower type of filename.
filename_root
Filename without extension:
>>> fileobject.filename_root
’testimage’

extension
File extension, including the dot. With a folder, the extensions is None:
>>> fileobject.extension
’.jpg’

mimetype
Mimetype, based on http://docs.python.org/library/mimetypes.html:
>>> fileobject.mimetype
(’image/jpeg’, None)

General Attributes

filetype
Type of the file, as defined with EXTENSIONS:
>>> fileobject.filetype
’Image’

filesize
Filesize in Bytes:
>>> fileobject.filesize
870037L

14 Chapter 2. API
 Django FileBrowser Documentation, Release 3.5.3

date
Date, based on time.mktime:
>>> fileobject.date
1299760347.0

datetime
Datetime object:
>>> fileobject.datetime
datetime.datetime(2011, 3, 10, 13, 32, 27)

exists
True, if the path exists, False otherwise:
>>> fileobject.exists
True

Path and URL attributes

path
Path relative to a storage location (including site.directory):
>>> fileobject.path
’uploads/testfolder/testimage.jpg’

path_relative_directory
Path relative to site.directory:
>>> fileobject.path_relative_directory
’testfolder/testimage.jpg’

path_full
Absolute server path (based on storage.path):
>>> fileobject.path_full
’/absolute/path/to/server/location/testfolder/testimage.jpg’

dirname
New in version 3.4.
The directory (not including site.directory):
>>> fileobject.dirname
’testfolder’

url
URL for the file/folder (based on storage.url):
>>> fileobject.url
’/media/uploads/testfolder/testimage.jpg’

Image attributes

The image attributes are only useful if the FileObject represents an image.
dimensions
Image dimensions as a tuple:

2.1. API 15
Django FileBrowser Documentation, Release 3.5.3

>>> fileobject.dimensions
(1000, 750)

width
Image width in px:
>>> fileobject.width
1000

height
Image height in px:
>>> fileobject.height
750

aspectratio
Aspect ratio (float format):
>>> fileobject.aspectratio
1.33534908

orientation
Image orientation, either Landscape or Portrait:
>>> fileobject.orientation
’Landscape’

Folder attributes

The folder attributes make sense when the FileObject represents a directory (not a file).
directory
Deprecated since version 3.5.3: Use path_relative_directory instead.
folder
Deprecated since version 3.5.3: Use dirname instead.
is_folder
True, if path is a folder:
>>> fileobject.is_folder
False

is_empty
True, if the folder is empty. False if the folder is not empty or the FileObject is not a folder:
>>> fileobject.is_empty
False

Version attributes

is_version
true if the File is a version of another File:

16 Chapter 2. API
 Django FileBrowser Documentation, Release 3.5.3

>>> fileobject.is_version
False
>>> version.is_version
True

versions_basedir
The relative path (from storage location) to the main versions folder. Either VERSIONS_BASEDIR or
site.directory:
>>> fileobject.versions_basedir
’_versions’
>>> version.versions_basedir
’_versions’

original
Returns the original FileObject:
>>> fileobject.original
<FileObject: uploads/testfolder/testimage.jpg>
>>> version.original
<FileObject: uploads/testfolder/testimage.jpg>

original_filename
Get the filename of an original image from a version:
>>> fileobject.original_filename
’testimage.jpg’
>>> version.original_filename
’testimage.jpg’

Methods

Version methods

versions()
List all filenames based on VERSIONS:
>>> fileobject.versions()
[’_versions/testfolder/testimage_admin_thumbnail.jpg’,
’_versions/testfolder/testimage_thumbnail.jpg’,
’_versions/testfolder/testimage_small.jpg’,
’_versions/testfolder/testimage_medium.jpg’,
’_versions/testfolder/testimage_big.jpg’,
’_versions/testfolder/testimage_large.jpg’]
>>> version.versions()
[]

Note: The versions are not being generated.

admin_versions()
List all filenames based on ADMIN_VERSIONS:
>>> fileobject.admin_versions()
[’_versions/testfolder/testimage_thumbnail.jpg’,
’_versions/testfolder/testimage_small.jpg’,
’_versions/testfolder/testimage_medium.jpg’,

2.1. API 17
Django FileBrowser Documentation, Release 3.5.3

’_versions/testfolder/testimage_big.jpg’,
’_versions/testfolder/testimage_large.jpg’]
>>> version.admin_versions()
[]

Note: The versions are not being generated.

version_name(version_suffix)
Get the filename for a version:
>>> fileobject.version_name("medium")
’testimage_medium.jpg’

Note: The version is not being generated.

version_path(version_suffix)
Get the path for a version:
>>> fileobject.version_path("medium")
’_versions/testfolder/testimage_medium.jpg’

Note: The version is not being generated.

version_generate(version_suffix)
Generate a version:
>>> fileobject.version_generate("medium")
<FileObject: uploads/testfolder/testimage_medium.jpg>

Please note that a version is only generated, if it does not already exist or if the original image is newer than the
existing version.

Delete methods

delete()
Delete the File or Folder from the server.

Warning: If you delete a Folder, all items within the folder are being deleted.

delete_versions()
Delete all VERSIONS.
delete_admin_versions()
Delete all ADMIN_VERSIONS.

18 Chapter 2. API
 CHAPTER 3

Fields & Widgets

3.1 Fields & Widgets

The FileBrowseField is a custom model field which returns a FileObject. The widgets FileInput and ClearableFileIn-
put are used with the admin app in order to show an additional thumbnail for images.

3.1.1 FileBrowseField

class FileBrowseField(max_length[, site, directory, extensions, format, **options ])

A subclass of CharField, referencing a media file within. Returns a FileObject.
Parameters
• site – A FileBrowser site (defaults to the main site), see FileBrowser Site.
• directory – Directory to browse when clicking the search icon.
• extensions – List of allowed extensions, see Extensions and Formats.
• format – A key from SELECT_FORMATS in order to restrict the selection to specific
filetypes, , see Extensions and Formats.
For example:
from filebrowser.fields import FileBrowseField

class BlogEntry(models.Model):
image = FileBrowseField("Image", max_length=200, directory="images/", extensions=[".jpg"], blank=
document = FileBrowseField("PDF", max_length=200, directory="documents/", extensions=[".pdf",".do

FileBrowseField in Templates

You can use all attributes from FileObject:

{{ blogentry.image }}
<img src="{{ publication.image.url }}" />

{% ifequal blogentry.image.image_orientation "landscape" %}

<img src="{{ blogentry.image.url }}" class="landscape" />
{% endifequal %}

19
Django FileBrowser Documentation, Release 3.5.3

Showing Thumbnail in the Changelist

To show a thumbnail with the changelist, you can define a ModelAdmin method:
from filebrowser.settings import ADMIN_THUMBNAIL

def image_thumbnail(self, obj):

if obj.image and obj.image.filetype == "Image":
return ’<img src="%s" />’ % obj.image.version_generate(ADMIN_THUMBNAIL).url
else:
return ""
image_thumbnail.allow_tags = True
image_thumbnail.short_description = "Thumbnail"

Using the FileBrowseField with TinyMCE

In order to replace the TinyMCE image/file manager with the FileBrowser, you have to use a FileBrowser Callback.
There’s an example TinyMCE configuration file in /static/js/ called TinyMCEAdmin.js. You can either copy the
FileBrowserCallback to your own file or just use tinymce_setup.js (which comes with django-grappelli).
Just add these lines to your ModelAdmin asset definitions:
class Media:
js = [’/path/to/tinymce/jscripts/tiny_mce/tiny_mce.js’,
’/path/to/your/tinymce_setup.js’]

3.1.2 FileInput

Subclass of FileInput with an additional thumbnail:

from filebrowser.widgets import FileInput

class BlogEntryOptions(admin.ModelAdmin):
formfield_overrides = {
models.ImageField: {’widget’: FileInput},
}

3.1.3 ClearableFileInput

Subclass of ClearableFileInput with an additional thumbnail:

from filebrowser.widgets import ClearableFileInput

class BlogEntryOptions(admin.ModelAdmin):
formfield_overrides = {
models.ImageField: {’widget’: ClearableFileInput},
}

3.1.4 Django FileField and the FileBrowser

Return a FileObject from a FileField or ImageField with:

20 Chapter 3. Fields & Widgets

 Django FileBrowser Documentation, Release 3.5.3

from filebrowser.base import FileObject

image_upload = models.ImageField(u"Image (Upload)", max_length=250, upload_to=image_upload_path, blan

def image(self):
if self.image_upload:
return FileObject(self.image_upload.path)
return None

In order show a thumbnail with your changelist, you could use a ModelAdmin method:
from filebrowser.base import FileObject

def image_thumbnail(self, obj):

if obj.image_upload:
image = FileObject(obj.image_upload.path)
if image.filetype == "Image":
return ’<img src="%s" />’ % image.version_generate(ADMIN_THUMBNAIL).url
else:
return ""
image_thumbnail.allow_tags = True
image_thumbnail.short_description = "Thumbnail"

Note: There are different ways to achieve this. The above examples show one of several options.

3.1. Fields & Widgets 21

Django FileBrowser Documentation, Release 3.5.3

22 Chapter 3. Fields & Widgets

 CHAPTER 4

Admin Interface

4.1 Admin Interface

The main FileBrowser admin application is an extension for the Django admin interface in order to browser your
media folder, upload and rename/delete files.

4.1.1 FileBrowser Site

New in version 3.4.0.

class FileBrowserSite(name=None, app_name=’filebrowser’, storage=default_storage)
Respresens the FileBrowser admin application (similar to Django’s admin site).
Parameters
• name – A name for the site, defaults to None.
• app_name – Defaults to ‘filebrowser’.
• storage – A custom storage engine, defaults to Djangos default storage.
Similar to django.contrib.admin, you first need to add a filebrowser.site to your admin interface. In
your urls.py, import the default FileBrowser site (or your custom site) and add the site to your URL-patterns (before
any admin-urls):
from filebrowser.sites import site

urlpatterns = patterns(’’,
url(r’^adminurl/filebrowser/’, include(site.urls)),
)

Now you are able to browse the location defined with the storage engine associated to your site.
from django.core.files.storage import DefaultStorage
from filebrowser.sites import import FileBrowserSite

# Default FileBrowser site

site = FileBrowserSite(name=’filebrowser’, storage=DefaultStorage())

# My Custom FileBrowser site

custom_site = FileBrowserSite(name=’custom_filebrowser’, storage=DefaultStorage())
custom_site.directory = "custom_uploads/"

23
Django FileBrowser Documentation, Release 3.5.3

Note: The module variable site from filebrowser.sites is the default FileBrowser application.

4.1.2 Custom Actions

New in version 3.4.0.

Similar to Django’s admin actions, you can define your FileBrowser actions and thus automate the typical tasks of
your users. Registered custom actions are listed in the detail view of a file and a user can select a single action at a
time. The selected action will then be applied to the file.
The default FileBrowser image actions, such as “Flip Vertical” or “Rotate 90° Clockwise” are in fact implemented as
custom actions (see the module filebrowser.actions).

Writing Your Own Actions

Custom actions are simple functions:

def foo(request, fileobjects):
# Do something with the fileobjects

The first parameter is a HttpRequest object (representing the submitted form in which a user selected the action)
and the second parameter is a list of FileObjects to which the action should be applied.
The list contains exactly one instance of FileObject (representing the file from the detail view), but this may change in
the future, as custom actions may become available also in browse views (similar to admin actions applied to a list of
checked objects).

Registering an Action

In order to make your action visible, you need to register it with a FileBrowser site:
site.add_action(foo)

Once registered, the action will appear in the detail view of a file. You can also give your action a short description:
foo.short_description = ’Do foo with the File’

This short description will then appear in the list of available actions. If you do not provide a short description, the
function name will be used instead and FileBrowser will replace any underscores in the function name with spaces.

Associating Actions with Specific Files

Each custom action can be associated with a specific file type (e.g., images, audio file, etc) to which it applies. In order
to do that, you need to define a predicate/filter function, which takes a single argument (FileObject) and returns True
if your action is applicable to that FileObject. Finally, you need to register this filter function with your action:
foo.applies_to(lambda fileobject: fileobject.filetype == ’Image’)

In the above example, foo will appear in the action list only for image files. If you do not specify any filter function
for your action, FileBrowser considers the action as applicable to all files.

24 Chapter 4. Admin Interface

 Django FileBrowser Documentation, Release 3.5.3

Messages & Intermediate Pages

You can provide a feedback to a user about a successful or failed execution of an action by using a message. For
example:
from django.contrib import messages

def desaturate_image(request, fileobjects):

for f in fileobjects:
# Desaturate the image
messages.add_message(request, messages.SUCCESS, _("Image ’%s’ was desaturated.") % f.filename

Some actions may require user confirmation (e.g., in order to prevent accidental and irreversible modification to
files). In order to that, follow the same pattern as with Django’s admin action and return a HttpResponse object
from your action. Good practice for intermediate pages is to implement a confirm view and have your action return
HttpResponseRedirect:
def crop_image(request, fileobjects):
files = ’&f=’.join([f.path_relative for f in fileobjects])
return HttpResponseRedirect(’/confirm/?action=crop_image&f=%s’ % files)

4.1.3 File Storages

New in version 3.4.0.

You have the option to specify which file storage engine a FileBrowser should use to browse/upload/modify your
media files. This enables you to use a FileBrowser even if your media files are located at some remote system. See
also the Django’s documentation on storages https://docs.djangoproject.com/en/dev/topics/files/.
To associate a FileBrowser site with a particular storage engine, set the storage property of a site object:
from django.core.files.storage import FileSystemStorage
site.storage = FileSystemStorage(location=’/path/to/media/directory’, base_url=’/media/’)

For storage classes other than FileSystemStorage (or those that inherit from that class), there’s more effort involved in
providing a storage object that can be used with FileBrowser. See StorageMixin Class

Note: Prior FileBrowser 3.4, the way to specify FileBrowser‘s MEDIA_ROOT and MEDIA_URL was via settings.py.
Starting from version 3.4, those variables are associated with the storage instance and you can set them as illustrated
in the above example.

Warning: For the reason of backward compatibility, FileBrowser settings FILEBROWSER_MEDIA_ROOT and
FILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as you’re using the default
FileBrowser‘s site without having changed its storage engine. In the next major release of FileBrowser these
settings will be removed.

StorageMixin Class

A FileBrowser uses the Django’s Storage class to access media files. However, the API of the Storage
class does not provide all methods necessary for FileBrowser’s functionality. A StorageMixin class from
filebrowser.storage module therefore defines all the additional methods that a FileBrowser requires:
isdir(self, name)
Returns true if name exists and is a directory.

4.1. Admin Interface 25

Django FileBrowser Documentation, Release 3.5.3

isfile(self, name)
Returns true if name exists and is a regular file.
move(self, old_file_name, new_file_name, allow_overwrite=False)
Moves safely a file from one location to another. If allow_ovewrite==False and new_file_name
exists, raises an exception.
makedirs(self, name)
Creates all missing directories specified by name. Analogue to os.mkdirs().

4.1.4 Views

All views use the staff_member_requird and path_exists decorator in order to check if the server path
actually exists. Some views also use the file_exists decorator.
• Browse, fb_browse Browse a directory on your server. Returns a FileListing.
– Optional query string args: dir, o, ot, q, p, filter_date, filter_type, type
• Create directory, fb_createdir Create a new folder on your server.
– Optional query string args: dir
– Signals: filebrowser_pre_createdir, filebrowser_post_createdir
• Upload, fb_upload Multiple upload.
– Optional query string args: dir
– Signals: filebrowser_pre_upload, filebrowser_post_upload
• Edit, fb_edit Edit a file or folder.
– Required query string args: filename
– Optional query string args: dir
– Signals: filebrowser_pre_rename, filebrowser_post_rename
You are able to apply custom actions (see Custom Actions) to the edit-view.
• Confirm delete, fb_confirm_delete Confirm the deletion of a file or folder.
– Required query string args: filename
– Optional query string args: dir
If you try to delete a folder, all files/folders within this folder are listed on this page.
• Delete, fb_delete Delete a file or folder.
– Required query string args: filename
– Optional query string args: dir
– Signals: filebrowser_pre_delete, filebrowser_post_delete

Warning: If you delete a Folder, all items within this Folder are being deleted.

• Version, fb_version Generate a version of an image as defined with ADMIN_VERSIONS.

– Required query string args: filename
– Optional Query string args: dir
This is a helper used by the FileBrowseField and TinyMCE for selecting a version.

26 Chapter 4. Admin Interface

 Django FileBrowser Documentation, Release 3.5.3

4.1.5 Signals

The FileBrowser sends a couple of different signals. Please take a look at the module filebrowser.signals for further
explanation on the provided arguments.
• filebrowser_pre_upload Sent before a an Upload starts.
• filebrowser_post_upload Sent after an Upload has finished.
• filebrowser_pre_delete Sent before an Item (File, Folder) is deleted.
• filebrowser_post_delete Sent after an Item (File, Folder) has been deleted.
• filebrowser_pre_createdir Sent before a new Folder is created.
• filebrowser_post_createdir Sent after a new Folder has been created.
• filebrowser_pre_rename Sent before an Item (File, Folder) is renamed.
• filebrowser_post_rename Sent after an Item (File, Folder) has been renamed.
• filebrowser_actions_pre_apply Sent before a custom action is applied.
• filebrowser_actions_post_apply Sent after a custom action has been applied.

Example for using these Signals

Here’s a small example for using the above Signals:

from filebrowser import signals

def pre_upload_callback(sender, **kwargs):

"""
Receiver function called before an upload starts.
"""
print "Pre Upload Callback"
print "kwargs:", kwargs
signals.filebrowser_pre_upload.connect(pre_upload_callback)

def post_upload_callback(sender, **kwargs):

"""
Receiver function called each time an upload has finished.
"""
print "Post Upload Callback"
print "kwargs:", kwargs
# You can use all attributes available with the FileObject
# This is just an example ...
print "Filesize:", kwargs[’file’].filesize
print "Orientation:", kwargs[’file’].orientation
print "Extension:", kwargs[’file’].extension
signals.filebrowser_post_upload.connect(post_upload_callback)

4.1. Admin Interface 27

Django FileBrowser Documentation, Release 3.5.3

28 Chapter 4. Admin Interface

 CHAPTER 5

Image Versions

5.1 Versions

With the FileBrowser, you are able to define different versions/sizes for images. This enables you to save an original
image on your server while having different versions of that image to automatically fit your websites grid. Versions
are also useful for responsive/adaptive layouts.

5.1.1 Defining Versions

New in version 3.4.0: methods

First you need to know which versions/sizes of an image you’d like to generate with your website. Let’s say you’re
using a 12 column grid with 60px for each column and 20px margin (which is a total of 940px). With this grid, you
could (for example) define these image versions.
FILEBROWSER_VERSIONS_BASEDIR = ’_versions’
FILEBROWSER_VERSIONS = {
’admin_thumbnail’: {’verbose_name’: ’Admin Thumbnail’, ’width’: 60, ’height’: 60, ’opts’: ’crop’},
’thumbnail’: {’verbose_name’: ’Thumbnail (1 col)’, ’width’: 60, ’height’: 60, ’opts’: ’crop’},
’small’: {’verbose_name’: ’Small (2 col)’, ’width’: 140, ’height’: ’’, ’opts’: ’’},
’medium’: {’verbose_name’: ’Medium (4col )’, ’width’: 300, ’height’: ’’, ’opts’: ’’},
’big’: {’verbose_name’: ’Big (6 col)’, ’width’: 460, ’height’: ’’, ’opts’: ’’},
’large’: {’verbose_name’: ’Large (8 col)’, ’width’: 680, ’height’: ’’, ’opts’: ’’},
}

Use the methods argument, if you need to add a filter:

def grayscale(im):
"Convert image to grayscale"
if im.mode != "L":
im = im.convert("L")
return im

FILEBROWSER_VERSIONS = {
’big’: {’verbose_name’: ’Big (6 col)’, ’width’: 460, ’height’: ’’, ’opts’: ’’, ’methods’: [graysc
})

29
Django FileBrowser Documentation, Release 3.5.3

5.1.2 Versions and the Admin

When using the FileBrowser with the admin interface, you need to define ADMIN_VERSIONS and
ADMIN_THUMBNAIL (see Settings). ADMIN_VERSIONS are available with the admin, i.e. you are able to see
these versions with the image detail view and you are able to select the versions with the FileBrowseField model field.
FILEBROWSER_ADMIN_VERSIONS = [’thumbnail’, ’small’, ’medium’, ’big’, ’large’]
FILEBROWSER_ADMIN_THUMBNAIL = ’admin_thumbnail’

5.1.3 Versions and the Frontend

With your templates, you have two different tags to choose from: version and version_object. With both
tags, the version will be generated if it doesn’t already exist OR if the original image is newer than the version. In
order to update an image, you just overwrite the original image and the versions will be generated automatically (as
you request them within your template).
A Model example:
from filebrowser.fields import FileBrowseField

class BlogEntry(models.Model):
image = FileBrowseField("Image", max_length=200, blank=True, null=True)

With your templates, use version if you simply need to retrieve the URL or version_object if you need to get
a FileObject:
<!-- load filebrowser templatetags -->
{% load fb_versions %}

<!-- get the url with version -->

<img src="{% version blogentry.image ’medium’ %}" />

<!-- get a fileobject with version_object -->

{% version_object blogentry.image ’medium’ as version_medium %}
{{ version_medium.width }}
<img src="{{ version_medium }}" />

Templatetag version

Retrieves/Generates a version and returns an URL:

{% version model.field_name version_prefix %}

Templatetag version_object

Retrieves/Generates a version and returns a FileObject:

{% version_object model.field_name version_prefix as variable %}

Note: With both templatetags, version_prefix can either be a string or a variable. If version_prefix is a
string, use quotes.

30 Chapter 5. Image Versions

 Django FileBrowser Documentation, Release 3.5.3

5.1.4 Versions in Views

If you have a FileObject you can generate/retrieve a version with:

v = obj.image.version_generate(version_prefix) # returns a FileObject

5.1.5 Placeholder

When developing on a locale machine or a development-server, you might not have all the images (resp. media-files)
available that are on your production instance and downloading these files on a regular basis might not be an option.
In that case, you can use a placeholder instead of a version. You just need to define the PLACEHOLDER and overwrite
the settings SHOW_PLACEHOLDER and/or FORCE_PLACEHOLDER (see Placeholder).

5.1.6 Management Commands

fb_version_generate
If you need to generate certain (or all) versions, type:
python manage.py fb_version_generate

fb_version_remove
If you need to generate certain (or all) versions, type:
python manage.py fb_version_generate

Warning: Please be very careful with this command.

5.1. Versions 31
Django FileBrowser Documentation, Release 3.5.3

32 Chapter 5. Image Versions

 CHAPTER 6

Help

6.1 Help

6.1.1 FAQ

Why should I use the FileBrowser?

If you need your editors or customers to manage files, the FileBrowser is an alternative to an FTP-client. Moreover,
you are able to define different image versions according to your websites grid. Alternatives to the FileBrowser can be
found at http://djangopackages.com/grids/g/file-managers/.

Do I need Grappelli?

Grappelli is a requirement for using the FileBrowser. There are several filebrowser-no-grappelli repositories (most of
them on GitHub), but we don’t follow the development.

I need help!

see Troubleshooting.

Why are there no fancy effects?

The FileBrowser is about managing files. We think that you should prepare your files before uploading them to the
server.

How do I upload to another server?

Use a custom storage engine, see https://docs.djangoproject.com/en/1.6/howto/custom-file-storage/.

Why do I need image-versions?

You need image-versions if your website is based on a grid.

33
Django FileBrowser Documentation, Release 3.5.3

Is the FileBrowser stable?

We’ve developed the FileBrowser for a couple of years and use it with almost all of our clients. That said, Grappelli is
the more stable and mature application.

How can I contribute?

Help is very much needed and appreciated. Test the FileBrowser and submit feedback/patches.

Who develops the FileBrowser?

The FileBrowser is developed and maintained by Patrick Kranzlmüller & Axel Swoboda of vonautomatisch.

6.1.2 Troubleshooting

Check your setup

Please check if the problem is caused by your setup.

• Read Quick start guide.
• Check if the static/media-files are served correctly.
• Make sure you have removed all custom FileBrowser templates from all locations in TEMPLATE_DIRS or
check that these templates are compatible with the FileBrowser.

Run the tests

Start the shell and type:

python manage.py test filebrowser

Warning: Please note that the tests will copy files to your filesystem.

Check issues

If your setup is fine, please check if your problem is a known issue.

• Take a look at all FileBrowser Issues (incuding closed) and search the FileBrowser Google-Group.

Add a ticket

If you think you’ve found a bug, please add a ticket.

• Try to describe your problem as precisely as possible.
• Tell us what you did in order to solve the problem.
• Tell us what version of the FileBrowser you are using.
• Tell us what version of Django you are using.

34 Chapter 6. Help
 Django FileBrowser Documentation, Release 3.5.3

• Please do NOT add tickets if you’re having problems with serving static/media-files (because this is not related
to the FileBrowser).
• Please do NOT add tickets referring to Djangos trunk version.
• At best: add a patch.

Note: Be aware that we may close issues not following these guidlines without further notifications.

6.1.3 Translation

Translation is done via Transifex.

Supported Languages

see https://www.transifex.net/projects/p/django-filebrowser/resource/djangopo/

6.1.4 FileBrowser 3.5 Release Notes

FileBrowser 3.5 is compatible with Django 1.4, 1.5 and 1.6 as well as Grappelli 2.4 and 2.5.

Update from FileBrowser 3.4.x

• Update Django to 1.4/1.5/1.6 and check https://docs.djangoproject.com/en/dev/releases/1.4/ or

https://docs.djangoproject.com/en/dev/releases/1.5/ or https://docs.djangoproject.com/en/dev/releases/1.6/
• Update Grappelli to 2.4.x/2.5.x
• Update FileBrowser to 3.5.x

6.2 Changelog

6.2.1 3.5.4 (not yet released)

6.2.2 3.5.3 (January 7, 2014)

• New: added path_full to FileObject.

• Improved: added docx to EXTENSIONS.
• Improved: Recommend pillow instead of PIL as a requirement.
• Improved: Added additional test cases.
• Improved: Updated documentation.
• Improved: Consistent use of storage (e.g. storage.location, storage.url).
• Improved: Removed unnecessary functions (e.g. url_join, url_strip).
• Improved: Moved sort_by_attr to FileListing.
• Improved: Regex matches with file versions on browse.
• Improved: Using django.conf.urls (with django.conf.urls.defaults as fallback).

6.2. Changelog 35
Django FileBrowser Documentation, Release 3.5.3

• Improved: Adding CONTRIBUTING.rst.

• Improved: Removed static Media inner class with fields.
• Improved: Removed search icon with fields (has not being used).
• Improved: Added custom class attributes with filebrowser field.
• Improved: Updated translations.
• Fixed: fixed exception handling with python 2.5.
• Fixed: fixes dir with SEARCH_TRAVERSE true and version select.
• Fixed: Make Django FileUploadHandlers work (also fixed a memory leak).
• Fixed: return correct filename with OVERWRITE_EXISTING.
• Fixed: fb_version_generate with FILEBROWSER_VERSIONS_BASEDIR.
• Fixed: Table sorting with asc/desc.
• Fixed: Added DeprecationWarning for FileObject.directory and FileObject.folder.

6.2.3 3.5.2 (February 22, 2013)

• Fixed: Use placeholder with version_generate (not only templatetags).

• Fixed: translate extension group name in upload form.
• Fixed: updated filter dropdown HTML.
• Fixed: Make setup.py work with Python 3.
• Fixed: File submit with search traversal.
• Fixed: Fixed fileobject path with Windows.
• Improved: Throwing an exception when in DEBUG and version is not generated (with using the templatetag).
• Compatibility with Django 1.5.

6.2.4 3.5.1 (November 09, 2012)

• Fixed: Documentation with Signals.

• Fixed: File Upload using basic submission.
• Fixed: Added site instance to Signals.
• Improved: Don’t hide errors during generate-command.
• Improved: Follow symlinks with generate-command.
• Improved: Added some translations (e.g. for “Upload File”).
• New: Setting OVERWRITE_EXISTING.
• New: Added file signals.py.
• New: Support for Django 1.5.

36 Chapter 6. Help
 Django FileBrowser Documentation, Release 3.5.3

6.2.5 3.5.0 (July 20, 2012)

• Compatibility with Django 1.4 and Grappelli 2.4.

6.2.6 3.4.3 (20.6.2012)

• Fixed a bug with versions not being generated (in case of capitalized extensions).

6.2.7 3.4.2 (26.3.2012)

• Fixed security bug: added staff_member_required decorator to the upload-function.

• Fixed a XSS vulnerability with fb_tags.

6.2.8 3.4.1 (7.3.2012)

• Fixed an error with quotes (french translation) in upload.html.

• Updated translations.
• FileObject now returns path (with __unicode__ and __str__), instead of filename. This is needed because
otherwise form.has_changed will always be triggerde when using a FileBrowseField.
• Fixed a bug with versions and “f referenced before assignment” (e.g. when an image is being deleted)
• Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-
moved with the next major release – use custom storage engine instead).
• Fixed issue with MEDIA_URL hardcoded in tests.
• Fixed issue when MEDIA_URL starts with https://.
• Fixed issue with default-site (if no site is given).
• Fixed bug with using L10N and MAX_UPLOAD_SIZE in upload.html.
• Fixed small bug with importing Http404 in sites.py.
• Fixed bug with Fileobject.exists.
• Added NORMALIZE_FILENAME.

6.2.9 3.4.0 (15/11/2011)

• Final release of 3.4, see FileBrowser 3.5 Release Notes

6.2. Changelog 37
Django FileBrowser Documentation, Release 3.5.3

38 Chapter 6. Help
 CHAPTER 7

Main Features

• Browse your media files with the admin interface.

• Multiple upload, including a progress bar.
• Automatic thumbnails.
• Image versions to fit your websites grid (esp. useful with adaptive/responsive layouts).
• Integration with TinyMCE.
• FileBrowseField to select images/documents.
• FileInput and ClearableFileInput with image preview.
• Signals for upload, rename and delete.
• Custom actions.
• Custom file storage engines.

39
Django FileBrowser Documentation, Release 3.5.3

40 Chapter 7. Main Features

 CHAPTER 8

Code

https://github.com/sehmaschine/django-filebrowser

41
Django FileBrowser Documentation, Release 3.5.3

42 Chapter 8. Code
 CHAPTER 9

Discussion

Use the FileBrowser Google Group to ask questions or discuss features.

43
Django FileBrowser Documentation, Release 3.5.3

44 Chapter 9. Discussion
 CHAPTER 10

Versions and Compatibility

• FileBrowser 3.5.4 (Development Version, not yet released, see Branch Stable/3.5.x)
• FileBrowser 3.5.3 (January 7, 2014): Compatible with Django 1.4/1.5/1.6
Older versions are availabe at GitHub, but are not supported anymore.

45