Package: django-adminfiles
A file upload manager and picker for the Django admin, with support
for browsing and embedding from Flickr, Youtube, Vimeo, etc.Upload files and view uploaded files (with thumbnails) in a
file-picker underneath any content textarea. Click on a file to add a
reference to it into the content area.Inline file references can be customized per-mime-type to automate the
correct presentation of each file: <img> tags (with additional markup
as needed) for images, links for downloadable files, even embedded
players for audio or video files. Seethe screencast.InstallationInstall from PyPI witheasy_installorpip:pip install django-adminfilesor get the in-development version:pip install http://bitbucket.org/carljm/django-adminfiles/get/tip.gzDependenciesdjango-adminfilesrequiresDjango1.4 or later,sorl-thumbnail11.12 (not compatible with old 3.x series)
and thePython Imaging Library.djangoembedordjango-oembedis required for OEmbed
functionality.flickrapiis required for browsing Flickr photos,gdatafor Youtube videos.UsageTo use django-adminfiles in your Django project:Add'adminfiles'to yourINSTALLED_APPSsetting. Also
add'sorl.thumbnail'if you have not installed it already.Runpython manage.py syncdbto to create the adminfiles database
tables.Make the contents of theadminfiles/static/adminfilesdirectory
available atSTATIC_URL/adminfiles.  This can be done by through
your webserver configuration, via an app such asdjango.contrib.staticfiles, or by copying the files or making a
symlink.Addurl(r'^adminfiles/',include('adminfiles.urls'))in your
root URLconf.Inherit content model admin options fromFilePickerAdmin.In addition, you may want to set theTHUMBNAIL_EXTENSIONsetting forsorl-thumbnailto"png"rather than the default"jpg", so that
images with alpha transparency aren’t broken when thumbnailed in the
adminfiles file-picker.FilePickerAdminFor each model you’d like to use thedjango-adminfilespicker
with, inherit that model’s admin options class fromadminfiles.admin.FilePickerAdmininstead of the usualdjango.contrib.admin.ModelAdmin, and set theadminfiles_fieldsattribute to a list/tuple of the names of the content fields it is
used with.For instance, if you have aPostmodel with acontentTextField, and you’d like to insert references into that TextField
from adjango-adminfilespicker:from django.contrib import admin

from adminfiles.admin import FilePickerAdmin

from myapp.models import Post

class PostAdmin(FilePickerAdmin):
    adminfiles_fields = ('content',)

admin.site.register(Post, PostAdmin)The picker displays thumbnails of all uploaded images, and appropriate
icons for non-image files. It also allows you to filter and view only
images or only non-image files. In the lower left it contains links to
upload a new file or refresh the list of available files.If you click on a file thumbnail/icon, a menu pops up with options to
edit or delete the uploaded file, or insert it into the associated
content field. To modify the default insertion options, set theADMINFILES_INSERT_LINKSsetting.File referencesWhen you use the file upload picker to insert an uploaded file
reference in a text content field, it inserts something like<<<my-file-slug>>>, built from theADMINFILES_REF_STARTandADMINFILES_REF_ENDsettings and the slug of theFileUploadinstance.The reference can also contain arbitrary key=value option after the
file slug, separated by colons, e.g.:<<<my-file-slug:class=left>>>.These generic references allow you to usedjango-adminfileswith
raw HTML content or any type of text markup. They also allow you to
change uploaded files and have old references to the file pick up the
change (as long as the slug does not change). The URL path to the
file, or other metadata like the height or width of an image, are not
hardcoded in your content.Rendering referencesThese references need to be rendered at some point into whatever
markup you ultimately want. The markup produced by the rendering is
controlled by the Django templates underadminfiles/render/.The template used is selected according to the mime type of the file
upload referenced. For instance, for rendering a file with mime typeimage/jpeg, the template used would be the first template of the
following that exists:adminfiles/render/image/jpeg.html,adminfiles/render/image/default.html,adminfiles/render/default.html.If a file should be rendered as if it had a different mime type
(e.g. an image you want to link to rather than display), pass theasoption with the mime type you want it rendered as (where either
the sub-type or the entire mime-type can be replaced withdefault). For instance, with the default available templates if
you wanted to link to an image file, you could use<<<my-image:as=default>>>.Two rendering templates are included withdjango-adminfiles:adminfiles/render/image/default.html(used for any type of image)
andadminfiles/render/default.html(used for any other type of
file). These default templates produce an HTMLimgtag for images
and a simplealink to other file types. They also respect three
key-value options:class, which will be used as the theclassattribute of theimgoratag;alt, which will be the
image alt text (images only; if not providedupload.titleis used
for alt text); andtitle, which will overrideupload.titleas
the link text of theatag (non-images only).You can easily override these templates with your own, and provide
additional templates for other file types. The template is rendered
with the following context:uploadTheFileUploadmodel instance whose slug field matches the
reference. Useful attributes of this instance includeupload.upload(aDjango File object),upload.title,upload.description,upload.mime_type(first and second
parts separately accessible asupload.content_typeandupload.sub_type) andupload.is_image(True ifupload.content_typeis “image”). Images also haveupload.heightandupload.widthavailable.optionsA dictionary of the key=value options in the reference.If a reference is encountered with an invalid slug (noFileUploadfound in the database with that slug), the value of theADMINFILES_STRING_IF_NOT_FOUNDsetting is rendered instead
(defaults to the empty string).render_uploads template filterdjango-adminfilesprovides two methods for making the actual
rendering happen. The simple method is a template filter:render_uploads. To use it, just load theadminfiles_tagstag
library, and apply therender_uploadsfilter to your content field:{% load adminfiles_tags %}

{{ post.content|render_uploads }}Therender_uploadsfilter just replaces any file upload references
in the content with the rendered template (described above).The filter also accepts an optional argument: an alternate base path
to the templates to use for rendering each uploaded file
reference. This path will replaceadminfiles/renderas the base
path in the mime-type-based search for specific templates. This allows
different renderings to be used in different circumstances:{{ post.content|render_uploads:"adminfiles/alt_render" }}For a file of mime typetext/plainthis would use one of the
following templates:adminfiles/alt_render/text/plain.html,adminfiles/alt_render/text/default.html, oradminfiles/alt_render/default.html.render_upload template filterIf you have aFileUploadmodel instance in your template and wish
to render just that instance using the normal rendering logic, you can
use therender_uploadfilter. This filter accepts options in the
same “key=val:key2=val2” format used for passing options to
inline-embedded files; the special optiontemplate_pathspecifies
an alternate base path for finding rendering templates:{{ my_upload|render_upload:"template_path=adminfiles/alt_render:class=special" }}pre-rendering at save timeIn some cases, markup in content fields is pre-rendered when the model
is saved, and stored in the database or cache. In this case, it may be
preferable to also render the uploaded file references in that step,
rather than re-rendering them every time the content is displayed in
the template.To use this approach, first you need to integrate the functionadminfiles.utils.render_uploadsinto your existing content
pre-rendering process, which should be automatically triggered by
saving the content model.Theadminfiles.utils.render_uploadsfunction takes a content
string as its argument and returns the same string with all uploaded
file references replaced, same as the template tag. It also accepts atemplate_pathargument, which is the same as the argument accepted
by therender_uploads template filter.Integrating this function in the markup-rendering step is outside the
scope ofdjango-adminfiles. For instance, if usingdjango-markitupwith Markdown to process content markup, theMARKITUP_FILTERsetting might look like this:MARKITUP_FILTER = ("utils.markup_filter", {})Which points to a function inutils.pylike this:from markdown import markdown
from adminfiles.utils import render_uploads

def markup_filter(markup):
    return markdown(render_uploads(markup))Once this is done, set theADMINFILES_USE_SIGNALSsetting to
