django filebrowser documentation

73
Django FileBrowser Documentation Release 3.5.2 Patrick Kranzlmueller December 15, 2013

Upload: others

Post on 05-Jun-2022

39 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Django FileBrowser Documentation

Django FileBrowser DocumentationRelease 352

Patrick Kranzlmueller

December 15 2013

Contents

1 Quick start guide 311 Requirements 312 Download 313 Installation 314 Settings 415 Testing 4

2 Settings 521 Main URLPaths Settings 522 FileBrowser Media TinyMCE Media 623 Extensions and Formats 624 Versions 725 Extra Settings 8

3 FileBrowser Sites 1131 Backward Incompatibilites 11

4 Custom Actions 1341 Writing Your Own Actions 1342 Registering an Action 1343 Associating Actions with Specific Files 1444 Messages amp Intermediate Pages 14

5 File Storages 1551 StorageMixin Class 15

6 FileListing class 1761 Options 1762 Attributes 17

7 FileObject class 2171 General attributes 2172 Path and URL attributes 2273 Image attributes 23

i

74 Folder attributes 2475 Version attributes 2476 Functions 26

8 Views 2781 Browse 2782 Create directory 2783 Upload 2784 Edit 2885 Confirm delete 2886 Delete 2887 Version 29

9 Signals 3191 filebrowser_pre_upload 3192 filebrowser_post_upload 3193 filebrowser_pre_delete 3194 filebrowser_post_delete 3295 filebrowser_pre_createdir 3296 filebrowser_post_createdir 3297 filebrowser_pre_rename 3298 filebrowser_post_rename 3299 filebrowser_actions_pre_apply 33910 filebrowser_actions_post_apply 33911 Example for using these Signals 33

10 FileBrowseField 35101 Attributes 35102 FileBrowseField in Templates 35103 Showing Thumbnail in the Changelist 36104 Using the FileBrowseField with TinyMCE 36

11 FileInput 37

12 ClearableFileInput 39

13 Django FileField and the FileBrowser 41

14 Image Versions 43141 Versions and the grid 43142 Versions with the admin-interface 43143 Versions on your website 44144 Versions in views 45145 Placeholder 45

15 Management Commands 47151 Command fb_version_generate 47152 Command fb_version_remove 47

16 FAQ 49161 Why should I use the FileBrowser 49162 I want to use FileBrowser but I donrsquot want to use Grappelli 49163 I need help 49164 Why are there no fancy effects 49165 How do I upload to another server 49

ii

166 Why should I need image-versions 50167 Is the FileBrowser stable 50168 How can I contribute 50169 Who develops the FileBrowser 50

17 Troubleshooting 51171 Check your setup 51172 Run the FileBrowser tests 51173 Check issues 51174 Add a ticket 51

18 Translation 53

19 Supported Languages 55

20 FileBrowser 35 Release Notes 57201 Update from FileBrowser 34x 57

21 Changelog 59211 353 (not yet released) 59212 352 (February 22 2013) 59213 351 (November 09 2012) 59214 350 (July 20 2012) 60215 343 (2062012) 60216 342 (2632012) 60217 341 (732012) 60218 340 (15112011) 60

22 Main Features 61

23 Code 63

24 Discussion 65

25 Versions and Compatibility 67

iii

iv

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 2: Django FileBrowser Documentation

Contents

1 Quick start guide 311 Requirements 312 Download 313 Installation 314 Settings 415 Testing 4

2 Settings 521 Main URLPaths Settings 522 FileBrowser Media TinyMCE Media 623 Extensions and Formats 624 Versions 725 Extra Settings 8

3 FileBrowser Sites 1131 Backward Incompatibilites 11

4 Custom Actions 1341 Writing Your Own Actions 1342 Registering an Action 1343 Associating Actions with Specific Files 1444 Messages amp Intermediate Pages 14

5 File Storages 1551 StorageMixin Class 15

6 FileListing class 1761 Options 1762 Attributes 17

7 FileObject class 2171 General attributes 2172 Path and URL attributes 2273 Image attributes 23

i

74 Folder attributes 2475 Version attributes 2476 Functions 26

8 Views 2781 Browse 2782 Create directory 2783 Upload 2784 Edit 2885 Confirm delete 2886 Delete 2887 Version 29

9 Signals 3191 filebrowser_pre_upload 3192 filebrowser_post_upload 3193 filebrowser_pre_delete 3194 filebrowser_post_delete 3295 filebrowser_pre_createdir 3296 filebrowser_post_createdir 3297 filebrowser_pre_rename 3298 filebrowser_post_rename 3299 filebrowser_actions_pre_apply 33910 filebrowser_actions_post_apply 33911 Example for using these Signals 33

10 FileBrowseField 35101 Attributes 35102 FileBrowseField in Templates 35103 Showing Thumbnail in the Changelist 36104 Using the FileBrowseField with TinyMCE 36

11 FileInput 37

12 ClearableFileInput 39

13 Django FileField and the FileBrowser 41

14 Image Versions 43141 Versions and the grid 43142 Versions with the admin-interface 43143 Versions on your website 44144 Versions in views 45145 Placeholder 45

15 Management Commands 47151 Command fb_version_generate 47152 Command fb_version_remove 47

16 FAQ 49161 Why should I use the FileBrowser 49162 I want to use FileBrowser but I donrsquot want to use Grappelli 49163 I need help 49164 Why are there no fancy effects 49165 How do I upload to another server 49

ii

166 Why should I need image-versions 50167 Is the FileBrowser stable 50168 How can I contribute 50169 Who develops the FileBrowser 50

17 Troubleshooting 51171 Check your setup 51172 Run the FileBrowser tests 51173 Check issues 51174 Add a ticket 51

18 Translation 53

19 Supported Languages 55

20 FileBrowser 35 Release Notes 57201 Update from FileBrowser 34x 57

21 Changelog 59211 353 (not yet released) 59212 352 (February 22 2013) 59213 351 (November 09 2012) 59214 350 (July 20 2012) 60215 343 (2062012) 60216 342 (2632012) 60217 341 (732012) 60218 340 (15112011) 60

22 Main Features 61

23 Code 63

24 Discussion 65

25 Versions and Compatibility 67

iii

iv

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 3: Django FileBrowser Documentation

74 Folder attributes 2475 Version attributes 2476 Functions 26

8 Views 2781 Browse 2782 Create directory 2783 Upload 2784 Edit 2885 Confirm delete 2886 Delete 2887 Version 29

9 Signals 3191 filebrowser_pre_upload 3192 filebrowser_post_upload 3193 filebrowser_pre_delete 3194 filebrowser_post_delete 3295 filebrowser_pre_createdir 3296 filebrowser_post_createdir 3297 filebrowser_pre_rename 3298 filebrowser_post_rename 3299 filebrowser_actions_pre_apply 33910 filebrowser_actions_post_apply 33911 Example for using these Signals 33

10 FileBrowseField 35101 Attributes 35102 FileBrowseField in Templates 35103 Showing Thumbnail in the Changelist 36104 Using the FileBrowseField with TinyMCE 36

11 FileInput 37

12 ClearableFileInput 39

13 Django FileField and the FileBrowser 41

14 Image Versions 43141 Versions and the grid 43142 Versions with the admin-interface 43143 Versions on your website 44144 Versions in views 45145 Placeholder 45

15 Management Commands 47151 Command fb_version_generate 47152 Command fb_version_remove 47

16 FAQ 49161 Why should I use the FileBrowser 49162 I want to use FileBrowser but I donrsquot want to use Grappelli 49163 I need help 49164 Why are there no fancy effects 49165 How do I upload to another server 49

ii

166 Why should I need image-versions 50167 Is the FileBrowser stable 50168 How can I contribute 50169 Who develops the FileBrowser 50

17 Troubleshooting 51171 Check your setup 51172 Run the FileBrowser tests 51173 Check issues 51174 Add a ticket 51

18 Translation 53

19 Supported Languages 55

20 FileBrowser 35 Release Notes 57201 Update from FileBrowser 34x 57

21 Changelog 59211 353 (not yet released) 59212 352 (February 22 2013) 59213 351 (November 09 2012) 59214 350 (July 20 2012) 60215 343 (2062012) 60216 342 (2632012) 60217 341 (732012) 60218 340 (15112011) 60

22 Main Features 61

23 Code 63

24 Discussion 65

25 Versions and Compatibility 67

iii

iv

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 4: Django FileBrowser Documentation

166 Why should I need image-versions 50167 Is the FileBrowser stable 50168 How can I contribute 50169 Who develops the FileBrowser 50

17 Troubleshooting 51171 Check your setup 51172 Run the FileBrowser tests 51173 Check issues 51174 Add a ticket 51

18 Translation 53

19 Supported Languages 55

20 FileBrowser 35 Release Notes 57201 Update from FileBrowser 34x 57

21 Changelog 59211 353 (not yet released) 59212 352 (February 22 2013) 59213 351 (November 09 2012) 59214 350 (July 20 2012) 60215 343 (2062012) 60216 342 (2632012) 60217 341 (732012) 60218 340 (15112011) 60

22 Main Features 61

23 Code 63

24 Discussion 65

25 Versions and Compatibility 67

iii

iv

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 5: Django FileBrowser Documentation

iv

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 6: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

Media-Management with Grappelli

This documentation covers version 352 of the FileBrowser

Note FileBrowser 352 requires Django 1415 and Grappelli 24 FileBrowser is always developed against thelastest stable Django release and is NOT tested with Djangos trunk

Installation and Setup

Contents 1

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 7: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

2 Contents

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 8: Django FileBrowser Documentation

CHAPTER 1

Quick start guide

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

11 Requirements

bull Django 1415 httpwwwdjangoprojectcom

bull Grappelli 24 httpsgithubcomsehmaschinedjango-grappelli

bull PIL httpwwwpythonwarecomproductspil

12 Download

Using pip

pip install django-filebrowser

Go to httpsgithubcomsehmaschinedjango-filebrowser if you need to download a package or clone the repo

13 Installation

Changed in version 340 Open settingspy and add filebrowser to your INSTALLED_APPS (beforedjangocontribadmin)

INSTALLED_APPS = (rsquograppellirsquorsquofilebrowserrsquorsquodjangocontribadminrsquo

)

In your urlpy import the default FileBrowser site

from filebrowsersites import site

and add the following URL-patterns (before any admin-urls)

3

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 9: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

urlpatterns = patterns(rsquorsquourl(rrsquo^adminfilebrowserrsquo include(siteurls))

)

Collect the media files

python managepy collectstatic

Note Please refer to the Staticfiles Documentation for setting up and using staticfiles

14 Settings

Check the Settings You need to add a folder ldquouploadsrdquo within your MEDIA_ROOT when using the default settings

15 Testing

Run the FileBrowser tests

python managepy test filebrowser

Start the devserver and login to your admin site

python managepy runserver ltIP-addressgt8000

Goto adminfilebrowserbrowse and check if everything looksworks as expected If yoursquore having prob-lems see Troubleshooting

4 Chapter 1 Quick start guide

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 10: Django FileBrowser Documentation

CHAPTER 2

Settings

There are quite a few possibilities of customizing the FileBrowser to fit your needs Nonetheless you should be ableto start with the default settings

Note All settings can be defined in your projects settings-file or the FileBrowsers settings-file (settingspy)When using the projects settings-file you have to use the prefix FILEBROWSER_ for every setting (egFILEBROWSER_MEDIA_URL instead of MEDIA_URL)

21 Main URLPaths Settings

211 MEDIA_ROOT

The absolute path to the directory that holds the media-files you want to browse

MEDIA_ROOT = getattr(settings FILEBROWSER_MEDIA_ROOT settingsMEDIA_ROOT)

212 MEDIA_URL

URL that handles the media served from MEDIA_ROOT

MEDIA_URL = getattr(settings FILEBROWSER_MEDIA_URL settingsMEDIA_URL)

213 DIRECTORY (relative to MEDIA_ROOT)

Main FileBrowser Directory Leave empty in order to browse all files and folders within MEDIA_ROOT

DIRECTORY = getattr(settings FILEBROWSER_DIRECTORY rsquouploadsrsquo)

5

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 11: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

22 FileBrowser Media TinyMCE Media

221 URL_FILEBROWSER_MEDIA PATH_FILEBROWSER_MEDIA

The URL and Path to your FileBrowser media-files

URL_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_URL_FILEBROWSER_MEDIA settingsSTATIC_URL + filebrowser)PATH_FILEBROWSER_MEDIA = getattr(settings FILEBROWSER_PATH_FILEBROWSER_MEDIA ospathjoin(settingsSTATIC_ROOT rsquofilebrowserrsquo))

222 URL_TINYMCE PATH_TINYMCE

The URL to your TinyMCE Installation

URL_TINYMCE = getattr(settings FILEBROWSER_URL_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)PATH_TINYMCE = getattr(settings FILEBROWSER_PATH_TINYMCE settingsADMIN_MEDIA_PREFIX + tinymcejscriptstiny_mce)

Note Only change these settings if yoursquore absolutely sure about what yoursquore doing

23 Extensions and Formats

231 EXTENSIONS

Allowed extensions for file upload

EXTENSIONS = getattr(settings FILEBROWSER_EXTENSIONS rsquoFolderrsquo [rsquorsquo]rsquoImagersquo [rsquojpgrsquorsquojpegrsquorsquogifrsquorsquopngrsquorsquotifrsquorsquotiffrsquo]rsquoDocumentrsquo [rsquopdfrsquorsquodocrsquorsquortfrsquorsquotxtrsquorsquoxlsrsquorsquocsvrsquo]rsquoVideorsquo [rsquomovrsquorsquowmvrsquorsquompegrsquorsquompgrsquorsquoavirsquorsquormrsquo]rsquoAudiorsquo [rsquomp3rsquorsquomp4rsquorsquowavrsquorsquoaiffrsquorsquomidirsquorsquom4prsquo]

)

232 SELECT_FORMATS

Set different Options for selecting elements from the FileBrowser

SELECT_FORMATS = getattr(settings FILEBROWSER_SELECT_FORMATS rsquofilersquo [rsquoFolderrsquorsquoImagersquorsquoDocumentrsquorsquoVideorsquorsquoAudiorsquo]rsquoimagersquo [rsquoImagersquo]rsquodocumentrsquo [rsquoDocumentrsquo]rsquomediarsquo [rsquoVideorsquorsquoAudiorsquo]

)

When using the browse-function for selecting FilesFolders you can use an additional query-attribute type in orderto restrict the choices

6 Chapter 2 Settings

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 12: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

24 Versions

241 VERSIONS_BASEDIR (relative to MEDIA_ROOT)

Changed in version 340 Directory to save image versions (and thumbnails) If no directory is given versions arestored at the same location as the original image

VERSIONS_BASEDIR = getattr(settings rsquoFILEBROWSER_VERSIONS_BASEDIRrsquo rsquorsquo)

Note In versions previous to FileBrowser 34 it was possible to have VERSION_BASEDIR placed at a path whichwas not browsed by FileBrowser (by placing VERSION_BASEDIR anywhere else than under DIRECTORY)

However this is not possible as of FileBrowser 34 because DIRECTORY variable is not used anymore and File-Browser browses anything under MEDIA_ROOT If you donrsquot want FileBrowser to browsedisplay the contents ofVERSION_BASEDIR make this directory hidden

242 VERSIONS

Define the versions according to your websites grid

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

243 ADMIN_VERSIONS

The versions you want to show with the admin-interface

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

244 ADMIN_THUMBNAIL

The version being used as the admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

245 PLACEHOLDER

Path to placeholder image (relative to MEDIA_ROOT)

PLACEHOLDER = getattr(settings FILEBROWSER_PLACEHOLDER )

24 Versions 7

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 13: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

246 SHOW_PLACEHOLDER

Show Placeholder (instead of a Version) if the original image does not exist

SHOW_PLACEHOLDER = getattr(settings FILEBROWSER_SHOW_PLACEHOLDER False)

247 FORCE_PLACEHOLDER

Always show placeholder (even if the original image exists)

FORCE_PLACEHOLDER = getattr(settings FILEBROWSER_FORCE_PLACEHOLDER False)

25 Extra Settings

251 SAVE_FULL_URL

Deprecated since version 340 With custom storage engines saving the full URL (including MEDIA_ROOT) doesnrsquotmake sense anymore Moreover removing this settings allows for easily replacing a FileBrowseField with DjangosFile- or ImageField

252 STRICT_PIL

If set to True the FileBrowser will not try to import a mis-installed PIL

STRICT_PIL = getattr(settings rsquoFILEBROWSER_STRICT_PILrsquo False)

253 IMAGE_MAXBLOCK

see httpmailpythonorgpipermailimage-sig1999-August000816html

IMAGE_MAXBLOCK = getattr(settings rsquoFILEBROWSER_IMAGE_MAXBLOCKrsquo 10241024)

254 EXCLUDE

Exclude-patterns for files you donrsquot want to show

EXTENSION_LIST = []for exts in EXTENSIONSvalues()

EXTENSION_LIST += extsEXCLUDE = getattr(settings rsquoFILEBROWSER_EXCLUDErsquo (rrsquo_((exts)s)__qd13((exts)s)rsquo rsquoextsrsquo (rsquo|rsquojoin(EXTENSION_LIST))))

255 MAX_UPLOAD_SIZE

Max Upload Size in Bytes

MAX_UPLOAD_SIZE = getattr(settings FILEBROWSER_MAX_UPLOAD_SIZE 10485760)

8 Chapter 2 Settings

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 14: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

256 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)

257 LIST_PER_PAGE

How many items appear on each paginated list

LIST_PER_PAGE = getattr(settings FILEBROWSER_LIST_PER_PAGE 50)

258 DEFAULT_SORTING_BY

Default sorting attribute

DEFAULT_SORTING_BY = getattr(settings FILEBROWSER_DEFAULT_SORTING_BY date)

Options are date filesize filename_lower filetype_checked

259 DEFAULT_SORTING_ORDER

Default sorting order

DEFAULT_SORTING_ORDER = getattr(settings FILEBROWSER_DEFAULT_SORTING_ORDER desc)

Options are asc or desc

2510 FOLDER_REGEX

regex to clean dir names before creation

FOLDER_REGEX = getattr(settings FILEBROWSER_FOLDER_REGEX rrsquo^[w_ -]+$rsquo)

2511 SEARCH_TRAVERSE

New in version 33 True if you want to traverse all subdirectories when searching Please note that with thousandsof filesdirectories this might take a while

SEARCH_TRAVERSE = getattr(settings FILEBROWSER_SEARCH_TRAVERSE False)

2512 DEFAULT_PERMISSIONS

New in version 33 Default Upload and Version Permissions

DEFAULT_PERMISSIONS = getattr(settings FILEBROWSER_DEFAULT_PERMISSIONS 0755)

25 Extra Settings 9

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 15: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

2513 OVERWRITE_EXISTING

New in version 351 True in order to overwrite existing files False to use the behaviour of the storage engine

OVERWRITE_EXISTING = getattr(settings FILEBROWSER_OVERWRITE_EXISTING True)

FileBrowser Sites

10 Chapter 2 Settings

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 16: Django FileBrowser Documentation

CHAPTER 3

FileBrowser Sites

New in version 340 As of version 34 the FileBrowser application is respresented by an object offilebrowsersitesFileBrowserSite (in analogy to Djangorsquos admin site) FileBrowser sites allow youto

bull associate Custom Actions (analogy to Djangorsquos admin actions) to a site

bull define a file system storage for a site (allows for browsing remote file servers) ndash see File Storages

bull subclass from FileBrowserSite and redefine the default FileBrowserrsquos behavior

bull use multiple FileBrowser sites in your project

The module variable site from filebrowsersites is the default FileBrowser application

31 Backward Incompatibilites

The only thing that you need to pay attention to when migrating to FileBrowser 34 is the specification of your URL-patterns URL-patterns are now associated with a FileBrowser site that is each FileBrowser site can have differentURL-patterns See Quick start guide for how to setup your URL-patterns

11

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 17: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

12 Chapter 3 FileBrowser Sites

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 18: Django FileBrowser Documentation

CHAPTER 4

Custom Actions

New in version 340 In analogy to Djangorsquos admin actions you can define your FileBrowser actions and thusautomate the typical tasks of your users Registered custom actions are listed in the detail view of a file and a user canselect a single action at a time The selected action will then be applied to the file

The default FileBrowser image actions such as ldquoFlip Verticalrdquo or ldquoRotate 90deg Clockwiserdquo are in fact implemented ascustom actions (in the module filebrowseractions)

41 Writing Your Own Actions

Custom actions are simple functions of the form

def foo(request fileobjects) Do something with the fileobjects

the first parameter is an 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

In the current FileBrowser version the list contains exactly one instance of FileObject (representing the file from thedetail view) but this may change in the future as custom actions may become available also in browse views (similarto admin actions applied to a list of checked objects)

42 Registering an Action

In order to make your action visible you need to register it at a FileBrowser site (see also FileBrowser Sites)

siteadd_action(foo)

Once registered the action will appear in the detail view of a file You can also give your action a short description

fooshort_description = rsquoDo foo with the Filersquo

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

13

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 19: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

43 Associating Actions with Specific Files

Each custom action can be associated with a specific file type (eg images audio file etc) to which it applies In orderto do that you need to define a predicatefilter function which takes a single argument ndash a FileObject ndash and returnsTrue if your action is applicable to that FileObject Finally you need to register this filter function with your action

fooapplies_to(lambda fileobject fileobjectfiletype == rsquoImagersquo)

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

44 Messages amp Intermediate Pages

You can provide a feedback to a user about or successful or failed execution of an action by registering a message atthe request object For example

from djangocontrib import messages

def desaturate_image(request fileobjects)for f in fileobjects

Desaturate the imagemessagesadd_message(request messagesSUCCESS _(Image rsquosrsquo was desaturated) ffilename)

Some actions may require user confirmation (eg in order to prevent accidental and irreversible modification to files)In order to that follow the same pattern as with Djangorsquos admin action and return an HttpResponse object fromyour action Good practice for intermediate pages is to implement a confirm view and have your action return anHttpResponseRedirect object redirecting a user to that view

def crop_image(request fileobjects)files = rsquoampf=rsquojoin([fpath_relative for f in fileobjects])return HttpResponseRedirect(rsquoconfirmaction=crop_imageampf=srsquo files)

14 Chapter 4 Custom Actions

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 20: Django FileBrowser Documentation

CHAPTER 5

File Storages

New in version 340 Starting with FileBrowser 34 you have the option to specify which file storage enginea FileBrowser should use to browseuploadmodify your media files This enables you to use a FileBrowsereven if your media files are located at some remote system See also the Djangorsquos documentation on storageshttpsdocsdjangoprojectcomendevtopicsfiles

To associate a FileBrowser site with a particular storage set the storage property of a site object

from djangocorefilesstorage import FileSystemStoragesitestorage = FileSystemStorage(location=rsquopathtomediadirectoryrsquo base_url=rsquomediarsquo)

For storage classes other than FileSystemStorage (or those that inherit from that class) therersquos a little bit more effortinvolved in providing a storage object that can be used with FileBrowser See StorageMixin Class

Note Prior FileBrowser 34 the way to specify FileBrowserlsquos MEDIA_ROOT and MEDIA_URL was viasettingspy Starting from version 34 those variables are associated with the storage instance and you canset them as illustrated in the above example

Warning For the reason of backward compatibility FileBrowser settings FILEBROWSER_MEDIA_ROOT andFILEBROWSER_MEDIA_URL can still be used to customize FileBrowser as long as yoursquore using the defaultFileBrowserlsquos site without having changed its storage engine In the next major release of FileBrowser thesesettings will be removed

51 StorageMixin Class

A FileBrowser uses the Djangorsquos Storage class to access media files However the API of the Storageclass does not provide all methods necessary for FileBrowserrsquos functionality A StorageMixin class fromfilebrowserstorage 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)

15

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 21: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

Moves safely a file from one location to another If allow_ovewrite==False and new_file_name ex-ists raises an exception

makedirs(self name)Creates all missing directories specified by name Analogue to osmkdirs()

rmtree(self name)Deletes a directory and everything it contains Analogue to shutilrmtree()

Note FileBrowser provides these methods only for FileSystemStorage (by mixing-in thefilebrowserstorageFileSystemStorageMixin class) If yoursquore using a custom storage enginewhich does not inherit from Djangorsquos FileSystemStorage you will need to provide those method yourself

FileBrowser API

16 Chapter 5 File Storages

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 22: Django FileBrowser Documentation

CHAPTER 6

FileListing class

The FileListing is a group of FileObjects for a given directory

filelisting = FileListing(path filter_func=None sorting_by=None sorting_order=None)

For example if you want to list all files for MEDIA_ROOT you can type

from filebrowsersettings import MEDIA_ROOTfilelisting = FileListing(MEDIA_ROOT sorting_by=rsquodatersquo sorting_order=rsquodescrsquo)

61 Options

611 filter_func

Filter function based on a FileObject

def filter_filelisting(item)return itemfiletype = Folder

612 sorting_by

Sort the files by any attribute of FileObject (eg filetype date )

613 sorting_order

Sorting order either asc or desc

62 Attributes

For the below examples wersquore using this folder-structure and filter_browse as filter_func (seeviewspy)

17

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 23: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

mediauploadstestfoldertestimagejpgmediauploadsblog1imagesblogimagejpg

621 listing

Returns all items for the given path with oslistdir(path)

gtgtgt for item in filelistinglisting() print itemblogtestfolder

622 walk

Returns all items for the given path with oswalk(path)

gtgtgt for item in filelistingwalk() print itemblogblog1blog1imagesblog1imagesblogimagejpgblog1imagesblogimage_admin_thumbnailjpgblog1imagesblogimage_mediumjpgblog1imagesblogimage_smalljpgblog1imagesblogimage_thumbnailjpgtestfoldertestfoldertestimagejpg

623 files_listing_total

Returns a sorted list of FileObjects for selflisting()

gtgtgt for item in filelistingwalk() print itemuploadsbloguploadstestfolder

624 files_walk_total

Returns a sorted list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_total() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadsblog1imagesblogimage_admin_thumbnailjpguploadsblog1imagesblogimage_mediumjpguploadsblog1imagesblogimage_smalljpguploadsblog1imagesblogimage_thumbnailjpg

18 Chapter 6 FileListing class

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 24: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

uploadstestfolderuploadstestfoldertestimagejpg

625 files_listing_filtered

Returns a sorted and filtered list of FileObjects for selflisting()

gtgtgt for item in filelistingfiles_listing_filtered() print itemuploadsbloguploadstestfolder

626 files_walk_filtered

Returns a sorted and filtered list of FileObjects for selfwalk()

gtgtgt for item in filelistingfiles_walk_filtered() print itemuploadsbloguploadsblog1uploadsblog1imagesuploadsblog1imagesblogimagejpguploadstestfolderuploadstestfoldertestimagejpg

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

627 results_listing_total

Number of total files based on files_listing_total

gtgtgt filelistingresults_listing_total()2

628 results_walk_total

Number of total files based on files_walk_total

gtgtgt filelistingresults_listing_total()10

629 results_listing_filtered

Number of filtered files based on files_listing_filtered

gtgtgt filelistingresults_listing_filtered()2

62 Attributes 19

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 25: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

6210 results_walk_filtered

Number of filtered files based on files_walk_filtered

gtgtgt filelistingresults_walk_filtered()6

20 Chapter 6 FileListing class

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 26: Django FileBrowser Documentation

