The fluent_contents package defines two models, for storing the content data:

Secondly, there are a few possible fields to add to parent models:

Finally, to exchange template data, a PlaceholderData object is available which mirrors the relevant fields of the Placeholder model.

The Placeholder class

class fluent_contents.models.Placeholder(*args, **kwargs)

The placeholder groups various ContentItem models together in a single compartment. It is the reference point to render custom content. Each placeholder is identified by a slot name and parent object.

Optionally, the placeholder can have a title, and role. The role is taken into account by the client-side placeholder editor when a page switches template layouts. Content items are migrated to the apropriate placeholder, first matched by slot name, secondly matched by role.

The parent object is stored in a generic relation, so the placeholder can be used with any custom object. By adding a PlaceholderRelation field to the parent model, the relation can be traversed backwards. From the placeholder, the contentitem_set can be traversed to find the associated ContentItem objects. Since a ContentItem is polymorphic, the actual sub classes of the ContentItem will be returned by the query. To prevent this behavior, call non_polymorphic() on the QuerySet.

  • id (AutoField) – Id
  • slot (SlugField) – A short name to identify the placeholder in the template code.
  • role (CharField) – This defines where the object is used.
  • parent_type_id (ForeignKey to ContentType) – Parent type
  • parent_id (IntegerField) – Parent id
  • title (CharField) – Admin title
get_absolute_url(*moreargs, **morekwargs)

Return the URL of the parent object, if it has one. This method mainly exists to support cache mechanisms (e.g. refreshing a Varnish cache), and assist in debugging.


Return the plugins which are supported in this placeholder.

get_content_items(parent=None, limit_parent_language=True)

Return all models which are associated with this placeholder. Because a ContentItem is polymorphic, the actual sub classes of the content item will be returned by the query.

By passing the parent object, the items can additionally be filtered by the parent language.


Get the search text for all contents of this placeholder.

Parameters:fallback_language (bool|str) – The fallback language to use if there are no items in the current language. Passing True uses the default FLUENT_CONTENTS_DEFAULT_LANGUAGE_CODE.
Return type:str

The PlaceholderManager class

class fluent_contents.models.PlaceholderManager

Extra methods for the Placeholder.objects.

create_for_object(parent_object, slot, role='m', title=None)

Create a placeholder with the given parameters

get_by_slot(parent_object, slot)

Return a placeholder by key.


Return all placeholders which are associated with a given parent object.

The ContentItem class

class fluent_contents.models.ContentItem(*args, **kwargs)

A ContentItem represents a content part (also called pagelet in other systems) which is displayed in a Placeholder. To use the ContentItem, derive it in your model class:

class ExampleItem(ContentItem):
    # any custom fields here

    class Meta:
        verbose_name = "Example item"

All standard Django model fields can be used in a ContentItem. Some things to note:

  • There are special fields for URL, WYSIWYG and file/image fields, which keep the admin styles consistent. These are the PluginFileField, PluginHtmlField, PluginImageField and PluginUrlField fields. See the Custom model fields section for more details.
  • When adding a M2M field, make sure to override copy_to_placeholder, so the M2M data will be copied.

When querying the objects through the ORM, the derived instances will be returned automatically. This happens because the ContentItem class is polymorphic:

>>> from fluent_contents.models import ContentItem
>>> ContentItem.objects.all()
[<ArticleTextItem: Main article>, <RawHtmlItem: test>, <CodeItem: def foo(): print 1>,
<AnnouncementBlockItem: Test>, <ArticleTextItem: Text in sidebar>]

Note that the django-polymorphic application is written in such way, that this requires the least amount of queries necessary. When access to the polymorphic classes is not needed, call non_polymorphic() on the QuerySet to prevent this behavior:

