Optionset settings


This is a dictionary used by the elfinder.fields.ElfinderFile class to define how the elfinder connector handles files and directories. Each dictionary key represents a different set of options. You can use this setting to define your own option sets or override the defaults.


yawd-elfinder defines two optionsets: default and image; the first is used to handle all sorts of files and the latter allows only image files in the file manager root directory.

Each optionset can define one of the following keys:

  • debug: indicates if we’re on debug mode: True or False

  • roots: a list of root directories that elfinder will load on its instantiation. For example, the following will load both pdfs and docs directories:

       'myoptionset' : {
          'debug' : False,
          'roots' : [
             { 'id' : 'volume1', 'path' : os.path.join(join(settings.MEDIA_ROOT, 'pdfs')) },
             { 'id' : 'volume2', 'path' : os.path.join(join(settings.MEDIA_ROOT, 'docs')) }


Each root can define one of the following keys:


Required. A unique string representing this root.


Required. The volume driver class. yawd-elfinder currently implements the elfinder.volumes.filesystem.ElfinderVolumeLocalFileSystem driver. This can be used to retrieve files located in your filesystem. Plans exist to implement an FTP driver in future releases. This can be a class or a class path string.


Default: '/'

The path to the root directory. Each driver may change the default value. For example, the elfinder.volumes.filesystem.ElfinderVolumeLocalFileSystem driver sets this to the project’s MEDIA_ROOT setting by default.


Default: ''

A string used by the driver to replace the root path and hide it from the end-user. Say you set this to ‘My root’ then elfinder will display ‘My Root/docs/document1.doc’ instead of ‘/home/django/project/media/docs/document1.doc’ to the frontend. If not provided elfinder will just use ‘docs/document1.doc’ instead.


Default: ''

Open this path on initial request instead of root path.


Default: 1

The depth of sub-directories (recursive directory listings) that should return per request. It must be greater than zero.


Default: os.sep

The path separator used by this driver. Normally, you do not want to change this setting.


Default: '.tmb'

The directory under which auto-generated thumbnails will be placed.


Default: ''

Thumbnails dir URL. Set this if you’re storing thumbnails outside the root directory


Default: 48

Thumbnail size (in px)


Default: True

Whether to crop (scale image to fit) thumbnails or not. Can be True or False


Default: '#ffffff'

The default thumbnail background color used when the image is not cropped.


Default: True

Whether on pasting to an existing file should overwrite the original or not. if False` the new file will get a name of the form ‘{original_name}-{number}.ext}’.


Default: True

If True, the volume driver will join new and old directory content on paste.


Default: []

A list of the mime types to show for this root. The driver checks if the file mime type starts with values in this lists. Therefore, to allow for displaying only images you can use ['image',] and all files whose mime starts with 'image' (e.g. ‘image/png’, ‘image/jpg’ etc) will be filtered out. This filter will also prevent unaccepted files from being uploaded as well as extracted from archive files.


Default: True

Used whn uploading files. If True, the old file will be replaced with new one. If set to False, the new file will get a name of the form ‘{original_name}-{number}.{ext}’


Default: ['all',]

A list containing the mime types allowed for upload. Use 'all' for all mimetypes. You can also use the first half of a mime type to match types starting with a certain prefix. E.g. use ['application',] to match ‘application/pdf’, ‘application/ms-word’ etc.


For more info on how this ssetting is used, see the uploadOrder setting.


Default: ['all',]

A list containing the mime types not allowed for upload. Use 'all' for all mimetypes. You can also use the first half of a mime type to match types starting with a certain prefix. E.g. use ['application',] to match ‘application/pdf’, ‘application/ms-word’ etc.


For more info on how this ssetting is used, see the uploadOrder setting.


Default: ['deny', 'allow']

The order in which to proccess uploadAllow and uploadDeny options.


Default: 0

The maximum upload file size. Set as number (bytes) or string ending with the size unit (e.g. “10M”, “500K”, “1G”)


This corresponds to each uploaded file. It is a hard limit.


Default: True

If True, each folder will be checked for having child directories. When set to False, all folders will be marked as having sub-directories and sub-sequent directory listing calls might be generated.


Default: True

Whether copying files from this volume to other volumes should be allowed or not. True or False.


Default: True

Whether pasting files originating from other volumes to this volume should be allowed or not. True or False.


Default: []

A list of the commands that should be disabled for this root. For example, to disallow the creation of new text files and archives in a root intented for containing images, you should set this setting to ['mkfile', 'archive'].

For a list of the available commands, see the elfinder.connector.ElfinderConnector class.


Default: r'^[^\.].*'

Regular expression against which all new file names will be validated. For example, to allow creating hidden files you could use the value r'.*'.


Default: None

A callable that controls file permissions. If provided, this can override a file’s default permissions. When called, the callable should return True if a certain file is given a certain permission, False if not and None if the standard permission rules should be applied. fs_standard_access() is an example of an accessControl callable that make dotfiles not readable, not writable, hidden and locked.



   'read' : True,
   'write' : True,

Default file permissions. Given a file, these are applied when:

  • No accessControl callable is provided, or the callable returns None for this file
  • No attributes rule applies to the file


Do not set the hidden``and ``locked properties here; they would take no effect as the default value for both properties is False.


Default: []

A list of permissions for specific file name patterns. Each value in the list must be a dictionary containing at least a pattern key and one or more of the read, write, locked and hidden properties. Any filename will be validated against the pattern and if a match is found, the permission rules will be applied. The first match is retunrf.

For example, to hide and lock the default thumbnails directory (to prevent viewing and deleting the directory), you could set this to:

      'pattern' : r'\.tmb$',
      'read' : True,
      'write': True,
      'hidden' : True,
      'locked' : True


Given a file, these rules override the defaults permissions, but are ignored if an accessControl callable is set and that callable returns True or False for defined properties of the file.


Default: '.quarantine'

A local folder used to temporarily extract files from an archive and check them for validity. This path is always created (if it does not already exist) on the local filesystem. The quarantine option may also be used from some drivers to temporarily store files when creating archives form a remote filesystem.


Default: []

Allowed archive mimetypes for this root. Leave empty for all available types.


Default: {}

A dictionary with two keys: create and extract. The first is used to define classes that generate archive files and the latter classes that can open/read archive files. Use this setting to provide additional archiver implementations, other than what yawd-elfinder already implements. By default, yawd-elfinder can create and read archives having the following mime types

  • application/x-tar (.tar files)
  • application/x-gzip (.gzip files)
  • application/x-bzip2 (.bzip files)
  • application/zip (.zip files)

If you need additional archivers use this setting as follows:

   'create' : {
      'application/java-archive' :  {
         'ext' : 'jar',
         'archiver' : MyJarArchiver
       'application/whatever' : {
         'ext' : 'whatever',
         'archiver' : MyWhateverArchiver
   'extract' : {
      'application/java-archive' :  {
         'ext' : 'jar',
         'archiver' : MyJarReader
       'application/whatever' : {
         'ext' : 'whatever',
         'archiver' : MyWhateverReader

Create archiver classes (e.g. MyJarArchiver in the above example) must implement the open, add and close methods according to Python’s built-in tarfile.TarFile class.

Extract/read archiver classes (e.g. MyJarReader in the above example) must implement the open, extractall and close methods and operate like python’s built-in tarfile.TarFile class.

For more information see http://docs.python.org/library/tarfile.html and view yawd-elfinder’s elfinder.utils.archivers.ZipFileArchiver source code.


Default: 0

The maximum allowed size of a new archive file. Set as number (bytes) or string ending with the size unit (e.g. “10M”, “500K”, “1G”). 0 means there is no size restriction.


Default: False

If True, instantiation and mount of this volume driver happens only once during the application lifetime. This can be set to False for local volumes or quick remote drivers to avoid memory overhead. It is very useful to enable it for volumes using RESTful APIs or other protocols that can be slow to initialize and mount.


Default: 600

The time in seconds for which yawd-elfinder will store file and dir listings in the cache. The higher the value, the less disk read operations are performed. Especially when it comes to remote volumes a higher value might be better. 0 seconds means that internal caching is disabled.


There might be some cases where you should lower the cache (although not recommended). If disk contents change constantly (i.e. from batch processes or 3rd party applications) you might find yawd-elfinder displaying the wrong data.For example if you manually delete a file from disk, it could theoretically take up to 10 minutes for yawd-elfinder to notice with the default value. However in typical set-ups this is not an issue.

Volume-specific root settings

Each volume driver can define its own extra root configuration options.

ElfinderVolumeLocalFileSystem additional settings

The elfinder.volumes.filesystem.ElfinderVolumeLocalFileSystem driver defines three extra options:


Required. The URL to the root directory (e.g. 'http://example.com/files/').


Default: 0755

The default mode of new directories created with elFinder when using this root (octal value).


Default: 0644

The default mode of new files created with elFinser when using this root (octal value).

ElfinderVolumeStorage additional settings

The elfinder.volumes.storage.ElfinderVolumeStorage driver defines some extra configuration options as well:


Default None

For ElfinderVolumeStorage to work we must set the Django filesystem storage it will use. This setting should be set to a storage instance.


Default None

In some cases we may not be able to instantiate a storage directly in the project main settings module. As an alternative method of providing the storage instance, storageClass can be used to set the class and storageKwArgs the keyword arguments that the driver will use to create a new storage instance. This setting can be a class (e.g. FileSystemStorage) or a string containing a fully qualified path to a python class (e.g. ‘django.core.files.storage.FileSystemStorage’). If both storage and storageClass are not set, the driver will create a new django.core.files.storage.FileSystemStorage instance managing your MEDIA_ROOT directory and ignoring the storageKwArgs setting.


storage has a higher priority over storageClass.


Default {}

The keyword arguments to use upon storage instantiation. Use this along with the storageClass setting.

For example, the two roots in the following configuration are the same:

    'myoptionset' : {
        'roots' : [{
            'id' : 'lr',
            'driver' : ElfinderVolumeStorage,
            'storageClass' : 'django.core.files.storage.FileSystemStorage',
            'storageKwArgs' : {
                    'location' : settings.MEDIA_ROOT,
                    'base_url' : settings.MEDIA_URL
            'id' : 'lr2',
            'driver' : ElfinderVolumeStorage,
            'storage' : FileSystemStorage()


Default: None

Filesystem storages do not provide a way for removing directories. You can use this setting to point to a callable that will handle directory removal for the current storage. The callable must accept two arguments: path and storage, the first being the path to delete and the latter the storage instance to use. When this is not set, yawd-elfinder behaves as follows: If the storage is an instance of :class:django.core.files.storage.FileSystemStorage it will use a built-in callable. If it’s not it will disable the rmDir functionality.