### Navigation

- index
- next |
- previous |
- Django FileBrowser v3.4.0 documentation »

# Image 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 and the grid

First you need to know which versions/sizes of an image you´d like to use on 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) generate these image versions:

    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': ''},
    })

New in version 3.4.0: `methods`

If you need to add some filter for the version (like grayscale, sepia, ...), you can also use the `methods` argument:

    def grayscale(im):
        '''Convert the PIL 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': [grayscale]},
    })

## Versions with the admin-interface

With the admin-interface, you need to define `ADMIN_VERSIONS`:

    ADMIN_VERSIONS = getattr(settings, 'FILEBROWSER_ADMIN_VERSIONS', ['thumbnail', 'small', 'medium', 'big', 'large'])

Don’t forget to select one version for your admin-thumbnail:

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

## Versions on your website

In order to generate versions, you have two different tags to choose from: `version` and `version_object`. With either using the version-tag or the version_object-tag, the Image-version will be generated “on the fly” if the version doesn´t already exist or if the original Image is newer than the version. This means that if you need to update an Image, you just overwrite the original Image - the versions will be re-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)

First you need to load the templatetags with:

    {% load fb_versions %}

You have two different tags to choose from: `version` and `version_object`.

Note

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

### Templatetag `version`

Generate a version and retrieve the URL:

    {% version model.field_name version_prefix %}

With the above Model, in order to generate a version you type:

    {% version blogentry.image 'medium' %}

Since you retrieve the URL, you can display the image with:

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

### Templatetag `version_object`

Generate a version and retrieve the FileObject:

    {% version_object model.field_name version_prefix as variable %}

With the above Model, in order to generate a version you type:

    {% version_object blogentry.image 'medium' as version_medium %}

Since you retrieve a `FileObject`, you can use all attributes:

    {{ version_medium.width }}

or just:

    <img src="{{ version_medium }}" />

## Versions in views

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

    obj.image.version(version_prefix)

So, if you need to generate/retrieve the admin thumbnail for an Image, you can type:

    from filebrowser.settings import ADMIN_THUMBNAIL
    obj.image.version_generate(ADMIN_THUMBNAIL).url

## 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 might wanna use a placeholder instead of an image-version. You just need to define the `PLACEHOLDER` and overwrite the settings `SHOW_PLACEHOLDER` and/or `FORCE_PLACEHOLDER` (see PLACEHOLDER).

# Management Commands

## Command `fb_version_generate`

If you need to generate certain (or all) versions, type:

    python manage.py fb_version_generate

## Command `fb_version_remove`

If you need to generate certain (or all) versions, type:

    python manage.py fb_version_remove

Warning

Please be very careful with this command.

### Navigation

- index
- next |
- previous |
- Django FileBrowser v3.4.0 documentation »