Quick-start guide: Using yawd-elfinder

Before reading this quick-start guide make sure yawd-elfinder is installed and configured.

The ElfinderFile model field

You should start by defining model fields that refer to files managed by elfinder. For example, to define an image field for a simple article model:

from django.db import models
from elfinder.fields import ElfinderField

class SimpleArticle(models.Model):
   name = models.CharField(max_length=100)
   content = models.TextField()
   image = ElfinderField(optionset='image')

   def __unicode__(self):
      return self.name

The elfinder.fields.ElfinderField field associates the image member with an elfinder.fields.ElfinderFile object. The optionset argument specifies a set of configuration options that define stuff like allowed file types, where to store uploaded files etc. yawd-elfinder by default configures two optionsets: default and image. When using

my_field = ElfinderField(optionset='default')

...yawd-elfinder will store uploaded files to a ‘files’ directory under your MEDIA_ROOT, and allow all kinds of files to be uploaded and managed.

When using

my_field = ElfinderField(optionset='image')

...yawd-elfinder will store uploaded files to an ‘images’ directory under your MEDIA_ROOT, and allow only image files to be uploaded and managed.

Of course, you can define your own optionsets. For more information on how to do this, view the Simple dropbox example below and visit the ELFINDER_CONNECTOR_OPTION_SETS setting documentation.

elfinder.fields.ElfinderFile can also accept a start_path argument to indicate the default folder to open for this field. For example, to open a folder named ‘languages’ you could use the following code:

my_field = ElfinderField(optionset='image', start_path='languages')

yawd-elfinder expects that the path defined in start_path is relative to the volume root (see the path setting). In fact, start_path sets the startPath setting to the provided value.

Django templates

Based on the above SimpleArticle example, if object is a SimpleArticle model instance, use the elfinder.fields.ElfinderFile url property to retrieve the image url:

<img src="{{object.image.url}}" alt="{{object.name}}" />

You can directly check if an elfinder.fields.ElfinderField of your model is empty:

{% if object.image %}..print the image..{% endif %}

To see if an elfinder.fields.ElfinderFile object is valid, you can check the hash attribute (let’s assume a context variable elfinderfile holds the ElfinderFile):

{% if elfinderfile.hash %}..print the file..{% endif %}

...or check the url attribute

{% if elfinderfile.url %}..print the file..{% endif %}

The above two will both work and perform the same.


The elfinder.fields.ElfinderField will return None if there is no file associated to the field. Otherwise, it will always return an ElfinderFile object, even if the actual file does not exist anymore (e.g. you have assigned the file and then deleted it in the file system). In that sense it is always preferred to check the ElfinderFile in your templates:

{% if object.image.url %}..do stuff..{% endif %}

Further reading

You can read some additional yawd-elfinder articles on the yawd blog: