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: tags (with additional markup
as needed) for images, links for downloadable files, even embedded
players for audio or video files. See
the screencast_.
.. _the screencast: http://vimeo.com/8940852
Install from PyPI with easy_install or pip::
pip install django-adminfiles
or get the in-development version::
pip install http://bitbucket.org/carljm/django-adminfiles/get/tip.gz
django-adminfiles requires Django_ 1.4 or later,
sorl-thumbnail_ 11.12 (not compatible with old 3.x series)
and the Python Imaging Library_.
djangoembed_ or django-oembed_ is required for OEmbed
functionality. flickrapi_ is required for browsing Flickr photos, gdata_
for Youtube videos.
.. _Django: http://www.djangoproject.com/ .. _sorl-thumbnail: http://pypi.python.org/pypi/sorl-thumbnail/11.12 .. _Python Imaging Library: http://www.pythonware.com/products/pil/ .. _django-oembed: http://pypi.python.org/pypi/django-oembed .. _djangoembed: http://pypi.python.org/pypi/djangoembed .. _gdata: http://pypi.python.org/pypi/gdata .. _flickrapi: http://pypi.python.org/pypi/flickrapi
To use django-adminfiles in your Django project:
1. Add ``'adminfiles'`` to your ``INSTALLED_APPS`` setting. Also
add ``'sorl.thumbnail'`` if you have not installed it already.
2. Run ``python manage.py syncdb`` to to create the adminfiles database
tables.
3. Make the contents of the ``adminfiles/static/adminfiles`` directory
available at ``STATIC_URL/adminfiles``. This can be done by through
your webserver configuration, via an app such as
``django.contrib.staticfiles``, or by copying the files or making a
symlink.
4. Add ``url(r'^adminfiles/', include('adminfiles.urls'))`` in your
root URLconf.
5. Inherit content model admin options from
`FilePickerAdmin`_.
In addition, you may want to set the THUMBNAIL_EXTENSION setting for
sorl-thumbnail_ to "png" rather than the default "jpg", so that
images with alpha transparency aren't broken when thumbnailed in the
adminfiles file-picker.
For each model you'd like to use the django-adminfiles picker
with, inherit that model's admin options class from
adminfiles.admin.FilePickerAdmin instead of the usual
django.contrib.admin.ModelAdmin, and set the adminfiles_fields
attribute to a list/tuple of the names of the content fields it is
used with.
For instance, if you have a Post model with a content
TextField, and you'd like to insert references into that TextField
from a django-adminfiles picker::
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 the
ADMINFILES_INSERT_LINKS_ setting.
When 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 the ADMINFILES_REF_START_ and
ADMINFILES_REF_END_ settings and the slug of the FileUpload
instance.
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 use django-adminfiles with
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.
These 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 under adminfiles/render/.
The template used is selected according to the mime type of the file
upload referenced. For instance, for rendering a file with mime type
image/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 the
as option with the mime type you want it rendered as (where either
the sub-type or the entire mime-type can be replaced with
default). 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 with django-adminfiles:
adminfiles/render/image/default.html (used for any type of image)
and adminfiles/render/default.html (used for any other type of
file). These default templates produce an HTML img tag for images
and a simple a link to other file types. They also respect three
key-value options: class, which will be used as the the class
attribute of the img or a tag; alt, which will be the
image alt text (images only; if not provided upload.title is used
for alt text); and title, which will override upload.title as
the link text of the a tag (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:
upload
The FileUpload model instance whose slug field matches the
reference. Useful attributes of this instance include
upload.upload (a Django File object_), upload.title,
upload.description, upload.mime_type (first and second
parts separately accessible as upload.content_type and
upload.sub_type) and upload.is_image (True if
upload.content_type is "image"). Images also have
upload.height and upload.width available.
options
A dictionary of the key=value options in the reference.
If a reference is encountered with an invalid slug (no FileUpload
found in the database with that slug), the value of the
ADMINFILES_STRING_IF_NOT_FOUND_ setting is rendered instead
(defaults to the empty string).
.. _Django File object: http://docs.djangoproject.com/en/dev/ref/files/file/
django-adminfiles provides two methods for making the actual
rendering happen. The simple method is a template filter:
render_uploads. To use it, just load the adminfiles_tags tag
library, and apply the render_uploads filter to your content field::
{% load adminfiles_tags %}
{{ post.content|render_uploads }}
The render_uploads filter 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 replace adminfiles/render as 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 type text/plain this would use one of the
following templates: adminfiles/alt_render/text/plain.html,
adminfiles/alt_render/text/default.html, or
adminfiles/alt_render/default.html.
If you have a FileUpload model instance in your template and wish
to render just that instance using the normal rendering logic, you can
use the render_upload filter. This filter accepts options in the
same "key=val:key2=val2" format used for passing options to
inline-embedded files; the special option template_path specifies
an alternate base path for finding rendering templates::
{{ my_upload|render_upload:"template_path=adminfiles/alt_render:class=special" }}
In 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 function
adminfiles.utils.render_uploads into your existing content
pre-rendering process, which should be automatically triggered by
saving the content model.
The adminfiles.utils.render_uploads function 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 a
template_path argument, which is the same as the argument accepted
by the render_uploads template filter_.
Integrating this function in the markup-rendering step is outside the
scope of django-adminfiles. For instance, if using
django-markitup_ with Markdown to process content markup, the
MARKITUP_FILTER setting might look like this::
MARKITUP_FILTER = ("utils.markup_filter", {})
Which points to a function in utils.py like 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 the ADMINFILES_USE_SIGNALS_ setting to
True. Now django-adminfiles will 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).
.. _django-markitup: http://bitbucket.org/carljm/django-markitup
django-adminfiles allows embedding media from any site that supports the
OEmbed protocol. OEmbed support is provided via djangoembed_ or
django-oembed_, one of which must be installed for embedding to work.
If a supported OEmbed application is installed, the render_uploads template filter_ will 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-adminfiles provides 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 the ADMINFILES_YOUTUBE_USER,
ADMINFILES_VIMEO_USER, or ADMINFILES_FLICKR_USER_ and
ADMINFILES_FLICKR_API_KEY_ settings (and make sure the
dependencies_ are satisfied).
To add support for browsing content from another site, just create a
class view that inherits from adminfiles.views.OEmbedView and add
its dotted path to the ADMINFILES_BROWSER_VIEWS_ setting. See the
existing views in adminfiles/views.py for details.
To list the available browsing views and their status (enabled or
disabled, and why), django-adminfiles provides an
adminfiles_browser_views management command, which you can run
with ./manage.py adminfiles_browser_views.
Marker 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.
Marker 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.
A boolean setting: should django-adminfiles track 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 the render_uploads template filter_.
The string used to replace invalid uploaded file references (given
slug not found). Defaults to u''.
Django-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 at stdicon.com_, and icons from that set will be linked.
.. _stdicon.com: http://www.stdicon.com
By 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, set
ADMINFILES_INSERT_LINKS to 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.
The upload_to argument that will be passed to the FileField on
django-admin-upload's FileUpload model; determines where
django-adminfiles keeps its uploaded files, relative to
MEDIA_URL. Can include strftime formatting codes as described in the Django documentation_. By default, set to 'adminfiles'.
.. _in the Django documentation: http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.FileField.upload_to
The 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.
.. _"ordering" model Meta attribute: http://docs.djangoproject.com/en/dev/ref/models/options/#ordering
List of dotted paths to file-browsing views to make available in the
filepicker. The default setting includes all the views bundled with
django-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 their dependencies_ are not satisfied or their required settings
are not set.
Required for use of the Youtube video browser.
Required for use of the Vimeo video browser.
The 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).
Required for use of the Flickr photo browser.
Required for use of the Flickr photo browser.
django-adminfiles requires the jQuery Javascript library. By default,
django-adminfiles uses the latest version of jQuery 1.4 hosted by Google,
via the URL http://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 the
JQUERY_URL setting. JQUERY_URL can be absolute or relative; if relative
it is relative to STATIC_URL. For example::
JQUERY_URL = 'jquery.min.js'
STATIC_URL/jquery.min.js.
CHANGESFix for non-local file storages. Thanks vitaly4uk.
Fix MANIFEST.in so static assets are included with release tarball. Thanks StillNewb for the report.
BACKWARDS-INCOMPATIBLE: Django versions prior to 1.4 are no longer tested or supported.
BACKWARDS-INCOMPATIBLE: Removed the ADMINFILES_MEDIA_URL setting, use
STATIC_URL everywhere 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.
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.
Added as template override keyword option
Added render_upload filter
Added YouTube, Flickr, Vimeo browsers
Added OEmbed support
Added 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 now
adminfiles/render/default.html instead of
adminfiles/render.html. Image-specific rendering should
override adminfiles/render/image/default.html instead of testing
upload.is_image in default template.
Added per-mime-type template rendering
Upgraded to jQuery 1.4
Fixed bug where YouTube and Flickr links showed up even when disabled.
Added sync_upload_refs command
tests package is not installed.Initial release as django-adminfiles
Added docs and test suite
Added reference parsing & rendering, template filter, signal handling
Fix 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.
FAQs
File upload manager and picker for Django admin
We found that django-adminfiles demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.