True. Nowdjango-adminfileswill automatically track all
references to uploaded files in your content models. Anytime an
uploaded file is changed, all content models which reference it will
automatically be re-saved (and thus updated with the new uploaded
file).Embedding media from other sitesdjango-adminfilesallows embedding media from any site that supports the
OEmbed protocol. OEmbed support is provided viadjangoembedordjango-oembed, one of which must be installed for embedding to work.If a supported OEmbed application is installed, therender_uploads template
filterwill also automatically replace any OEmbed-capable URLs with the
appropriate embed markup (so URLs from any site supported by the installed
OEmbed application can simply be pasted in to the content manually).In addition,django-adminfilesprovides views in its filepicker to
browse Flickr photos, Youtube videos, and Vimeo videos and insert
their URLs into the context textarea with a click. To enable these
browsing views, set theADMINFILES_YOUTUBE_USER,ADMINFILES_VIMEO_USER, orADMINFILES_FLICKR_USERandADMINFILES_FLICKR_API_KEYsettings (and make sure thedependenciesare satisfied).To add support for browsing content from another site, just create a
class view that inherits fromadminfiles.views.OEmbedViewand add
its dotted path to theADMINFILES_BROWSER_VIEWSsetting. See the
existing views inadminfiles/views.pyfor details.To list the available browsing views and their status (enabled or
disabled, and why),django-adminfilesprovides anadminfiles_browser_viewsmanagement command, which you can run
with./manage.py adminfiles_browser_views.SettingsADMINFILES_REF_STARTMarker indicating the beginning of an uploaded-file reference in text
content. Defaults to ‘<<<’.If you set this to something insufficiently distinctive (a string
that’s likely to show up otherwise in your content), all bets are off.Special regex characters are escaped, thus you can safely set it to
something like ‘[[[’, but you can’t do advanced regex magic with it.ADMINFILES_REF_ENDMarker indicating the end of an uploaded-file reference in text
content. Defaults to ‘>>>’.If you set this to something insufficiently distinctive (a string
that’s likely to show up otherwise in your content), all bets are off.Special regex characters are escaped, thus you can safely set it to
something like ‘]]]’, but you can’t do advanced regex magic with it.ADMINFILES_USE_SIGNALSA boolean setting: shoulddjango-adminfilestrack which content
models reference which uploaded files, and re-save those content
models whenever a referenced uploaded file changes?Set this to True if you already pre-render markup in content fields at
save time and want to render upload references at that same save-time
pre-rendering step.Defaults to False. If this setting doesn’t make sense to you, you can
safely just leave it False and use therender_uploads template
filter.ADMINFILES_STRING_IF_NOT_FOUNDThe string used to replace invalid uploaded file references (given
slug not found). Defaults tou''.ADMINFILES_STDICON_SETDjango-adminfiles ships with a few icons for common file types, used
for displaying non-image files in the file-picker. To enable a broader
range of mime-type icons, set this setting to the name of an icon set
included atstdicon.com, and icons from that set will be linked.ADMINFILES_INSERT_LINKSBy default, the admin file picker popup menu for images allows
inserting a reference with no options, a reference with “class=left”,
or a reference with “class=right”. For non-images, the default popup
menu only allows inserting a reference without options. To change the
insertion options for various file types, setADMINFILES_INSERT_LINKSto a dictionary mapping mime-types (or
partial mime-types) to a list of insertion menu options. For instance,
the default setting looks like this:ADMINFILES_INSERT_LINKS = {
    '': [('Insert Link', {})],
    'image': [('Insert', {}),
              ('Insert (left)', {'class': 'left'}),
              ('Insert (right)', {'class': 'right'})]
}Each key in the dictionary can be the first segment of a mime type
(e.g. “image”), or a full mime type (e.g. “audio/mpeg”), or an empty
string (the default used if no mime type matches). For any given file
the most specific matching entry is used. The dictionary should always
contain a default entry (empty string key), or some files may have no
insertion options.Each value in the dictionary is a list of menu items. Each menu item
is a two-tuple, where the first entry is the user-visible name for the
insertion option, and the second entry is a dictionary of options to
be added to the inserted file reference.ADMINFILES_UPLOAD_TOTheupload_toargument that will be passed to theFileFieldondjango-admin-upload’sFileUploadmodel; determines wheredjango-adminfileskeeps its uploaded files, relative toMEDIA_URL. Can include strftime formatting codes as describedin
the Django documentation. By default, set to'adminfiles'.ADMINFILES_THUMB_ORDERThe ordering that will be applied to thumbnails displayed in the
picker. Expects a tuple of field names, prefixed with-to
indicate reverse ordering, same as“ordering” model Meta
attribute. The default value is('-upload_date'); thumbnails
ordered by date uploaded, most recent first.ADMINFILES_BROWSER_VIEWSList of dotted paths to file-browsing views to make available in the
filepicker. The default setting includes all the views bundled withdjango-adminfiles:['adminfiles.views.AllView',
'adminfiles.views.ImagesView',
'adminfiles.views.AudioView',
'adminfiles.views.FilesView',
'adminfiles.views.FlickrView',
'adminfiles.views.YouTubeView',
'adminfiles.views.VimeoView']The last three may be disabled despite their inclusion in this setting
if theirdependenciesare not satisfied or their required settings
are not set.ADMINFILES_YOUTUBE_USERRequired for use of the Youtube video browser.ADMINFILES_VIMEO_USERRequired for use of the Vimeo video browser.ADMINFILES_VIMEO_PAGESThe Vimeo API returns 20 videos per page; this setting determines the
maximum number of pages to fetch (defaults to 1, Vimeo-imposed maximum of
3).ADMINFILES_FLICKR_USERRequired for use of the Flickr photo browser.ADMINFILES_FLICKR_API_KEYRequired for use of the Flickr photo browser.JQUERY_URLdjango-adminfilesrequires the jQuery Javascript library.  By default,django-adminfilesuses the latest version of jQuery 1.4 hosted by Google,
via the URLhttp://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js.If you wish to use a different version of jQuery, or host it yourself, set theJQUERY_URLsetting.JQUERY_URLcan be absolute or relative; if relative
it is relative toSTATIC_URL. For example:JQUERY_URL = 'jquery.min.js'This will use the jQuery available atSTATIC_URL/jquery.min.js.
CHANGES
=======1.0.1 (2013.06.15)Fix for non-local file storages. Thanks vitaly4uk.Fix MANIFEST.in so static assets are included with release tarball. Thanks
StillNewb for the report.1.0 (2013.06.06)BACKWARDS-INCOMPATIBLE: Django versions prior to 1.4 are no longer tested or supported.BACKWARDS-INCOMPATIBLE: Removed theADMINFILES_MEDIA_URLsetting, useSTATIC_URLeverywhere for static assets. Thanks Rudolph Froger for the
nudge.Updated to most recent sorl-thumbnail. Thanks Svyatoslav Bulbakha.Added Russian translation. Thanks Svyatoslav Bulbakha.Added Spanish translation. Thanks Andrés Reyes Monge.Updated to use Django 1.3’s class-based views. Fixes #10. Thanks Andrés
Reyes Monge and Ales Zabala Alava.0.5.1 (2011.03.22)Added support for djangoembed as well as django-oembed.Added support for multiple pages of Vimeo results via
ADMINFILES_VIMEO_PAGES setting (defaults to 1).Added German translation. Thanks Jannis Leidel.0.5.0 (2010.03.09)Addedastemplate override keyword optionAddedrender_uploadfilterAdded YouTube, Flickr, Vimeo browsersAdded OEmbed supportAdded translation hooks and Polish translation: thanks Ludwik Trammer!Added support for linking full set of mime-type icons from stdicon.com.Made the JS reference-insertion options configurable.BACKWARDS-INCOMPATIBLE: default rendering template is nowadminfiles/render/default.htmlinstead ofadminfiles/render.html.  Image-specific rendering should
overrideadminfiles/render/image/default.htmlinstead of testingupload.is_imagein default template.Added per-mime-type template renderingUpgraded to jQuery 1.4Fixed bug where YouTube and Flickr links showed up even when disabled.Added sync_upload_refs command0.3.4 (2009.12.03)Fixed over-eager escaping in render_uploads template tag.0.3.3 (2009.12.02)Fixed insertion of slugs for non-image files.0.3.2 (2009.12.02)Fixed setup.py package_data so media and templates are installed from sdist.0.3.1 (2009.11.25)Fixed setup.py sotestspackage is not installed.0.3.0 (2009.11.23)Initial release asdjango-adminfilesAdded docs and test suiteAdded reference parsing & rendering, template filter, signal handlingTODOFix run_tests and short DB names deprecation warnings when running tests
on 1.3.Test and document snipshot integration and select dropdown integration.Add integration with plain FilePathField or FileField (for unobtrusive use
with third-party apps).Make URLs in JS portable (by reversing “all” view to find out where
we’ve been included in the URLconf).Link to online demo or video.