Transcript
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
top related