83 | The Media Tree Documentation contains extensive information on how to use and extend this application.
84 |
85 |
86 |
87 |
Generic Views
88 |
89 | This application includes class-based generic views that enable you to access FileNode objects through public URLs.
90 | Please see the Demo Project's urls.py for an example of how to use them.
91 | Of course you can also extend the generic view classes to create views that suit your specific requirements.
92 |
99 |
--------------------------------------------------------------------------------
/docs/custom_plugins.rst:
--------------------------------------------------------------------------------
1 | Creating custom plugins for use with 3rd-party applications
2 | ***********************************************************
3 |
4 | .. _custom-plugins-howto:
5 |
6 | How to create custom plugins
7 | ============================
8 |
9 | Django Media Tree comes with some generic View classes and Mixins that make it
10 | relatively easy to use ``FileNode`` objects with your own applications.
11 |
12 | The following pseudo code should give you an idea of how to implement your own
13 | custom plugin that will render a file listing and work together with the
14 | 3rd-party application of your choice. It loosely looks like a Django CMS plugin.
15 | Please notice that the ``render()`` method is passed an
16 | ``options_instance``, which can be a dictionary or an object with
17 | attributes to initialize the generic View class we are using, which is
18 | ``FileNodeListingView`` in this case. See :ref:`generic-views` for more
19 | information on the View classes themselves::
20 |
21 |
22 | from media_tree.contrib.views.listing import FileNodeListingMixin
23 | from third_party_app import YourPluginSuperclass
24 | from django.shortcuts import render_to_response
25 |
26 | # Notice we are subclassing our third-party plugin class,
27 | # as well as the FileNodeListingMixin
28 | class CustomFileNodeListingPlugin(YourPluginSuperclass, FileNodeListingMixin):
29 |
30 | # Assuming render() is a standard method of YourPluginSuperclass
31 | def render(self, request, options_instance):
32 |
33 | # Get the generic view class using the method inherited from
34 | # the Mixin class.
35 | # Notice that get_detail_view() is inherited from the
36 | # FileNodeListingMixin. We are also passing our options model
37 | # instance for configuring the view instance.
38 | view = self.get_detail_view(request,
39 | queryset=options_instance.selected_folders,
40 | opts=options_instance)
41 |
42 | # Get the template context as generated by the View class
43 | context_data = view.get_context_data()
44 |
45 | # Render with custom template
46 | return render_to_response('listing.html', context_data)
47 |
48 | This is what our model classes (namely the class of the ``options_instance`` above)
49 | might look like::
50 |
51 | from django.db import Models
52 | from media_tree.fields import FileNodeForeignKey
53 |
54 | class PluginOptions(models.Model):
55 | # These field names are derived from
56 | # media_tree.contrib.views.list.FileNodeListingView.
57 | list_max_depth = models.IntegerField()
58 | include_descendants = models.BooleanField()
59 |
60 | class SelectedFolder(models.Model):
61 | plugin = models.ForeignKey(PluginOptions)
62 | folder = FileNodeForeignKey()
63 |
64 | The first class contains our plugin option fields. Notice that when calling the
65 | ``get_detail_view()`` or ``get_view()`` methods provided by the
66 | ``FileNodeListingMixin`` and passing it an instance of this model, any fields that
67 | match attributes of the view object returned will be used to initialized the
68 | view object.
69 |
70 | The second class creates a relationship between the options model and the
71 | ``FileNode`` model, i.e. you will be able to link ``FileNode`` objects to
72 | plugins.
73 |
74 |
75 | View Mixins
76 | ===========
77 |
78 | View Mixins are classes that add methods useful for interfacing with
79 | Media Tree's generic view classes to your custom plugin classes, as
80 | demonstrated in the above example.
81 |
82 | .. automodule:: media_tree.contrib.views.mixin_base
83 |
84 | .. autoclass:: media_tree.contrib.views.listing.FileNodeListingMixin
85 | :members:
86 | :inherited-members:
87 | :exclude-members: get_view
88 |
89 | .. autoclass:: media_tree.contrib.views.detail.FileNodeDetailMixin
90 | :members:
91 | :inherited-members:
92 | :exclude-members: get_view
93 |
94 | .. autoclass:: media_tree.contrib.views.detail.image.ImageNodeDetailMixin
95 | :members:
96 | :inherited-members:
97 | :exclude-members: get_view
98 |
99 |
--------------------------------------------------------------------------------
/media_tree/contrib/views/detail/__init__.py:
--------------------------------------------------------------------------------
1 | from media_tree.models import FileNode
2 | from media_tree.contrib.views.mixin_base import PluginMixin
3 | from django.views.generic.detail import DetailView
4 | from django.http import Http404
5 | from django.utils.translation import ugettext_lazy as _
6 |
7 |
8 | class FileNodeDetailView(DetailView):
9 | """
10 | View class for implementing detail views for ``FileNode`` objects. This
11 | class is based on Django's generic ``DetailView``. Please refer to the
12 | respective Django documentation on subclassing and customizing `Class-based
13 | generic views
14 | `_.
15 |
16 | The following example ``urls.py`` would implement a detail view capable of
17 | displaying all files with the extension ``.txt``, with URLs containing the
18 | full path of the ``FileNode`` object, for instance
19 | ``http://yourdomain.com/files/some/folder/ReadMe.txt``::
20 |
21 | from media_tree.models import FileNode
22 | from media_tree.contrib.views.detail import FileNodeDetailView
23 | from django.conf.urls.defaults import *
24 |
25 | urlpatterns = patterns('',
26 | (r'^files/(?P.+)/$', FileNodeDetailView.as_view(
27 | queryset=FileNode.objects.filter(extension='txt')
28 | )),
29 | )
30 | """
31 |
32 | model = FileNode
33 |
34 | filter_media_types = None
35 | """ An iterable containing media types to filter for. """
36 |
37 | filter_node_types = (FileNode.FILE,)
38 | """
39 | An iterable containing node types to filter for. By default this is
40 | ``(FileNode.FILE,)``
41 | """
42 |
43 | context_object_name = 'node'
44 | """ Designates the name of the variable to use in the context. """
45 |
46 | template_name = "media_tree/filenode_detail.html"
47 | """ Name of the template. """
48 |
49 | def get_object(self, queryset=None):
50 | """
51 | Returns the object the view is displaying.
52 |
53 | By default this requires `self.queryset` and a `pk` or `path` argument
54 | in the URLconf, but subclasses can override this to return any object.
55 | """
56 | # Use a custom queryset if provided; this is required for subclasses
57 | # like DateDetailView
58 | if queryset is None:
59 | queryset = self.get_queryset()
60 |
61 | path = self.kwargs.get('path', None)
62 |
63 | # Next, try looking up by path.
64 | if path is not None:
65 | queryset = queryset.filter(**FileNode.objects.get_filter_args_with_path(
66 | for_self=True, path=path))
67 | try:
68 | obj = queryset.get()
69 | except FileNode.DoesNotExist:
70 | raise Http404(_(u"No %(verbose_name)s found matching the query") %
71 | {'verbose_name': queryset.model._meta.verbose_name})
72 | return obj
73 |
74 | return super(FileNodeDetailView, self).get_object(queryset)
75 |
76 | def get_queryset(self, *args, **kwargs):
77 | queryset = super(FileNodeDetailView, self).get_queryset(*args, **kwargs)
78 | kwargs = {}
79 | if self.filter_node_types:
80 | kwargs['node_type__in'] = self.filter_node_types
81 | if self.filter_media_types:
82 | kwargs['media_type__in'] = self.filter_media_types
83 | return queryset.filter(**kwargs)
84 |
85 | def get_context_data(self, **kwargs):
86 | context = super(FileNodeDetailView, self).get_context_data(**kwargs)
87 | if not 'title' in context:
88 | context['title'] = context[self.context_object_name].title or context[self.context_object_name].name
89 | return context
90 |
91 |
92 | class FileNodeDetailMixin(PluginMixin):
93 |
94 | view_class = FileNodeDetailView
95 | """ The view class instantiated by ``get_detail_view()``. """
96 |
97 | def get_detail_view(self, request, object, opts=None):
98 | """
99 | Instantiates and returns the view class that will generate the actual
100 | context for this plugin.
101 | """
102 | view = self.get_view(request, self.view_class, opts)
103 | view.object = object
104 | return view
105 |
--------------------------------------------------------------------------------
/media_tree/widgets.py:
--------------------------------------------------------------------------------
1 | import os
2 | import django
3 | from django.contrib.admin.widgets import AdminFileWidget
4 | from django.contrib.admin.templatetags.admin_static import static
5 | from django.contrib.admin.widgets import ForeignKeyRawIdWidget
6 | from django.utils.html import escape
7 | from django.template.loader import render_to_string
8 | from django.utils.safestring import mark_safe
9 | from django.utils.translation import ugettext as _
10 | from media_tree import settings as app_settings
11 | from media_tree import media_types
12 | from media_tree.media_backends import get_media_backend, ThumbnailError
13 |
14 | THUMBNAIL_EXTENSIONS = app_settings.MEDIA_TREE_THUMBNAIL_EXTENSIONS
15 | THUMBNAIL_SIZE = app_settings.MEDIA_TREE_THUMBNAIL_SIZES['large']
16 | STATIC_SUBDIR = app_settings.MEDIA_TREE_STATIC_SUBDIR
17 |
18 |
19 | class FileNodeForeignKeyRawIdWidget(ForeignKeyRawIdWidget):
20 |
21 | class Media:
22 | js = (
23 | os.path.join(STATIC_SUBDIR, 'js', 'filenode_foreignkeywidget.js').replace("\\","/"),
24 | )
25 | css = {
26 | 'all': (
27 | os.path.join(STATIC_SUBDIR, 'css', 'filenode_preview.css').replace("\\","/"),
28 | )
29 | }
30 |
31 | # the actual input field should be hidden...
32 | input_type = 'hidden'
33 |
34 | # ...but for the field to show up amongst the form's visible fields, return
35 | # False here.
36 | @property
37 | def is_hidden(self):
38 | return False
39 |
40 | def render(self, name, value, attrs=None):
41 | # insert a placeholder for widget preview if value is None so that
42 | # the dismissRelatedLookupPopup hook in Javascript can populate it.
43 | output = super(FileNodeForeignKeyRawIdWidget, self).render(name, value, attrs)
44 | extra = ''
45 | if value:
46 | extra = '' % (
47 | static('admin/img/icon-deletelink.svg' if django.VERSION >= (1.9) else 'admin/img/icon-deletelink.svg'), _('Clear'))
48 | return mark_safe('%s%s%s' %
49 | (output, self.label_for_value(None) if not value else '', extra))
50 |
51 | def label_for_value(self, value):
52 | # instead of just outputting the node's name, render the node (or None)
53 | # through widget_preview.html, which adds icons and thumbnails depending
54 | # on your configuration.
55 | key = self.rel.get_related_field().name
56 | try:
57 | if value:
58 | obj = self.rel.to._default_manager.using(self.db).get(**{key: value})
59 | else:
60 | obj = None
61 | preview = render_to_string('admin/media_tree/filenode/includes/widget_preview.html',
62 | {'node': obj, 'preview_file': obj.get_preview_file() if obj else None})
63 |
64 | return preview
65 | except (ValueError, self.rel.to.DoesNotExist):
66 | return ''
67 |
68 |
69 | class AdminThumbWidget(AdminFileWidget):
70 | """
71 | An Image FileField Widget that shows a thumbnail if it has one.
72 | """
73 | def __init__(self, attrs={}):
74 | super(AdminThumbWidget, self).__init__(attrs)
75 |
76 | def get_media_backend(self, media_type):
77 | return get_media_backend(fail_silently=True, handles_media_types=(
78 | media_type,))
79 |
80 | def render(self, name, value, attrs=None):
81 | output = super(AdminThumbWidget, self).render(name, value, attrs)
82 | thumb = None
83 |
84 | if value and hasattr(value, "url"):
85 | media_backend = self.get_media_backend(media_types.SUPPORTED_IMAGE)
86 | if media_backend:
87 | try:
88 | thumb = media_backend.get_thumbnail(value, {'size': THUMBNAIL_SIZE})
89 | except ThumbnailError:
90 | pass
91 | if not thumb:
92 | media_backend = self.get_media_backend(media_types.VECTOR_IMAGE)
93 | if media_backend:
94 | try:
95 | thumb = media_backend.get_thumbnail(value, {'size': THUMBNAIL_SIZE})
96 | except ThumbnailError:
97 | pass
98 | if thumb:
99 | thumb_html = u'' % (thumb.url, os.path.basename(value.name), thumb.width, thumb.height)
100 | output = u'
%s
%s
' % (thumb_html, output)
101 |
102 | return mark_safe(output)
103 |
--------------------------------------------------------------------------------
/media_tree/utils/__init__.py:
--------------------------------------------------------------------------------
1 | from media_tree import settings as app_settings
2 | from django.conf import settings
3 | try:
4 | # Python 1.7
5 | from importlib import import_module
6 | except ImportError:
7 | from django.utils.importlib import import_module
8 | from django.core.exceptions import ImproperlyConfigured
9 | from django.core.files.storage import get_storage_class
10 | from django.utils.html import conditional_escape
11 | import re
12 |
13 |
14 | RE_SPLITEXT = re.compile('^(\.*.*?)((\.[^\.]+)*|\.)$')
15 |
16 |
17 | def get_media_storage():
18 | klass = get_storage_class(import_path=app_settings.MEDIA_TREE_STORAGE)
19 | return klass()
20 |
21 |
22 | # TODO: This function should probably cache all imported modules
23 | def get_module_attr(path):
24 | i = path.rfind('.')
25 | module_name, attr_name = path[:i], path[i+1:]
26 | try:
27 | module = import_module(module_name)
28 | except ImportError, e:
29 | raise ImproperlyConfigured('Error importing module %s: "%s"' % (module_name, e))
30 | try:
31 | attr = getattr(module, attr_name)
32 | except AttributeError:
33 | raise ImproperlyConfigured('Module "%s" does not define a "%s" callable' % (module_name, attr_name))
34 | return attr
35 |
36 |
37 | def autodiscover_media_extensions():
38 | """
39 | Auto-discover INSTALLED_APPS media_extensions.py modules and fail silently when
40 | not present. This forces an import on them to register any media extension bits
41 | they may want.
42 |
43 | Rip of django.contrib.admin.autodiscover()
44 | """
45 | import copy
46 | from django.conf import settings
47 | from django.utils.module_loading import module_has_submodule
48 |
49 | for app in settings.INSTALLED_APPS:
50 | mod = import_module(app)
51 | try:
52 | import_module('%s.media_extension' % app)
53 | except:
54 | if module_has_submodule(mod, 'media_extension'):
55 | raise
56 |
57 |
58 | def multi_splitext(basename):
59 | """
60 | Similar to os.path.slittext(), but with special handling for files with multiple extensions,
61 | such as "archive.tar.gz": Returns a list containg three elements, the first being the
62 | name without any extensions (taking into account hidden files/leading periods),
63 | the second being the "full" extension, the third being the extension as returned by
64 | os.path.splitext.
65 |
66 | Examples:
67 |
68 | os.path.join('foo.bar') # => ('foo', '.bar')
69 | multi_splitext('foo.bar') # => ['foo', '.bar', '.bar']
70 |
71 | os.path.join('foo.tar.gz') # => ('foo.tar', '.gz')
72 | multi_splitext('foo.tar.gz') # => ['foo', '.tar.gz', '.gz']
73 |
74 | os.path.join('.foo.tar.gz') # => ('.foo.tar', '.gz')
75 | multi_splitext('.foo.tar.gz') # => ['.foo', '.tar.gz', '.gz']
76 |
77 | os.path.join('.htaccess') # => ('.htaccess', '')
78 | multi_splitext('.htaccess') # => ['.htaccess', '', '']
79 |
80 | os.path.join('.foo.bar.') # => ('.foo.bar', '.')
81 | multi_splitext('.foo.bar.') # => ['.foo.bar', '.', '.']
82 |
83 | """
84 | groups = list(RE_SPLITEXT.match(basename).groups())
85 | if not groups[2]:
86 | groups[2] = groups[1]
87 | return groups
88 |
89 |
90 | def join_formatted(text, new_text, glue_format_if_true = u'%s%s', glue_format_if_false = u'%s%s', condition=None, format = u'%s', escape=False):
91 | """
92 | Joins two strings, optionally escaping the second, and using one of two
93 | string formats for glueing them together, depending on whether a condition
94 | is True or False.
95 |
96 | This function is a shorthand for complicated code blocks when you want to
97 | format some strings and link them together. A typical use case might be:
98 | Wrap string B with tags, but only if it is not empty, and join it
99 | with A with a comma in between, but only if A is not empty, etc.
100 | """
101 | if condition is None:
102 | condition = text and new_text
103 | add_text = new_text
104 | if escape:
105 | add_text = conditional_escape(add_text)
106 | if add_text:
107 | add_text = format % add_text
108 | glue_format = glue_format_if_true if condition else glue_format_if_false
109 | return glue_format % (text, add_text)
110 |
111 |
112 | # TODO: Factor out to image extension
113 | def widthratio(value, max_value, max_width):
114 | """
115 | Does the same like Django's `widthratio` template tag (scales max_width to factor value/max_value)
116 | """
117 | ratio = float(value) / float(max_value)
118 | return int(round(ratio * max_width))
119 |
--------------------------------------------------------------------------------
/media_tree/fields.py:
--------------------------------------------------------------------------------
1 | from media_tree import settings as media_types
2 | from media_tree import media_types
3 | from media_tree.models import FileNode
4 | from media_tree.widgets import FileNodeForeignKeyRawIdWidget
5 | from media_tree.forms import FileNodeChoiceField, LEVEL_INDICATOR
6 | from django.contrib.admin.widgets import ForeignKeyRawIdWidget
7 | from django.db import models
8 | from django import forms
9 | from django.conf import settings
10 |
11 | class FileNodeForeignKey(models.ForeignKey):
12 | """
13 | A model field for selecting a ``FileNode`` object.
14 |
15 | Its constructor takes the following arguments that are relevant when selecting ``FileNode`` objects:
16 |
17 | :param allowed_node_types: A list of node types that are allowed and will validate, e.g. ``(FileNode.FILE,)`` if the user should only be able to select files, but not folders
18 | :param allowed_media_types: A list of media types that are allowed and will validate, e.g. ``(media_types.DOCUMENT,)``
19 | :param allowed_extensions: A list of file extensions that are allowed and will validate, e.g. ``("jpg", "jpeg")``
20 |
21 | Since this class is a subclass of ``models.ForeignKey``, you can also pass it that class'
22 | parameters, such as ``limit_choices_to`` if you would like to restrict the objects that will
23 | be available for selection.
24 | """
25 |
26 | def __init__(self, allowed_node_types=None, allowed_media_types=None, allowed_extensions=None, level_indicator=LEVEL_INDICATOR, *args, **kwargs):
27 | self.allowed_node_types = allowed_node_types
28 | self.allowed_media_types = allowed_media_types
29 | self.allowed_extensions = allowed_extensions
30 | self.level_indicator = level_indicator
31 | kwargs['to'] = 'media_tree.FileNode'
32 | super(FileNodeForeignKey, self).__init__(*args, **kwargs)
33 |
34 | def formfield(self, **kwargs):
35 | defaults = {
36 | 'form_class': FileNodeChoiceField,
37 | 'rel': self.rel,
38 | 'allowed_node_types': self.allowed_node_types,
39 | 'allowed_media_types': self.allowed_media_types,
40 | 'allowed_extensions': self.allowed_extensions,
41 | 'empty_label': '',
42 | }
43 |
44 | defaults.update(kwargs)
45 | field = super(FileNodeForeignKey, self).formfield(**defaults)
46 |
47 | # If the widget is a ForeignKeyRawIdWidget, overwrite it with
48 | # FileNodeForeignKeyRawIdWidget. This is done here since the
49 | # widget's contructor parameters are coming from the ModelAdmin,
50 | # which we have no direct access to here.
51 | if isinstance(field.widget, ForeignKeyRawIdWidget) and not \
52 | isinstance(field.widget, FileNodeForeignKeyRawIdWidget):
53 | field.widget = FileNodeForeignKeyRawIdWidget(field.widget.rel,
54 | field.widget.admin_site, using=field.widget.db)
55 | return field
56 |
57 | def south_field_triple(self):
58 | "Returns a suitable description of this field for South."
59 | from south.modelsinspector import introspector
60 | field_class = "django.db.models.fields.related.ForeignKey"
61 | args, kwargs = introspector(self)
62 | return (field_class, args, kwargs)
63 |
64 |
65 | class ImageFileNodeForeignKey(FileNodeForeignKey):
66 | """
67 | A model field for selecting a ``FileNode`` object associated to a supported image format.
68 |
69 | Using this field will ensure that only folders and image files will be visible in the widget,
70 | and will require the user to select an image node.
71 | """
72 | def __init__(self, allowed_node_types=None, allowed_media_types=None, allowed_extensions=None, level_indicator=LEVEL_INDICATOR, *args, **kwargs):
73 | self.allowed_node_types = allowed_node_types
74 | if not allowed_media_types:
75 | allowed_media_types = (media_types.SUPPORTED_IMAGE,)
76 | kwargs['limit_choices_to'] = {'media_type__in': (FileNode.FOLDER, media_types.SUPPORTED_IMAGE)}
77 |
78 | super(ImageFileNodeForeignKey, self).__init__(allowed_node_types, allowed_media_types, allowed_extensions, level_indicator, *args, **kwargs)
79 |
80 |
81 | class DimensionField(models.CharField):
82 | """
83 | CharField for specifying image dimensions, i.e. width or height. Currently,
84 | this needs to be an integer > 0, but since it is a CharField, it might also
85 | contain units such as "px" or "%" in the future.
86 | """
87 | def __init__(self, verbose_name=None, name=None, **kwargs):
88 | if not 'max_length' in kwargs:
89 | kwargs['max_length'] = 8
90 | super(DimensionField, self).__init__(verbose_name, name, **kwargs)
91 |
92 | def formfield(self, **kwargs):
93 | defaults = {'regex': '^[1-9][0-9]*$',
94 | 'form_class': forms.RegexField}
95 | defaults.update(kwargs)
96 | return models.Field.formfield(self, **defaults)
97 |
98 | def south_field_triple(self):
99 | "Returns a suitable description of this field for South."
100 | from south.modelsinspector import introspector
101 | field_class = "django.db.models.fields.CharField"
102 | args, kwargs = introspector(self)
103 | return (field_class, args, kwargs)
104 |
--------------------------------------------------------------------------------
/docs/configuration.rst:
--------------------------------------------------------------------------------
1 | .. _configuration:
2 |
3 | Configuring Media Tree
4 | **********************
5 |
6 | The following settings can be specified in your Django project's settings
7 | module.
8 |
9 |
10 | ``MEDIA_TREE_STORAGE``
11 | File storage class to be used for any file-related operations when dealing
12 | with media files.
13 |
14 | This is not set by default, meaning that Django's ``DEFAULT_FILE_STORAGE``
15 | will be used. If you need to implement your custom storage, please refer to the
16 | relevant Django `documentation on that setting
17 | `_ and
18 | on `file storage
19 | `_
20 | in general.
21 |
22 | ``MEDIA_TREE_DELETE_FROM_STORAGE_ON_OVERWRITE``
23 |
24 | Determines whether existing files should be deleted from storage when the
25 | corresponding object is overwritten with a new file. This prevents the creation
26 | of orphaned files. As an added benefit in the case of Django's
27 | `FileSystemStorage`, if this setting is `True` and a file is supposed to be
28 | overwritten with a new file that has the same name, that name remains permanent
29 | because the old file will be deleted before the object is saved. If `False`, a
30 | random hash would be added to the new file's name due to the existing file
31 | already occupying the desired name on disk.
32 | """
33 |
34 | Default: ``True``
35 |
36 | ``MEDIA_TREE_MEDIA_BACKENDS``
37 | A tuple of media backends for thumbnail generation and other media-related
38 | tasks, i.e. a list of wrappers for the 3rd-party applications that take
39 | care of them.
40 |
41 | .. Note::
42 | Please refer to the :ref:`installation instructions
43 | ` for information on how to configure
44 | supported media backends.
45 |
46 | For general information on media backends, see :ref:`media-backends` for
47 | more information.
48 |
49 |
50 | ``MEDIA_TREE_MEDIA_BACKEND_DEBUG``
51 | Specifies whether exceptions caused by media backends, such as ``ThumbnailError``, should be
52 | raised or silently ignored.
53 |
54 | Default: ``settings.DEBUG``
55 |
56 |
57 | ``MEDIA_TREE_LIST_DISPLAY``
58 | A tuple containing the columns that should be displayed in the
59 | ``FileNodeAdmin``. Note that the ``browse_controls`` column is necessary for
60 | the admin to function properly.
61 |
62 |
63 | ``MEDIA_TREE_LIST_FILTER``
64 | A tuple containing the fields that nodes can be filtered by in the
65 | ``FileNodeAdmin``.
66 |
67 |
68 | ``MEDIA_TREE_SEARCH_FIELDS``
69 | A tuple containing the fields that nodes can be searched by in the
70 | ``FileNodeAdmin``.
71 |
72 |
73 | ``MEDIA_TREE_UPLOAD_SUBDIR``
74 | Default: ``'upload'``
75 |
76 | The name of the folder under your ``MEDIA_ROOT`` where media files are stored.
77 |
78 |
79 | ``MEDIA_TREE_PREVIEW_SUBDIR``
80 | Default: ``'upload/_preview'``
81 |
82 | The name of the folder under your ``MEDIA_ROOT`` where cached versions of
83 | media files, e.g. thumbnails, are stored.
84 |
85 |
86 | ``MEDIA_TREE_ICON_DIRS``
87 | Default::
88 |
89 | (
90 | 'media_tree/img/icons/mimetypes',
91 | )
92 |
93 | A tuple containing all icon directories. See :ref:`install-icon-sets`
94 | for more information.
95 |
96 |
97 | ``MEDIA_TREE_THUMBNAIL_SIZES``
98 | A dictionary of default thumbnail sizes. You can pass the dictionary key to
99 | the ``thumbnail`` templatetag instead of a numeric size.
100 |
101 | Default::
102 |
103 | {
104 | 'small': (80, 80),
105 | 'default': (100, 100),
106 | 'medium': (250, 250),
107 | 'large': (400, 400),
108 | 'full': None, # None means: use original size
109 | }
110 |
111 |
112 | ``MEDIA_TREE_ALLOWED_FILE_TYPES``
113 | A whitelist of file extensions that can be uploaded. By default, this is a
114 | comprehensive list of many common media file extensions that generally
115 | shouldn't pose a security risk.
116 |
117 | .. Warning::
118 | Just because a file extension may be considered “safe”, there is
119 | absolutely no guarantee that a skilled attacker couldn't find an exploit.
120 | You should only allow people you trust to upload files to your webserver.
121 | Be careful when adding potentially unsafe file extensions to this
122 | setting, such as executables or scripts, as this possibly opens a door to
123 | attackers.
124 |
125 |
126 | ``MEDIA_TREE_THUMBNAIL_EXTENSIONS``
127 | Default: ``('jpg', 'png')``
128 |
129 | A tuple of image extensions used for thumbnail files. Note that ``png`` is
130 | in there since you typically might want to preserve the file type of PNG
131 | images instead of converting them to JPG.
132 |
133 |
134 | ``MEDIA_TREE_FILE_SIZE_LIMIT``
135 | Default: ``1000000000 # 1 GB``
136 |
137 | Maximum file size for uploaded files.
138 |
139 |
140 | ``MEDIA_TREE_GLOBAL_THUMBNAIL_OPTIONS``
141 | A dictionary of options that should be applied by default when generating
142 | thumbnails. You might use this, for instance, to sharpen all thumbnails::
143 |
144 | MEDIA_TREE_GLOBAL_THUMBNAIL_OPTIONS = {
145 | 'sharpen': True
146 | }
147 |
--------------------------------------------------------------------------------
/media_tree/utils/staticfiles.py:
--------------------------------------------------------------------------------
1 | from media_tree import settings as app_settings
2 | from media_tree.utils import get_module_attr
3 | from django.conf import settings
4 | from django.db.models.fields.files import FieldFile
5 | from django.core.files.storage import FileSystemStorage
6 | from django.core.files.base import File
7 | from django.utils.translation import ugettext_lazy as _
8 | from PIL import Image
9 | import os
10 |
11 |
12 | ICON_DIRS = app_settings.MEDIA_TREE_ICON_DIRS
13 |
14 |
15 | def get_static_storage():
16 | # Passing FileSystemStorage the STATIC_ROOT and STATIC_URL settings
17 | # if set will make it work with django.contrib.staticfiles while, if
18 | # those settings don't exist, it will fall back to MEDIA_ROOT /
19 | # MEDIA_URL by default.
20 | return FileSystemStorage(
21 | location=getattr(settings, 'STATIC_ROOT', None),
22 | base_url=getattr(settings, 'STATIC_URL', None))
23 |
24 |
25 | STATIC_STORAGE = get_static_storage()
26 | BUFFERED_ICON_SIZES = {}
27 | EXISTING_PATHS = {}
28 |
29 |
30 | class StaticFile(FieldFile):
31 | """
32 | A wrapper for static files that is compatible to the FieldFile class, i.e.
33 | you can use instances of this class in templates just like you use the value
34 | of FileFields (e.g. `{{ my_static_file.url }}`)
35 | """
36 | def __init__(self, instance, name):
37 | File.__init__(self, None, name)
38 | self.instance = instance
39 | self.storage = STATIC_STORAGE
40 | self.field = self
41 |
42 | def save(self, *args, **kwargs):
43 | raise NotImplementedError('Static files are read-only')
44 |
45 | def delete(self, *args, **kwargs):
46 | raise NotImplementedError('Static files are read-only')
47 |
48 | def __unicode__(self):
49 | return self.instance.__unicode__()
50 |
51 | def alt(self):
52 | return self.instance.alt
53 |
54 |
55 | class StaticIconFile(StaticFile):
56 | """
57 | A wrapper for static icons that is compatible to the FieldFile class, i.e.
58 | you can use instances of this class in templates just like you use the value
59 | of FileFields (e.g. `{{ my_static_file.url }}`)
60 | """
61 | def __init__(self, *args, **kwargs):
62 | super(StaticIconFile, self).__init__(*args, **kwargs)
63 | self.is_icon = True
64 | if not self.path in BUFFERED_ICON_SIZES:
65 | try:
66 | im = Image.open(self.path)
67 | BUFFERED_ICON_SIZES[self.path] = im.size
68 | except:
69 | pass
70 | self.width, self.height = BUFFERED_ICON_SIZES.get(self.path, (None, None))
71 |
72 | def alt(self):
73 | if not self.instance:
74 | return ''
75 | if not self.instance.is_folder():
76 | return self.instance.extension
77 | return _('folder')
78 |
79 |
80 | class StaticPathFinder:
81 |
82 | @staticmethod
83 | def find(names, dirs, file_ext):
84 | """
85 | Iterating a set of dirs under the static root, this method tries to find
86 | a file named like one of the names and file ext passed, and returns the
87 | storage path to the first file it encounters.
88 |
89 | Usage this method makes it possible to override static files (such as
90 | icon sets) in a similar way like templates in different locations can
91 | override others that have the same file name.
92 | """
93 | if not isinstance(names, list) or isinstance(names, tuple):
94 | names = (names,)
95 | for dir_name in dirs:
96 | for name in names:
97 | path = os.path.join(dir_name, name + file_ext)
98 | if not path in EXISTING_PATHS:
99 | # check on file system, then cache
100 | EXISTING_PATHS[path] = STATIC_STORAGE.exists(path)
101 | if EXISTING_PATHS[path]:
102 | return path
103 |
104 |
105 | class MimetypeStaticIconFileFinder:
106 |
107 | @staticmethod
108 | def find(file_node, dirs=ICON_DIRS, default_name=None, file_ext='.png'):
109 | """
110 | Iterating all icon dirs, try to find a file called like the node's
111 | extension / mime subtype / mime type (in that order).
112 | For instance, for an MP3 file ("audio/mpeg"), this would look for:
113 | "mp3.png" / "audio/mpeg.png" / "audio.png"
114 | """
115 | names = []
116 | for attr_name in ('extension', 'mimetype', 'mime_supertype'):
117 | attr = getattr(file_node, attr_name)
118 | if attr:
119 | names.append(attr)
120 | if default_name:
121 | names.append(default_name)
122 | icon_path = StaticPathFinder.find(names, dirs, file_ext)
123 | if icon_path:
124 | return StaticIconFile(file_node, icon_path)
125 |
126 |
127 | # TODO: Find a better way of caching ICON_FINDERS (and what about threads and different settings files defining different icon finders?)
128 | ICON_FINDERS = None
129 |
130 | def get_icon_finders(finder_names):
131 | global ICON_FINDERS
132 | if not ICON_FINDERS:
133 | finders = []
134 | for finder_name in finder_names:
135 | finder = get_module_attr(finder_name)
136 | if not hasattr(finder, 'find'):
137 | raise ImproperlyConfigured('Module "%s" does not define a "find" method' % finder_name)
138 | finders.append(finder)
139 | ICON_FINDERS = finders
140 | return ICON_FINDERS
141 |
--------------------------------------------------------------------------------
/docs/dummy/settings.py:
--------------------------------------------------------------------------------
1 | # Django settings for dummy project.
2 |
3 | DEBUG = True
4 | TEMPLATE_DEBUG = DEBUG
5 |
6 | ADMINS = (
7 | # ('Your Name', 'your_email@example.com'),
8 | )
9 |
10 | MANAGERS = ADMINS
11 |
12 | DATABASES = {
13 | 'default': {
14 | 'ENGINE': 'django.db.backends.', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
15 | 'NAME': '', # Or path to database file if using sqlite3.
16 | 'USER': '', # Not used with sqlite3.
17 | 'PASSWORD': '', # Not used with sqlite3.
18 | 'HOST': '', # Set to empty string for localhost. Not used with sqlite3.
19 | 'PORT': '', # Set to empty string for default. Not used with sqlite3.
20 | }
21 | }
22 |
23 | # Local time zone for this installation. Choices can be found here:
24 | # http://en.wikipedia.org/wiki/List_of_tz_zones_by_name
25 | # although not all choices may be available on all operating systems.
26 | # On Unix systems, a value of None will cause Django to use the same
27 | # timezone as the operating system.
28 | # If running in a Windows environment this must be set to the same as your
29 | # system time zone.
30 | TIME_ZONE = 'America/Chicago'
31 |
32 | # Language code for this installation. All choices can be found here:
33 | # http://www.i18nguy.com/unicode/language-identifiers.html
34 | LANGUAGE_CODE = 'en-us'
35 |
36 | SITE_ID = 1
37 |
38 | # If you set this to False, Django will make some optimizations so as not
39 | # to load the internationalization machinery.
40 | USE_I18N = True
41 |
42 | # If you set this to False, Django will not format dates, numbers and
43 | # calendars according to the current locale
44 | USE_L10N = True
45 |
46 | # Absolute filesystem path to the directory that will hold user-uploaded files.
47 | # Example: "/home/media/media.lawrence.com/media/"
48 | MEDIA_ROOT = ''
49 |
50 | # URL that handles the media served from MEDIA_ROOT. Make sure to use a
51 | # trailing slash.
52 | # Examples: "http://media.lawrence.com/media/", "http://example.com/media/"
53 | MEDIA_URL = ''
54 |
55 | # Absolute path to the directory static files should be collected to.
56 | # Don't put anything in this directory yourself; store your static files
57 | # in apps' "static/" subdirectories and in STATICFILES_DIRS.
58 | # Example: "/home/media/media.lawrence.com/static/"
59 | STATIC_ROOT = ''
60 |
61 | # URL prefix for static files.
62 | # Example: "http://media.lawrence.com/static/"
63 | STATIC_URL = '/static/'
64 |
65 | # URL prefix for admin static files -- CSS, JavaScript and images.
66 | # Make sure to use a trailing slash.
67 | # Examples: "http://foo.com/static/admin/", "/static/admin/".
68 | ADMIN_MEDIA_PREFIX = '/static/admin/'
69 |
70 | # Additional locations of static files
71 | STATICFILES_DIRS = (
72 | # Put strings here, like "/home/html/static" or "C:/www/django/static".
73 | # Always use forward slashes, even on Windows.
74 | # Don't forget to use absolute paths, not relative paths.
75 | )
76 |
77 | # List of finder classes that know how to find static files in
78 | # various locations.
79 | STATICFILES_FINDERS = (
80 | 'django.contrib.staticfiles.finders.FileSystemFinder',
81 | 'django.contrib.staticfiles.finders.AppDirectoriesFinder',
82 | # 'django.contrib.staticfiles.finders.DefaultStorageFinder',
83 | )
84 |
85 | # Make this unique, and don't share it with anybody.
86 | SECRET_KEY = 'f!ctm1x10dqn1jily1rueh(uu_qv5q#nia@x034k*_*+k+!b83'
87 |
88 | # List of callables that know how to import templates from various sources.
89 | TEMPLATE_LOADERS = (
90 | 'django.template.loaders.filesystem.Loader',
91 | 'django.template.loaders.app_directories.Loader',
92 | # 'django.template.loaders.eggs.Loader',
93 | )
94 |
95 | MIDDLEWARE_CLASSES = (
96 | 'django.middleware.common.CommonMiddleware',
97 | 'django.contrib.sessions.middleware.SessionMiddleware',
98 | 'django.middleware.csrf.CsrfViewMiddleware',
99 | 'django.contrib.auth.middleware.AuthenticationMiddleware',
100 | 'django.contrib.messages.middleware.MessageMiddleware',
101 | )
102 |
103 | ROOT_URLCONF = 'dummy.urls'
104 |
105 | TEMPLATE_DIRS = (
106 | # Put strings here, like "/home/html/django_templates" or "C:/www/django/templates".
107 | # Always use forward slashes, even on Windows.
108 | # Don't forget to use absolute paths, not relative paths.
109 | )
110 |
111 | INSTALLED_APPS = (
112 | 'django.contrib.auth',
113 | 'django.contrib.contenttypes',
114 | 'django.contrib.sessions',
115 | 'django.contrib.sites',
116 | 'django.contrib.messages',
117 | 'django.contrib.staticfiles',
118 | # Uncomment the next line to enable the admin:
119 | # 'django.contrib.admin',
120 | # Uncomment the next line to enable admin documentation:
121 | # 'django.contrib.admindocs',
122 | )
123 |
124 | # A sample logging configuration. The only tangible logging
125 | # performed by this configuration is to send an email to
126 | # the site admins on every HTTP 500 error.
127 | # See http://docs.djangoproject.com/en/dev/topics/logging for
128 | # more details on how to customize your logging configuration.
129 | LOGGING = {
130 | 'version': 1,
131 | 'disable_existing_loggers': False,
132 | 'handlers': {
133 | 'mail_admins': {
134 | 'level': 'ERROR',
135 | 'class': 'django.utils.log.AdminEmailHandler'
136 | }
137 | },
138 | 'loggers': {
139 | 'django.request': {
140 | 'handlers': ['mail_admins'],
141 | 'level': 'ERROR',
142 | 'propagate': True,
143 | },
144 | }
145 | }
146 |
147 | MEDIA_TREE_MEDIA_BACKENDS = (
148 | 'dummy.media_backends.DummyBackend',
149 | )
150 |
--------------------------------------------------------------------------------