fluent_contents.models¶
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, thecontentitem_set
can be traversed to find the associatedContentItem
objects. Since aContentItem
is polymorphic, the actual sub classes of theContentItem
will be returned by the query. To prevent this behavior, callnon_polymorphic()
on the QuerySet.Parameters: - id (AutoField) – Id
- slot (SlugField) – Slot. A short name to identify the placeholder in the template code.
- role (CharField) – Role. This defines where the object is used.
- parent_type (ForeignKey to
ContentType
) – Parent type - parent_id (IntegerField) – Parent id
- title (CharField) – Admin title
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
get_absolute_url
()¶ 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.
-
get_allowed_plugins
()¶ 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_search_text
(fallback_language=None)¶ 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.
-
parent
(parent_object)¶ 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
andPluginUrlField
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 theContentPlugin
class for details.The rendering of a ContentItem class happens in the associate
ContentPlugin
class. To render content items outside the template code, use thefluent_contents.rendering
module to render the items.Parameters: - id (AutoField) – Id
- polymorphic_ctype (ForeignKey to
ContentType
) – Polymorphic ctype - parent_type (ForeignKey to
ContentType
) – Parent type - parent_id (IntegerField) – Parent id
- language_code (CharField) – Language code
- placeholder (ForeignKey to
Placeholder
) – Placeholder - sort_order (IntegerField) – Sort order
-
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
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
()¶ Return the URL of the parent object, if it has one. This method mainly exists to refreshing cache mechanisms.
-
get_cache_keys
()¶ 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.
-
plugin
¶ Access the parent plugin which renders this model.
Return type: ContentPlugin
-
save
(*args, **kwargs)¶ Calls
pre_save_polymorphic()
and saves the model.
- There are special fields for URL, WYSIWYG and file/image fields, which keep the admin styles consistent.
These are the
The PlaceholderField
class¶
-
class
fluent_contents.models.
PlaceholderField
(slot, plugins=None, **kwargs)¶ The model field to add
ContentItem
objects to a model.Parameters: - 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:
-
__init__
(slot, plugins=None, **kwargs)¶ Initialize the placeholder field.
-
contribute_to_class
(cls, name, **kwargs)¶ Internal Django method to associate the field with the Model; it assigns the descriptor.
-
formfield
(**kwargs)¶ Returns a
PlaceholderFormField
instance for this database Field.
-
plugins
¶ Get the set of plugins that this field may display.
-
rel_class
¶ alias of
PlaceholderRel
-
value_from_object
(obj)¶ 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 aPlaceholder
. For example:class Page(models.Model): placeholder_set = PlaceholderRelation()
-
__init__
(**kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
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 theContentItem
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.-
__init__
(**kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
Return all objects related to
objs
via thisGenericRelation
.
-
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
androle
fields with thePlaceholder
class.-
__init__
(slot, title=None, role=None, fallback_language=None)¶ Create the placeholder data with a slot, and optional title and role.
-
as_dict
()¶ 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()
andContentPlugin.render()
method.Instances can be treated like a string object, but also allows reading the
html
andmedia
attributes.-
__init__
(html, media=None, cacheable=True, cache_timeout=<object object>)¶ Initialize self. See help(type(self)) for accurate signature.
-