>>> from fluent_contents.models import ContentItem
>>> ContentItem.objects.all().non_polymorphic()
[<ContentItem: Article text item#1 in 'Main content'>, <ContentItem: HTML code#5 in 'Main content'>, <ContentItem: Code snippet#6 in 'Main content'>,
<ContentItem: Announcement block#7 in 'Main content'>, <ContentItem: Article text item#4 in 'Sidebar'>]

Being polymorphic also means the base class provides some additional methods such as:

  • get_real_instance()
  • get_real_instance_class()

Each ContentItem references both it’s parent object (e.g. a page, or article), and the placeholder. While this is done mainly for internal reasons, it also provides an easy way to query all content items of a parent. The parent object is stored in a generic relation, so the ContentItem can be used with any custom object. By adding a ContentItemRelation field to the parent model, the relation can be traversed backwards.

Because the ContentItem references it’s parent, and not the other way around, it will be cleaned up automatically by Django when the parent object is deleted.

To use a ContentItem in the PlaceholderField, register it via a plugin definition. see the ContentPlugin class for details.

The rendering of a ContentItem class happens in the associate ContentPlugin class. To render content items outside the template code, use the fluent_contents.rendering module to render the items.

  • id (AutoField) – Id
  • polymorphic_ctype_id (ForeignKey to ContentType) – Polymorphic ctype
  • parent_type_id (ForeignKey to ContentType) – Parent type
  • parent_id (IntegerField) – Parent id
  • language_code (CharField) – Language code
  • placeholder_id (ForeignKey to Placeholder) – Placeholder
  • sort_order (IntegerField) – Sort order
copy_to_placeholder(placeholder, sort_order=None, in_place=False)

Note: if you have M2M relations on the model, override this method to transfer those values.

get_absolute_url(*moreargs, **morekwargs)

Return the URL of the parent object, if it has one. This method mainly exists to refreshing cache mechanisms.


Get a list of all cache keys associated with this model. This queries the associated plugin for the cache keys it used to store the output at.

move_to_placeholder(placeholder, sort_order=None)

The object is saved afterwards.

The PlaceholderField class

class fluent_contents.models.PlaceholderField(slot, plugins=None, **kwargs)

The model field to add ContentItem objects to a model.

  • slot (str) – A programmatic name to identify the placeholder.
  • plugins (list) – Optional, define which plugins are allowed to be used. This can be a list of names, or ContentPlugin references.

This class provides the form fields for the field. Use this class in a model to use it:

class Article(models.Model):
    contents = PlaceholderField("article_contents")

The data itself is stored as reverse relation in the ContentItem object. Hence, all contents will be cleaned up properly when the parent model is deleted.

The placeholder will be displayed in the admin:

django-fluent-contents placeholder field preview
contribute_to_class(cls, name)

Internal Django method to associate the field with the Model; it assigns the descriptor.


Returns a PlaceholderFormField instance for this database Field.


Get the set of plugins that this field may display.


alias of PlaceholderRel


Internal Django method, used to return the placeholder ID when exporting the model instance.

The PlaceholderRelation class

class fluent_contents.models.PlaceholderRelation(**kwargs)

A GenericRelation which can be applied to a parent model that is expected to be referenced be a Placeholder. For example:

class Page(models.Model):
    placeholder_set = PlaceholderRelation()

The ContentItemRelation class

class fluent_contents.models.ContentItemRelation(**kwargs)

A GenericRelation which can be applied to a parent model that is expected to be referenced by the ContentItem classes. For example:

class Page(models.Model):
    contentitem_set = ContentItemRelation()

Adding this relation also causes the admin delete page to list the ContentItem objects which will be deleted.

The PlaceholderData class

class fluent_contents.models.PlaceholderData(slot, title=None, role=None, fallback_language=None)

A wrapper with data of a placeholder node. It shares the slot, title and role fields with the Placeholder class.


Return the contents as dictionary, for client-side export. The dictionary contains the fields:

  • slot
  • title
  • role
  • fallback_language
  • allowed_plugins

The ContentItemOutput class

class fluent_contents.models.ContentItemOutput(html, media=None, cacheable=True, cache_timeout=<object object>)

A wrapper with holds the rendered output of a plugin, This object is returned by the render_placeholder() and ContentPlugin.render() method.

Instances can be treated like a string object, but also allows reading the html and media attributes.

The get_parent_lookup_kwargs function


Return lookup arguments for the generic parent_type / parent_id fields.

Parameters:parent_object (Model) – The parent object.