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:
INSTALLED_APPS += (
'fluent_contents',
'django_wysiwyg',
# And optionally add the desired plugins:
'fluent_contents.plugins.text', # requires django-wysiwyg
'fluent_contents.plugins.code', # requires pygments
'fluent_contents.plugins.gist',
'fluent_contents.plugins.googledocsviewer',
'fluent_contents.plugins.iframe',
'fluent_contents.plugins.markup',
'fluent_contents.plugins.rawhtml',
)
Since some extra plugins are used here, make sure their applications are installed:
pip install django-fluent-contents[text,code]
Note
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):
pass
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:
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',),
})
)
Optional features¶
To add even more plugins, use:
INSTALLED_APPS += (
'fluent_contents',
# Dependencies for plugins:
'disqus',
'django.contrib.comments',
'django_wysiwyg',
'form_designer',
# All plugins:
'fluent_contents.plugins.text', # requires django-wysiwyg
'fluent_contents.plugins.code', # requires pygments
'fluent_contents.plugins.gist',
'fluent_contents.plugins.googledocsviewer',
'fluent_contents.plugins.iframe',
'fluent_contents.plugins.markup',
'fluent_contents.plugins.rawhtml',
'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-ai
)
DISQUS_API_KEY = '...'
DISQUS_WEBSITE_SHORTNAME = '...'
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:
- django-wysiwyg (for the text plugin)
- Pygments (for the code plugin)
- docutils (for the markup plugin)
- django-disqus (for the disquscommentsarea plugin)
- django-form-designer-ai (for the formdesignerlink plugin)
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:
FLUENT_CONTENTS_CACHE_PLACEHOLDER_OUTPUT = True
This improves the performance of the template tags.