Installing Media Tree

This install guide assumes you are familiar with Python and Django.

Dependencies

Make sure to install the following packages if you want to use Media Tree:

Note

All required Python packages can easily be installed using pip (or, alternatively, easy_install).

Getting the code

For the latest stable version (recommended), use pip:

pip install django-media-tree

or download it from http://github.com/samluescher/django-media-tree and run the installation script:

python setup.py install

Demo project

A demo project is included for you to quickly test and evaluate Django Media Tree. It is recommended to use virtualenv for trying it out, as you’ll be able to install all dependencies in isolation. Afer installing virtualenv, run the following commands to start the demo project:

mkdir django-media-tree-test && cd django-media-tree-test
virtualenv venv
source venv/bin/activate
curl -L https://github.com/samluescher/django-media-tree/archive/master.zip  \
  -o django-media-tree-master.zip && unzip django-media-tree-master
cd django-media-tree-master/demo_project
pip install -r requirements.txt
python manage.py collectstatic
python manage.py syncdb  # no need to create a superuser
python manage.py loaddata fixtures/initial_data.json
python manage.py runserver

Then open http://localhost:8000 in your web browser.

Basic setup

Please follow these steps to use Media Tree with your own application.

  • In your project settings, add mptt and media_tree to the INSTALLED_APPS:

    INSTALLED_APPS = (
        # ... your other apps here
        'mptt',
        'media_tree',
    )
    
  • Make sure your STATIC_URL, STATIC_ROOT, MEDIA_URL and STATIC_ROOT are properly configured.

    Note

    Please refer to the Django documentation on how to configure your Django project to serve static files if you have not done that yet.

  • If you are using django.contrib.staticfiles (recommended), just run the usual command to collect static files:

    python manage.py collectstatic
    

    If you are not going to use the staticfiles app, you will have to copy the contents of the static folder to the location you are serving static files from.

  • Create the database tables:

    python manage.py syncdb
    

    Alternatively, if you are using South in your project, you’ll have to use a slightly different command:

    python manage.py syncdb --all
    python migrate media_tree --fake
    

Configuring media backends (optional)

  • If you want thumbnails to be generated – which will usually be the case – you need to install the appropriate media backend that takes care of this. Currently, easy-thumbnails is the only recommended and officially supported 3rd-party application.

    After you’ve installed the easy_thumbnails module, configure Media Tree to use it by defining MEDIA_TREE_MEDIA_BACKENDS in your project settings:

    MEDIA_TREE_MEDIA_BACKENDS = (
        'media_tree.contrib.media_backends.easy_thumbnails.EasyThumbnailsBackend',
    )
    

    Note

    In principle, Media Tree can work together with any other thumbnail generating app, provided that you write the appropriate media backend class to support it. Please have a look at one of the backends under media_tree.contrib.media_backends if you are interested in using your own specific 3rd-party app.

  • Optional: Also add any Media Tree extensions that you are planning to use to your INSTALLED_APPS:

    INSTALLED_APPS = (
        # ... your other apps here
        'media_tree.contrib.media_extensions.images.focal_point',
        'media_tree.contrib.media_extensions.zipfiles',
    )
    

    Note

    See Bundled extensions for a list of default extensions included in the project.

Note on django-mptt

A version of django-mptt newer than 0.4.2 is required because there is an issue with older versions not indenting the folder list correctly. Either install a recent version:

pip install django-mptt==0.5.1

or, if for some reason you can’t install a recent version, you can resolve the situation by putting legacy_mptt_support in your INSTALLED_APPS before mptt. This will be deprecated in the future:

INSTALLED_APPS = (
  # ... your other apps here
  'media_tree.contrib.legacy_mptt_support', 'mptt', 'media_tree',
)

Installing icon sets (optional)

By default, Media Tree only comes with plain file and folder icons. If you would like to use custom icon sets that are more appropriate for your specific media types, you can install them like a Django application.

The following ready-to-use modules contain some nice icons:

You will need to configure Media Tree to use an icon set as follows.

  • In order to install an icon set, simply add the respective module to your INSTALLED_APPS setting:

    INSTALLED_APPS = (
        # ... your other apps here
        'my_custom_icon_set',
    )
    
  • If you are using django.contrib.staticfiles (recommended), just run the usual command to collect static files:

    ./manage.py collectstatic
    

    If you are not using the staticfiles app, copy the contents of the static folder to the static root of your project.

  • Define MEDIA_TREE_ICON_DIRS in your project settings, and add the static path containing the new icon files, e.g.:

    MEDIA_TREE_ICON_DIRS = (
        'my_custom_icons/64x64px', # the new folder under your static root
        'media_tree/img/icons/mimetypes', # default icon folder
    )
    

    Note

    You can add several icon sets to this tuple, and for each media file the first appropriate icon that is encountered will be used. Please notice that on the last line we are specifying the default icon location, which will be used as a fallback in case no appropriate icon is found in one of the custom sets.