CHAPTER 7

FileObject class

When browsing a directory on the server you get a FileObject (see basepy) for every file within that directoryThe FileObject is also returned when using the FileBrowseField

fileobject = FileObject(relativeserverpathtostoragelocationfileext)

For the examples below we use

fileobject = FileObject(ospathjoin(MEDIA_ROOTDIRECTORYtestfoldertestimagejpg))

71 General attributes

711 filename

Name of the file (including the extension) or name of the folder

gtgtgt print fileobjectfilenamersquotestimagejpgrsquo

712 filetype

Type of the file as defined with EXTENSIONS With a folder the filetype is ldquoFolderrdquo

gtgtgt print fileobjectfiletypersquoImagersquo

713 mimetype

New in version 33 Mimetype based on httpdocspythonorglibrarymimetypeshtml

gtgtgt print fileobjectmimetype(rsquoimagejpegrsquo None)

21

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 27: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

714 filesize

Filesize in Bytes Display with filesizeformat

gtgtgt print fileobjectfilesize870037L

715 extension

File extension including the dot With a folder the extensions is None

gtgtgt print fileobjectextensionrsquojpgrsquo

716 date

Date based on getmtime

gtgtgt print fileobjectdate12997603470

717 datetime

Datetime object

gtgtgt print fileobjectdatetimedatetimedatetime(2011 3 10 13 32 27)

72 Path and URL attributes

721 path

Absolute server path to the filefolder including MEDIA_ROOT

gtgtgt print fileobjectpathrsquovarwwwtestsitemediauploadstestfoldertestimagejpgrsquo

722 path_relative

Server path to the filefolder relative to MEDIA_ROOT

gtgtgt print fileobjectpath_relativeursquouploadstestfoldertestimagejpgrsquo

723 url_full

Deprecated since version 33 Use url instead

22 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 28: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

724 url

New in version 33 URL for the filefolder including MEDIA_URL

gtgtgt print fileobjecturlursquomediauploadstestfoldertestimagejpgrsquo

725 url_relative

URL for the filefolder relative to MEDIA_URL

gtgtgt print fileobjecturl_relativeursquouploadstestfoldertestimagejpgrsquo

726 url_save

URL for the filefolder based on the setting SAVE_FULL_URL used for the FileBrowseField (either url orurl_relative)

gtgtgt print fileobjecturl_saveursquouploadstestfoldertestimagejpgrsquo

73 Image attributes

731 dimensions

Image dimensions as a tuple

gtgtgt print fileobjectdimensions(1000 750)

732 width

Image width in px

gtgtgt print fileobjectwidth1000

733 height

Image height in px

gtgtgt print fileobjectheight750

73 Image attributes 23

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 29: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

734 aspectratio

Aspect ratio (float format)

gtgtgt print fileobjectaspectratio133534908

735 orientation

Image orientation either ldquolandscaperdquo or ldquoportraitrdquo

gtgtgt print fileobjectorientationrsquoLandscapersquo

74 Folder attributes

741 folder

gtgtgt print fileobjectfolderursquotestfolderrsquo

742 is_folder

true if path is a folder

gtgtgt print fileobjectis_folderFalse

743 is_empty

true if the folder is empty

gtgtgt print fileobjectis_empty

75 Version attributes

751 is_version

true if the File is a version of another File

gtgtgt print fileobjectis_versionFalse

24 Chapter 7 FileObject class

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 30: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

752 version_basedir

The absolute path to the versions-folder

gtgtgt print fileobjectversion_basedirrsquovarwwwtestsitemediauploadstestfolderrsquo

753 version_name(version_suffix)

Get the filename for a version

gtgtgt print fileobjectversion_name(medium)rsquotestimage_mediumjpgrsquo

Note The version is not being generated

754 versions()

List all filenames based on VERSIONS

gtgtgt print fileobjectversions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_admin_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

755 admin_versions()

List all filenames based on ADMIN_VERSIONS

gtgtgt print fileobjectadmin_versions()[rsquovarwwwtestsitemediauploadstestfoldertestimage_thumbnailjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_smalljpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_mediumjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_bigjpgrsquorsquovarwwwtestsitemediauploadstestfoldertestimage_largejpgrsquo]

Note The versions are not being generated

756 version_generate(version_suffix)

Generate a version

gtgtgt print fileobjectversion(medium)uploadstestfoldertestimage_mediumjpg

75 Version attributes 25

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 31: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

76 Functions

761 delete()

Delete the File or Folder from the server

Warning If you delete a Folder all items within the folder are being deleted Be very careful with using this

762 delete_versions()

Delete all VERSIONS

763 delete_admin_versions()

Delete all ADMIN_VERSIONS

Admin Interface

26 Chapter 7 FileObject class

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 32: Django FileBrowser Documentation

CHAPTER 8

Views

All views use the staff_member_requird and path_exists decorator in order to check if the server pathactually exists Some views also use the file_exists decorator

81 Browse

Browse a directory on your server Returns a FileListing class

httpmysitecomadminurlfilebrowserbrowse

bull URL fb_browse

bull Optional query string args dir o ot q p filter_date filter_type type

82 Create directory

Create a new folder on your server

httpmysitecomadminurlfilebrowsercreatedir

bull URL fb_createdir

bull Optional query string args dir

bull Signals filebrowser_pre_createdir filebrowser_post_createdir

83 Upload

Multiple upload

httpmysitecomadminurlfilebrowserupload

bull URL fb_upload

bull Optional query string args dir

bull Signals filebrowser_pre_upload filebrowser_post_upload

27

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 33: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

84 Edit

Edit a file or folder

httpmysitecomadminurlfilebrowsereditfilename=testimagejpg

bull URL fb_edit

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_rename filebrowser_post_rename

You are able to apply custom actions (see Custom Actions) to the edit-view

Note This wonrsquot check if you use the file or folder anywhere with your models

85 Confirm delete

Confirm the deletion of a file or folder

httpmysitecomadminurlfilebrowserconfirm_deletefilename=testimagejpg

bull URL fb_confirm_delete

bull Required query string args filename

bull Optional query string args dir

Note If you try to delete a folder all filesfolders within this folder are listed on this page

86 Delete

Delete a file or folder

httpmysitecomadminurlfilebrowserdeletefilename=testimagejpg

bull URL fb_delete

bull Required query string args filename

bull Optional query string args dir

bull Signals filebrowser_pre_delete filebrowser_post_delete

Note This wonrsquot check if you use the file or folder anywhere with your models

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

28 Chapter 8 Views

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 34: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

87 Version

Generate a version of an Image as defined with ADMIN_VERSIONS

httpmysitecomadminurlfilebrowserversionfilename=testimagejpg

bull URL fb_version

bull Required query string args filename

bull Query string args dir

Note This is a helper used by the FileBrowseField and TinyMCE for selecting an Image-Version

87 Version 29

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 35: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

30 Chapter 8 Views

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 36: Django FileBrowser Documentation

CHAPTER 9

Signals

The FileBrowser sends a couple of different signals

