Adding document previews to Wagtail CMS

Wagtail is a free and open source CMS written in Python. It’s built on top of the Django web framework. Wagtail also follow’s Django’s “batteries included” philosophy, so it offers many great features out of the box, including image and document management. Like most document management solutions, these files usually don’t have thumbnails. If they do, it requires editors to upload one for each document.

Wagtail has the correct hooks in places to allow developers to extend their Document’s implementation, so we built a third party package that you can install to easily extend your Wagtail site’s documents with image previews and metadata.

Getting started

After installing and configuring Wagtail, install wagtaildocs_previews.

$ pip install wagtaildocs_previews

Settings

Now, configure the project’s settings

In your settings file, add wagtaildocs_previews to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'wagtail.contrib.settings',
    'wagtaildocs_previews',
    # ...
]

You’ll also need to set WAGTAILDOCS_DOCUMENT_MODEL.

WAGTAILDOCS_DOCUMENT_MODEL = 'wagtaildocs_previews.PreviewableDocument'

Make sure to apply any new migrations to your database

$ python manage.py migrate

URL configuration

By default, Wagtail sets the documents/ URL to the following in your project’s urls.py.

from wagtail.wagtaildocs import urls as wagtaildocs_urls

Update that import so that your urls.py looks like the following:

from wagtaildocs_previews import urls as wagtaildocs_urls

urlpatterns = [
    # ...
    url(r'^documents/', include(wagtaildocs_urls)),
    # ...
]

FilePreviews.io API Keys

For previews to be generated for your documents, you’ll need to have a FilePreviews.io account and an application’s credentials. Once you have the credentials, add them under the FilePreviews settings in your Wagtail admin.

Usage

Since we’re extending via WAGTAILDOCS_DOCUMENT_MODEL you should be using get_document_model() to reference the correct Document model.

from wagtail.wagtailcore.models import Page
from wagtail.wagtaildocs.models import get_document_model
from wagtail.wagtaildocs.edit_handlers import DocumentChooserPanel


class BookPage(Page):
    book_file = models.ForeignKey(
        get_document_model(),
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+'
    )

    content_panels = Page.content_panels + [
        DocumentChooserPanel('book_file'),
    ]

In your template now you’ll be able to access the preview_data field.

{% extends "base.html" %}
{% load wagtailcore_tags %}

{% block body_class %}resource-page{% endblock %}

{% block content %}
    <h1>Book</h>
    <h2>{{ page.book_file.title }}</h2>
    <img src="{{ page.book_file.preview_data.preview.url|default:'http://placehold.it/300x300' }}" alt="">
{% endblock %}

Configuring thumbnail sizes and other options

By default, image previews and not resized at all. If you want to specify additional FilePreviews options like thumbnail size or metadata, specify the WAGTAILDOCS_PREVIEWS_OPTIONS_CALLBACK option in your settings.

WAGTAILDOCS_PREVIEWS_OPTIONS_CALLBACK='mysite.utils.get_preview_options'

def get_preview_options(document):
    return {
        'sizes': [300],
        'metadata': ['ocr']
    }

Open Source

Like Wagtail, our wagtaildocs_previews package is open source. If you run into any issues or have any ideas on how to improve it, the project is available on GitHub: https://github.com/filepreviews/wagtail-filepreviews.

Bonus: Coding session video

Here’s a coding session video building up to the released package.