Quick start guide

Installing django-fluent-contents

The base installation of django-fluent-contents requires Django version 1.3 or higher and django-polymorphic 0.2 or higher.

The package can be installed using:

pip install django-fluent-contents

The additional plugins may add additional requirements; the plugins will warn about then when they are used for the first time. For optional dependency management, it is strongly recommended that you run the application inside a virtualenv.

Basic setup

Next, create a project which uses the module. The basic module can be installed and optional plugins can be added:


    # And optionally add the desired plugins:
    'fluent_contents.plugins.text',                # requires django-wysiwyg
    'fluent_contents.plugins.code',                # requires pygments

Since some extra plugins are used here, make sure their applications are installed:

pip install django-fluent-contents[text,code]


Each plugin is optional. Only the fluent_contents application is required, allowing to write custom models and plugins. Since a layout with the text and code plugin form a good introduction, these are added here.

Afterwards, you can setup the database:

./manage.py syncdb

Displaying content

Finally, it needs a model or application that displays the content. The most simply way, is adding a PlaceholderField to a model:

class Article(models.Model):
    title = models.CharField("Title", max_length=200)
    content = PlaceholderField("article_content")

    class Meta:
        verbose_name = "Article"
        verbose_name_plural = "Articles"

    def __unicode__(self):
        return self.title

Make sure the admin screen the PlaceholderFieldAdmin class. This makes sure additional inlines are added the the admin screen:

class ArticleAdmin(PlaceholderFieldAdmin):

admin.site.register(Article, ArticleAdmin)

No extra configuration is required, the field will simply blend in with the rest of the form fields. Gven that the article is displayed by a template (i.e. article/details.html) it can use the fluent_contents_tags to display the contents:

{% load fluent_contents_tags %}
{% render_placeholder article.content %}

That’s it!

Fieldset layout

With a small change in the fieldsets configuration, the admin interface could look like this:

django-fluent-contents placeholder field preview

When the placeholder is used in a separate fieldset that has a plugin-holder class name, the field will be displayed without a label in front of it:

class ArticleAdmin(PlaceholderFieldAdmin):
    prepopulated_fields = {'slug': ('title',)}

    fieldsets = (
        (None, {
            'fields': ('title', 'slug'),
        ("Contents", {
            'fields': ('content',),
            'classes': ('plugin-holder',),

django-fluent-contents placeholder field preview

Optional features

To add even more plugins, use:


    # Dependencies for plugins:

    # All plugins:
    'fluent_contents.plugins.text',                # requires django-wysiwyg
    'fluent_contents.plugins.code',                # requires pygments

    'fluent_contents.plugins.commentsarea',        # requires django.contrib.comments + templates
    'fluent_contents.plugins.disquswidgets',       # requires django-disqus + DISQUS_API_KEY
    'fluent_contents.plugins.formdesignerlink',    # requires django-form-designer from github.


FLUENT_MARKUP_LANGUAGE = 'reStructuredText'        # can also be markdown or textile

Most of the features are glue to existing Python or Django modules, hence these packages need to be installed:

They can be installed using:

pip install django-fluent-contents[text,code,markup,disquscommentsarea,formdesignerlink]

The reason that all these features are optional is make them easily swappable for other implementations. You can use a different comments module, or invert new content plugins. It makes the CMS configurable in the way that you see fit.

Some plugins, like the commentsarea based on django.contrib.comments, might make a bad first impression because they have no default layout. This turns out however to be by design, to make them highly adaptable to your design and requirements.

Creating a CMS system

The django-fluent-contents package also offers a PlaceholderEditorAdmin class which allows CMS-developers to display the content plugins at various locations of a CMS page. For more information, see the Creating a CMS system.

Testing your new shiny project

Congrats! At this point you should have a working installation. Now you can just login to your admin site and see what changed.

Production notes

When deploying the project to production, enable the following setting:


This improves the performance of the template tags.