91 filebrowser_pre_upload

Sent before a an Upload starts Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

92 filebrowser_post_upload

Sent after an Upload has finished Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

93 filebrowser_pre_delete

Sent before an Item (File Folder) is deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

31

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 37: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

94 filebrowser_post_delete

Sent after an Item (File Folder) has been deleted Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull site Current FileBrowserSite instance

95 filebrowser_pre_createdir

Sent before a new Folder is created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

96 filebrowser_post_createdir

Sent after a new Folder has been created Arguments

bull path Absolute server path to the folder

bull name Name of the new folder

bull site Current FileBrowserSite instance

97 filebrowser_pre_rename

Sent before an Item (File Folder) is renamed Arguments

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

98 filebrowser_post_rename

Sent after an Item (File Folder) has been renamed

bull path Absolute server path to the filefolder

bull name Name of the filefolder

bull new_name New name of the filefolder

bull site Current FileBrowserSite instance

32 Chapter 9 Signals

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 38: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

99 filebrowser_actions_pre_apply

Sent before a custom action is applied Arguments

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action will be applied to

bull site Current FileBrowserSite instance

910 filebrowser_actions_post_apply

Sent after a custom action has been applied

bull action_name Name of the custom action

bull fileobjects A list of fileobjects the action has been be applied to

bull results The response you defined with your custom action

bull site Current FileBrowserSite instance

911 Example for using these Signals

Herersquos a small example for using the above Signals

from filebrowser import signals

def pre_upload_callback(sender kwargs)Receiver function called before an upload startsprint Pre Upload Callbackprint kwargs kwargs

signalsfilebrowser_pre_uploadconnect(pre_upload_callback)

def post_upload_callback(sender kwargs)Receiver function called each time an upload has finishedprint Post Upload Callbackprint kwargs kwargs You can use all attributes available with the FileObject This is just an example print Filesize kwargs[rsquofilersquo]filesizeprint Orientation kwargs[rsquofilersquo]orientationprint Extension kwargs[rsquofilersquo]extension

signalsfilebrowser_post_uploadconnect(post_upload_callback)

Fields and Widgets

99 filebrowser_actions_pre_apply 33

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 39: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

34 Chapter 9 Signals

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 40: Django FileBrowser Documentation

CHAPTER 10

FileBrowseField

The FileBrowseField is a Model field for selecting a file from your Media Server

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)

image = FileBrowseField(Image max_length=200 directory=images extensions=[jpg] blank=True null=True)document = FileBrowseField(PDF max_length=200 directory=documents extensions=[pdfdoc] blank=True null=True)

101 Attributes

max_length Since the FileBrowseField is a CharField you have to define max_length

site (optional) The FileBrowser site you want to use with this field Defaults to the main site if not given

directory (optional) Subdirectory of DIRECTORY If DIRECTORY is not defined subdirectory ofMEDIA_ROOT Do not prepend a slash

extensions (optional) List of allowed extensions

format (optional) Use this attribute to restrict selection to specific filetypes Eg if you use format=rsquoimagersquo onlyImages can be selected from the FileBrowser Note The format has to be defined within SELECT_FORMATS

102 FileBrowseField in Templates

When using a FileBrowseField yoursquoll get a FileObject class back

With the above Model you can use

blogentryimage

to output the contents of your image-field For example this could result in something like ldquomyimagejpgrdquo

Now if you want to actually display the Image you write

35

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 41: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

ltimg src= publicationimageurl gt

More complicated if you want to display ldquoLandscaperdquo Images only

ifequal blogentryimageimage_orientation landscape ltimg src= blogentryimageurl class=landscape gt

endifequal

103 Showing Thumbnail in the Changelist

If you want to show a Thumbnail in the Changelist you can define a Model-Admin-Method

from filebrowsersettings import ADMIN_THUMBNAIL

def image_thumbnail(self obj)if objimage and objimagefiletype == Image

return rsquoltimg src=s gtrsquo objimageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

104 Using the FileBrowseField with TinyMCE

You can also replace the TinyMCE ImageFile Manager with the FileBrowser What you haveto do is a FileBrowser Callback Therersquos an example in mediajs called TinyMCEAdminjs (aTinyMCE Configuration File) You can copy the FileBrowserCallback to your own file take a look athttpwikimoxiecodecomindexphpTinyMCECustom_filebrowser or just use tinymce_setupjs (which comes withdjango-grappelli)

Just add these lines to your AdminModel

class Mediajs = [rsquopathtotinymcejscriptstiny_mcetiny_mcejsrsquo rsquopathtoyourtinymce_setupjsrsquo]

36 Chapter 10 FileBrowseField

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 42: Django FileBrowser Documentation

CHAPTER 11

FileInput

Subclass of FileInput with an additional Image-Thumbnail

from filebrowserwidgets import FileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo FileInput

37

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 43: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

38 Chapter 11 FileInput

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 44: Django FileBrowser Documentation

CHAPTER 12

ClearableFileInput

Subclass of ClearableFileInput with an additional Image-Thumbnail

from filebrowserwidgets import ClearableFileInput

class BlogEntryOptions(adminModelAdmin)formfield_overrides =

modelsImageField rsquowidgetrsquo ClearableFileInput

39

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 45: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

40 Chapter 12 ClearableFileInput

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 46: Django FileBrowser Documentation

CHAPTER 13

Django FileField and the FileBrowser

Generate a FileObject from a FileField or ImageField with

from filebrowserbase import FileObject

image_upload = modelsImageField(uImage (Upload) max_length=250 upload_to=image_upload_path blank=True null=True)

def image(self)if selfimage_upload

return FileObject(selfimage_uploadpath)return None

To show a Thumbnail on your changelist you could use a ModelAdmin-Method

from filebrowserbase import FileObject

def image_thumbnail(self obj)if objimage_upload

image = FileObject(objimage_uploadpath)if imagefiletype == Image

return rsquoltimg src=s gtrsquo imageversion_generate(ADMIN_THUMBNAIL)urlelse

return image_thumbnailallow_tags = Trueimage_thumbnailshort_description = Thumbnail

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

Image Versions

41

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 47: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

42 Chapter 13 Django FileField and the FileBrowser

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 48: Django FileBrowser Documentation

CHAPTER 14

Image Versions

With the FileBrowser you are able to define different versionssizes for Images This enables you to save an OriginalImage on your Server while having different versions of that Image to automatically fit your websites Grid Versionsare also useful for responsiveadaptive layouts

141 Versions and the grid

First you need to know which versionssizes of an image yoursquod like to use on your website Letrsquos say yoursquore using a12 column grid with 60px for each column and 20px margin (which is a total of 940px) With this grid you could (forexample) generate these image versions

