FileBrowser Sites

New in version 3.4.0.

The FileBrowser application is respresented by an object of filebrowser.sites.FileBrowserSite (similar to Django’s admin site). FileBrowser sites allow you to:

  • associate Custom Actions to a site,
  • define File Storages,
  • subclass from FileBrowserSite and redefine the default FileBrowser’s behavior,
  • use multiple FileBrowser sites with your project.

Note

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

FileBrowserSite(name=None, app_name=’filebrowser’, storage=default_storage)

The FileBrowser application is respresented by an object of FileBrowserSite (similar to Django’s admin site). FileBrowser sites allow you to:

name
A name for the site, defaults to None.
app_name
Defaults to ‘filebrowser’.
storage
A custom storage engine, defaults to Djangos default storage.

For example:

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/"

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.

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)

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.

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().