Tutorial

Django-inline-media is a simple reusable app that allows insertion of inline media content, so far pictures and picture sets, into texts.

Motivation

Django-inline-media help your users place images or collections of images as inlines in texts.

Any application used to write text that needs to insert inline pictures is a good candidate to adopt Django-inline-media. The app will render the text with inline pictures or picture sets, and when defined as clickable pictures will be overlayed in a bigger size on top of the page.

Django-inline-media comes with two media models: Picture and PictureSet, but you can create your own inline types to support other media formats or providers (oembed based content coming soon).

This tutorial explains how to install and configure django-inline-media, how to integrate it in your web project and how to use the widget. It additionally supports the Wysihtml5 rich text editor by providing a replacement for the Wysihtml5’s insertImage command. See the demo_wysihtml5 for details on this feature.

Installation

Check out the sources and add the app to your project or PYTHONPATH.

Use git, pip or easy_install to check out django-inline-media from Github or get a release from PyPI:

  1. Use git to clone the repository, and then install the package (read more about git):
  • git clone git://github.com/danirus/django-inline-media.git and
  • python setup.py install
  1. Or use pip (read more about pip):
  • Do pip install django-inline-media, or
  • Edit your project’s requirements file and append either the Github URL or the package name django-inline-media, and then do pip install -r requirements.
  1. Or use easy_install (read more about easy_install):
  • Do easy_install django-inline-media

Configuration

Follow the steps:

  1. Install required apps:
  1. Add the following entries to your settings.py:
  • Add inline_media, sorl.thumbnail and tagging to INSTALLED_APPS.
  • Add THUMBNAIL_BACKEND = "inline_media.sorl_backends.AutoFormatBackend"
  • Add THUMBNAIL_FORMAT = "JPEG"
  • Optionally add an extra setting to control where django-inline-media stores images (see Settings). It has a sane default, so don’t bother to much.
  1. Run management commands:
    • python manage.py syncdb to create inline_media DB entities (License, Picture, PictureSet)
    • python manage.py collectstatic to copy CSS and JavaScript content from inline_media to your project’s static directory

There are extra steps when planning to use the Wysihtml5 editor. Read on the specific ref-wysihtml5-demo.

Using inline-media

Using inline-media is pretty easy:

  1. Decide which fields of your models will hold inline media content (the typical candidate: a body field of a blog Post model)
  2. Change their type from TextField to TextFieldWithInlines. This change does not affect your models’ table definition, but just the way fields are rendered.
  3. Change the admin class of those models and make them inherit from AdminTextFieldWithInlinesMixin. Fields of type TextfieldWithInlines will be rendered as TextareWithInlines

Let’s see it with an example: the Article model.

Example code

The Article model, in the demo project, has a couple of fields of type TextField, abstract and body. Only the field body will hold inline media content. Article definition will look as follow:

from inline_media.fields import TextFieldWithInlines

class Article(models.Model):
    title = models.CharField(max_length=200)
    slug = models.SlugField(unique_for_date='publish')
    abstract = models.TextField()
    body = TextFieldWithInlines()
    publish = models.DateTimeField(default=datetime.now)

The ArticleAdmin class will inherit from both, AdminTextFieldWithInlinesMixin and Django’s ModelAdmin:

from django.contrib import admin
from inline_media.admin import AdminTextFieldWithInlinesMixin
from demo.articles.models import Article

class ArticleAdmin(AdminTextFieldWithInlinesMixin, admin.ModelAdmin):
    list_display  = ('title', 'publish')
    list_filter   = ('publish',)
    search_fields = ('title', 'abstract', 'body')
    prepopulated_fields = {'slug': ('title',)}
    fieldsets = ((None,
                  {'fields': ('title', 'slug', 'abstract', 'body',
                              'publish',)}),)

admin.site.register(Article, ArticleAdmin)

In action

Look at the admin site of the demo project. Click on any of the articles and see that the inlines field below the body allows you to choose between Picture and PictureSet:

_images/tutorial_article_change_view.png

Your articles detail template (example/demo/templates/articles/article_detail.html) loads the inlines templatetag and apply the render_inlines filter to the body field:

{% load i18n inlines %}
...

<div class="inline_media_clearfix">
  {{ object.body|render_inlines }}
</div>

You can also customize inline-media templates for pictures and picture sets.