VERSIONS = getattr(settings FILEBROWSER_VERSIONS rsquoadmin_thumbnailrsquo rsquoverbose_namersquo rsquoAdmin Thumbnailrsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquothumbnailrsquo rsquoverbose_namersquo rsquoThumbnail (1 col)rsquo rsquowidthrsquo 60 rsquoheightrsquo 60 rsquooptsrsquo rsquocroprsquorsquosmallrsquo rsquoverbose_namersquo rsquoSmall (2 col)rsquo rsquowidthrsquo 140 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquomediumrsquo rsquoverbose_namersquo rsquoMedium (4col )rsquo rsquowidthrsquo 300 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquorsquolargersquo rsquoverbose_namersquo rsquoLarge (8 col)rsquo rsquowidthrsquo 680 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo

)

New in version 340 methods If you need to add some filter for the version (like grayscale sepia ) you can alsouse the methods argument

def grayscale(im)rsquorsquorsquoConvert the PIL image to grayscalersquorsquorsquoif immode = L

im = imconvert(L)return im

FILEBROWSER_VERSIONS = rsquobigrsquo rsquoverbose_namersquo rsquoBig (6 col)rsquo rsquowidthrsquo 460 rsquoheightrsquo rsquorsquo rsquooptsrsquo rsquorsquo rsquomethodsrsquo [grayscale]

)

142 Versions with the admin-interface

With the admin-interface you need to define ADMIN_VERSIONS

43

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 49: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

ADMIN_VERSIONS = getattr(settings rsquoFILEBROWSER_ADMIN_VERSIONSrsquo [rsquothumbnailrsquo rsquosmallrsquo rsquomediumrsquo rsquobigrsquo rsquolargersquo])

Donrsquot forget to select one version for your admin-thumbnail

ADMIN_THUMBNAIL = getattr(settings rsquoFILEBROWSER_ADMIN_THUMBNAILrsquo rsquoadmin_thumbnailrsquo)

143 Versions on your website

In order to generate versions you have two different tags to choose from version and version_object Witheither using the version-tag or the version_object-tag the Image-version will be generated ldquoon the flyrdquo if the versiondoesnrsquot already exist or if the original Image is newer than the version This means that if you need to update an Imageyou just overwrite the original Image - the versions will be re-generated automatically (as you request them withinyour template)

A Model example

from filebrowserfields import FileBrowseField

class BlogEntry(modelsModel)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 astring use quotes

1431 Templatetag version

Generate a version and retrieve the URL

version modelfield_name version_prefix

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

version blogentryimage rsquomediumrsquo

Since you retrieve the URL you can display the image with

ltimg src= version blogentryimage rsquomediumrsquo gt

1432 Templatetag version_object

Generate a version and retrieve the FileObject

version_object modelfield_name version_prefix as variable

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

44 Chapter 14 Image Versions

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 50: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

version_object blogentryimage rsquomediumrsquo as version_medium

Since you retrieve a FileObject you can use all attributes

version_mediumwidth

or just

ltimg src= version_medium gt

144 Versions in views

If you have a FileObject you can easily generateretrieve a version with

objimageversion(version_prefix)

So if you need to generateretrieve the admin thumbnail for an Image you can type

from filebrowsersettings import ADMIN_THUMBNAILobjimageversion_generate(ADMIN_THUMBNAIL)url

145 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 thePLACEHOLDER and overwrite the settings SHOW_PLACEHOLDER andor FORCE_PLACEHOLDER (see PLACE-HOLDER)

144 Versions in views 45

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 51: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

46 Chapter 14 Image Versions

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 52: Django FileBrowser Documentation

CHAPTER 15

Management Commands

151 Command fb_version_generate

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

python managepy fb_version_generate

152 Command fb_version_remove

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

python managepy fb_version_remove

Warning Please be very careful with this command

Help

47

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 53: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

48 Chapter 15 Management Commands

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 54: Django FileBrowser Documentation

CHAPTER 16

FAQ

Some questions some answers

161 Why should I use the FileBrowser

If you need your editors or customer to manage files the FileBrowser is an alternative to an FTP-client Moreoverwith the FileBrowser you are able to define different image-versions according to your websites grid Alternatives tothe FileBrowser can be found at httpdjangopackagescomgridsgfile-managers

162 I want to use FileBrowser but I donrsquot want to use Grappelli

Grappelli is a requirement for using the FileBrowser There are several filebrowser-no-grappelli versions (most ofthem on GitHub) but we donrsquot follow the development

163 I need help

see Troubleshooting

164 Why are there no fancy effects

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

165 How do I upload to another server

Use a custom storage engine see httpsdocsdjangoprojectcomen13howtocustom-file-storage

49

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 55: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

166 Why should I need image-versions

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

167 Is the FileBrowser stable

Wersquove developed the FileBrowser for a couple of years and use it with almost all of our clients That said Grappelli isthe more stable and mature application

168 How can I contribute

Help is very much needed and appreciated Test the FileBrowser and submit feedbackpatches

169 Who develops the FileBrowser

The FileBrowser is developed and maintained by Patrick Kranzlmuumlller amp Axel Swoboda of vonautomatisch

50 Chapter 16 FAQ

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 56: Django FileBrowser Documentation

CHAPTER 17

Troubleshooting

Sometimes you might have a problem installingusing the FileBrowser

171 Check your setup

First please check if the problem is caused by your setup

bull Read Quick start guide

bull Check if the staticmedia-files are served correctly

bull Make sure you have removed all customized filebrowser templates from all locations in TEMPLATE_DIRSpaths or check that these templates are compatible with the FileBrowser

172 Run the FileBrowser tests

Start the shell and type

python managepy test filebrowser

173 Check issues

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

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

174 Add a ticket

If you think yoursquove found a bug please add a ticket

bull Try to describe your problem as precisely as possible

bull Tell us what you did in order to solve the problem

51

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 57: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

bull Tell us what version of the FileBrowser you are using

bull Tell us what version of Django you are using

bull Please do NOT add tickets if yoursquore having problems with serving staticmedia-files (because this is not relatedto the FileBrowser)

bull Please do NOT add tickets referring to Djangos trunk version

bull At best add a patch

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

52 Chapter 17 Troubleshooting

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 58: Django FileBrowser Documentation

CHAPTER 18

Translation

New in version 33 Translation is done via Transifex

53

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 59: Django FileBrowser Documentation

Django FileBrowser Documentation Release 352

54 Chapter 18 Translation

CHAPTER 19

Supported Languages

see httpswwwtransifexnetprojectspdjango-filebrowserresourcedjangopo

55

Django FileBrowser Documentation Release 352

56 Chapter 19 Supported Languages

CHAPTER 20

FileBrowser 35 Release Notes

FileBrowser 35 is compatible with Django 1415 and Grappelli 24

201 Update from FileBrowser 34x

bull Update Django to 14 or 15 and check httpsdocsdjangoprojectcomendevreleases14 orhttpsdocsdjangoprojectcomendevreleases15

bull Update Grappelli to 24x

bull Update FileBrowser to 35x

57

Django FileBrowser Documentation Release 352

58 Chapter 20 FileBrowser 35 Release Notes

CHAPTER 21

Changelog

211 353 (not yet released)

212 352 (February 22 2013)

bull Fixed Use placeholder with version_generate (not only templatetags)

bull Fixed translate extension group name in upload form

bull Fixed updated filter dropdown HTML

bull Fixed Make setuppy work with Python 3

bull Fixed File submit with search traversal

bull Fixed Fixed fileobject path with Windows

bull Improved Throwing an exception when in DEBUG and version is not generated (with using the templatetag)

bull Compatibility with Django 15

213 351 (November 09 2012)

bull Fixed Documentation with Signals

bull Fixed File Upload using basic submission

bull Fixed Added site instance to Signals

bull Improved Donrsquot hide errors during generate-command

bull Improved Follow symlinks with generate-command

bull Improved Added some translations (eg for ldquoUpload Filerdquo)

bull New Setting OVERWRITE_EXISTING

bull New Added file lsquolsquosignalspylsquo

bull New Support for Django 15

59

Django FileBrowser Documentation Release 352

214 350 (July 20 2012)

bull Compatibility with Django 14 and Grappelli 24

215 343 (2062012)

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

216 342 (2632012)

bull Fixed security bug added staff_member_required decorator to the upload-function

bull Fixed a XSS vulnerability with fb_tags

217 341 (732012)

bull Fixed an error with quotes (french translation) in uploadhtml

bull Updated translations

bull FileObject now returns path (with __unicode__ and __str__) instead of filename This is needed becauseotherwise formhas_changed will always be triggerde when using a FileBrowseField

bull Fixed a bug with versions and ldquof referenced before assignmentrdquo (eg when an image is being deleted)

bull Updated docs (warning that FILEBROWSER_MEDIA_ROOT and FILEBROWSER_MEDIA_URL will be re-moved with the next major release ndash use custom storage engine instead)

bull Fixed issue with MEDIA_URL hardcoded in tests

bull Fixed issue when MEDIA_URL starts with https

bull Fixed issue with default-site (if no site is given)

bull Fixed bug with using L10N and MAX_UPLOAD_SIZE in uploadhtml

bull Fixed small bug with importing Http404 in sitespy

bull Fixed bug with Fileobjectexists

bull Added NORMALIZE_FILENAME

218 340 (15112011)

bull Final release of 34 see FileBrowser 35 Release Notes

60 Chapter 21 Changelog

CHAPTER 22

Main Features

bull Browse your media files with the admin-interface

bull Multiple Upload including a progress bar

bull Automatic Thumbnails

bull Image-Versions to fit your websites grid (esp useful with adaptiveresponsive layouts)

bull Integration with TinyMCE (AdvImage amp AdvLink)

bull FileBrowseField to select ImagesDocuments

bull FileInput and ClearableFileInput with Image-Preview

bull Signals for Upload Rename and Delete

bull Custom Actions

bull Custom File Storage Engines

61

Django FileBrowser Documentation Release 352

62 Chapter 22 Main Features

CHAPTER 23

Code

httpsgithubcomsehmaschinedjango-filebrowser

63

Django FileBrowser Documentation Release 352

64 Chapter 23 Code

CHAPTER 24

Discussion

Use the FileBrowser Google Group to ask questions or discuss features

65

Django FileBrowser Documentation Release 352

66 Chapter 24 Discussion

CHAPTER 25

Versions and Compatibility

bull FileBrowser 353 (Development Version not yet released see Branch Stable35x)

bull FileBrowser 352 (February 22 2013) Compatible with Django 1415

bull FileBrowser 343 (April 2012) Compatible with Django 13

Older versions are availabe at GitHub but are not supported anymore

67

  • Quick start guide
    • Requirements
    • Download
    • Installation
    • Settings
    • Testing
      • Settings
        • Main URLPaths Settings
        • FileBrowser Media TinyMCE Media
        • Extensions and Formats
        • Versions
        • Extra Settings
          • FileBrowser Sites
            • Backward Incompatibilites
              • Custom Actions
                • Writing Your Own Actions
                • Registering an Action
                • Associating Actions with Specific Files
                • Messages amp Intermediate Pages
                  • File Storages
                    • StorageMixin Class
                      • FileListing class
                        • Options
                        • Attributes
                          • FileObject class
                            • General attributes
                            • Path and URL attributes
                            • Image attributes
                            • Folder attributes
                            • Version attributes
                            • Functions
                              • Views
                                • Browse
                                • Create directory
                                • Upload
                                • Edit
                                • Confirm delete
                                • Delete
                                • Version
                                  • Signals
                                    • filebrowser_pre_upload
                                    • filebrowser_post_upload
                                    • filebrowser_pre_delete
                                    • filebrowser_post_delete
                                    • filebrowser_pre_createdir
                                    • filebrowser_post_createdir
                                    • filebrowser_pre_rename
                                    • filebrowser_post_rename
                                    • filebrowser_actions_pre_apply
                                    • filebrowser_actions_post_apply
                                    • Example for using these Signals
                                      • FileBrowseField
                                        • Attributes
                                        • FileBrowseField in Templates
                                        • Showing Thumbnail in the Changelist
                                        • Using the FileBrowseField with TinyMCE
                                          • FileInput
                                          • ClearableFileInput
                                          • Django FileField and the FileBrowser
                                          • Image Versions
                                            • Versions and the grid
                                            • Versions with the admin-interface
                                            • Versions on your website
                                            • Versions in views
                                            • Placeholder
                                              • Management Commands
                                                • Command fb_version_generate
                                                • Command fb_version_remove
                                                  • FAQ
                                                    • Why should I use the FileBrowser
                                                    • I want to use FileBrowser but I dont want to use Grappelli
                                                    • I need help
                                                    • Why are there no fancy effects
                                                    • How do I upload to another server
                                                    • Why should I need image-versions
                                                    • Is the FileBrowser stable
                                                    • How can I contribute
                                                    • Who develops the FileBrowser
                                                      • Troubleshooting
                                                        • Check your setup
                                                        • Run the FileBrowser tests
                                                        • Check issues
                                                        • Add a ticket
                                                          • Translation
                                                          • Supported Languages
                                                          • FileBrowser 35 Release Notes
                                                            • Update from FileBrowser 34x
                                                              • Changelog
                                                                • 353 (not yet released)
                                                                • 352 (February 22 2013)
                                                                • 351 (November 09 2012)
                                                                • 350 (July 20 2012)
                                                                • 343 (2062012)
                                                                • 342 (2632012)
                                                                • 341 (732012)
                                                                • 340 (15112011)
                                                                  • Main Features
                                                                  • Code
                                                                  • Discussion
                                                                  • Versions and Compatibility
Page 60: Django FileBrowser Documentation
Page 61: Django FileBrowser Documentation
Page 62: Django FileBrowser Documentation
Page 63: Django FileBrowser Documentation
Page 64: Django FileBrowser Documentation
Page 65: Django FileBrowser Documentation
Page 66: Django FileBrowser Documentation
Page 67: Django FileBrowser Documentation
Page 68: Django FileBrowser Documentation
Page 69: Django FileBrowser Documentation
Page 70: Django FileBrowser Documentation
Page 71: Django FileBrowser Documentation
Page 72: Django FileBrowser Documentation