fluent_contents.extensions¶
Special classes to extend the module; e.g. plugins.
The extension mechanism is provided for projects that benefit from a tighter integration then the Django URLconf can provide.
The API uses a registration system.
While plugins can be easily detected via __subclasses__()
, the register approach is less magic and more explicit.
Having to do an explicit register ensures future compatibility with other API’s like reversion.
The ContentPlugin
class¶
-
class
fluent_contents.extensions.
ContentPlugin
¶ The base class for all content plugins.
A plugin defines the rendering for a
ContentItem
, settings and presentation in the admin interface. To create a new plugin, derive from this class and callplugin_pool.register
to enable it. For example:from fluent_contents.extensions import plugin_pool, ContentPlugin @plugin_pool.register class AnnouncementBlockPlugin(ContentPlugin): model = AnnouncementBlockItem render_template = "plugins/announcementblock.html" category = _("Simple blocks")
As minimal configuration, specify the
model
andrender_template
fields. Themodel
should be a subclass of theContentItem
model class.Note
When the plugin is registered in the
plugin_pool
, it will be instantiated only once. It is therefore not possible to store per-request state at the plugin object. This is similar to the behavior of theModelAdmin
classes in Django.To customize the admin, the
admin_form_template
andform
can be defined. Some well known properties of theModelAdmin
class can also be specified on plugins; such as:fieldsets
filter_horizontal
filter_vertical
prepopulated_fields
radio_fields
raw_id_fields
readonly_fields
- A
class Media
to provide extra CSS and JavaScript files for the admin interface.
The rendered output of a plugin is cached by default, assuming that most content is static. This also avoids extra database queries to retrieve the model objects. In case the plugin needs to output content dynamically, include
cache_output = False
in the plugin definition.-
ADMIN_TEMPLATE_WITHOUT_LABELS
= 'admin/fluent_contents/contentitem/admin_form_without_labels.html'¶ Alternative template for the view.
-
ADVANCED
= 'Advanced'¶ New in version 1.1.
Category for advanced plugins (e.g. raw HTML, iframes)
-
HORIZONTAL
= 1¶ New in version 0.8.5.
The
HORIZONTAL
constant for theradio_fields
.
-
INTERACTIVITY
= 'Interactivity'¶ New in version 1.1.
Category for interactive plugins (e.g. forms, comments)
-
MEDIA
= 'Media'¶ New in version 1.1.
Category for media
-
PROGRAMMING
= 'Programming'¶ New in version 1.1.
Category for programming plugins
-
VERTICAL
= 2¶ New in version 0.8.5.
The
VERTICAL
constant for theradio_fields
.
-
admin_form_template
= 'admin/fluent_contents/contentitem/admin_form.html'¶ The template to render the admin interface with
-
admin_init_template
= None¶ An optional template which is included in the admin interface, to initialize components (e.g. JavaScript)
-
cache_output
= True¶ By default, rendered output is cached, and updated on admin changes.
-
cache_output_per_language
= False¶ New in version 1.0.
Cache the plugin output per language. This can be useful for sites which either:
- Display fallback content on pages, but still use
{% trans %}
inside templates. - Dynamically switch the language per request, and share content between multiple languages.
This option does not have to be used for translated CMS pages, as each page can have it’s own set of
ContentItem
objects. It’s only needed for rendering the same item in different languages.- Display fallback content on pages, but still use
-
cache_supported_language_codes
= ['af', 'ar', 'ar-dz', 'ast', 'az', 'bg', 'be', 'bn', 'br', 'bs', 'ca', 'cs', 'cy', 'da', 'de', 'dsb', 'el', 'en', 'en-au', 'en-gb', 'eo', 'es', 'es-ar', 'es-co', 'es-mx', 'es-ni', 'es-ve', 'et', 'eu', 'fa', 'fi', 'fr', 'fy', 'ga', 'gd', 'gl', 'he', 'hi', 'hr', 'hsb', 'hu', 'hy', 'ia', 'id', 'ig', 'io', 'is', 'it', 'ja', 'ka', 'kab', 'kk', 'km', 'kn', 'ko', 'ky', 'lb', 'lt', 'lv', 'mk', 'ml', 'mn', 'mr', 'my', 'nb', 'ne', 'nl', 'nn', 'os', 'pa', 'pl', 'pt', 'pt-br', 'ro', 'ru', 'sk', 'sl', 'sq', 'sr', 'sr-latn', 'sv', 'sw', 'ta', 'te', 'tg', 'th', 'tk', 'tr', 'tt', 'udm', 'uk', 'ur', 'uz', 'vi', 'zh-hans', 'zh-hant']¶ New in version 1.0.
Tell which languages the plugin will cache. It defaults to the language codes from the
LANGUAGES
setting.
-
cache_timeout
= <object object>¶ Set a custom cache timeout value
-
category
= None¶ The category title to place the plugin into. This is only used for the “Add Plugin” menu. You can provide a string here,
ugettext_lazy()
or one of the predefined constants (MEDIA
,INTERACTIVITY:
,PROGRAMMING
andADVANCED
).
-
filter_horizontal
= ()¶ The fields to display in a horizontal filter
-
filter_vertical
= ()¶ The fields to display in a vertical filter
-
form
¶ alias of
fluent_contents.forms.ContentItemForm
-
formfield_overrides
= {}¶ Overwritten formfield attributes, e.g. the ‘widget’. Allows both the class and fieldname as key.
-
frontend_media
¶ New in version 1.0.
The frontend media, typically declared using a
class FrontendMedia
definition.
-
get_cached_output
(placeholder_name, instance)¶ New in version 0.9: Return the cached output for a rendered item, or
None
if no output is cached.This method can be overwritten to implement custom caching mechanisms. By default, this function generates the cache key using
get_output_cache_key()
and retrieves the results from the configured Django cache backend (e.g. memcached).
-
get_context
(request, instance, **kwargs)¶ Return the context to use in the template defined by
render_template
(orget_render_template()
). By default, it returns the model instance asinstance
field in the template.
-
get_frontend_media
(instance)¶ Return the frontend media for a specific instance. By default, it returns
self.frontend_media
, which derives from theclass FrontendMedia
of the plugin.
-
get_model_instances
()¶ Return the model instances the plugin has created.
-
get_output_cache_base_key
(placeholder_name, instance)¶ New in version 1.0: Return the default cache key, both
get_output_cache_key()
andget_output_cache_keys()
rely on this. By default, this function generates the cache key usingget_rendering_cache_key()
.
-
get_output_cache_key
(placeholder_name, instance)¶ New in version 0.9: Return the default cache key which is used to store a rendered item. By default, this function generates the cache key using
get_output_cache_base_key()
.
-
get_output_cache_keys
(placeholder_name, instance)¶ New in version 0.9: Return the possible cache keys for a rendered item.
This method should be overwritten when implementing a function
set_cached_output()
method or when implementing aget_output_cache_key()
function. By default, this function generates the cache key usingget_output_cache_base_key()
.
-
get_render_template
(request, instance, **kwargs)¶ Return the template to render for the specific model instance or request, By default it uses the
render_template
attribute.
-
get_search_text
(instance)¶ Return a custom search text for a given instance.
Note
This method is called when
search_fields
is set.
-
model
= None¶ The model to use, must derive from
fluent_contents.models.ContentItem
.
-
name
¶ Return the classname of the plugin, this is mainly provided for templates. This value can also be used in
PluginPool()
.
-
prepopulated_fields
= {}¶ Fields to automatically populate with values
-
radio_fields
= {}¶ The fields to display as radio choice. For example:
radio_fields = { 'align': ContentPlugin.VERTICAL, }
The value can be
ContentPlugin.HORIZONTAL
orContentPlugin.VERTICAL
.
-
raw_id_fields
= ()¶ The fields to display as raw ID
-
readonly_fields
= ()¶ The fields to display as readonly.
-
redirect
(url, status=302)¶ New in version 1.0.
Request a redirect to be performed for the user. Usage example:
def get_context(self, request, instance, **kwargs): context = super(IdSearchPlugin, self).get_context(request, instance, **kwargs) if request.method == "POST": form = MyForm(request.POST) if form.is_valid(): self.redirect("/foo/") else: form = MyForm() context['form'] = form return context
To handle redirects,
fluent_contents.middleware.HttpRedirectRequestMiddleware
should be added to theMIDDLEWARE_CLASSES
.
-
render
(request, instance, **kwargs)¶ The rendering/view function that displays a plugin model instance.
Parameters: - instance – An instance of the
model
the plugin uses. - request – The Django
HttpRequest
class containing the request parameters. - kwargs – An optional slot for any new parameters.
To render a plugin, either override this function, or specify the
render_template
variable, and optionally overrideget_context()
. It is recommended to wrap the output in a<div>
tag, to prevent the item from being displayed right next to the previous plugin.New in version 1.0: The function may either return a string of HTML code, or return a
ContentItemOutput
object which holds both the CSS/JS includes and HTML string. For the sake of convenience and simplicity, most examples only return a HTML string directly.When the user needs to be redirected, simply return a
HttpResponseRedirect
or call theredirect()
method.To render raw HTML code, use
mark_safe()
on the returned HTML.- instance – An instance of the
-
render_error
(error)¶ A default implementation to render an exception.
-
render_ignore_item_language
= False¶ New in version 1.0.
By default, the plugin is rendered in the
language_code
it’s written in. It can be disabled explicitly in case the content should be rendered language agnostic. For plugins that cache output per language, this will be done already.See also:
cache_output_per_language
-
render_template
= None¶ The template to render the frontend HTML output.
-
render_to_string
(request, template, context, content_instance=None)¶ Render a custom template with the
PluginContext
as context instance.
-
search_fields
= []¶ Define which fields could be used for indexing the plugin in a site (e.g. haystack)
-
search_output
= None¶ Define whether the full output should be used for indexing.
-
set_cached_output
(placeholder_name, instance, output)¶ New in version 0.9: Store the cached output for a rendered item.
This method can be overwritten to implement custom caching mechanisms. By default, this function generates the cache key using
get_rendering_cache_key()
and stores the results in the configured Django cache backend (e.g. memcached).When custom cache keys are used, also include those in
get_output_cache_keys()
so the cache will be cleared when needed.Changed in version 1.0: The received data is no longer a HTML string, but
ContentItemOutput
object.
-
type_id
¶ Shortcut to retrieving the ContentType id of the model.
-
type_name
¶ Return the classname of the model, this is mainly provided for templates.
-
verbose_name
¶ The title for the plugin, by default it reads the
verbose_name
of the model.
The PluginPool
class¶
-
class
fluent_contents.extensions.
PluginPool
¶ The central administration of plugins.
-
__init__
()¶ Initialize self. See help(type(self)) for accurate signature.
-
get_allowed_plugins
(placeholder_slot)¶ Return the plugins which are supported in the given placeholder name.
-
get_model_classes
()¶ Return all
ContentItem
model classes which are exposed by plugins.
-
get_plugin_by_model
(model_class)¶ Return the corresponding plugin for a given model.
You can also use the
ContentItem.plugin
property directly. This is the low-level function that supports that feature.
-
get_plugins
()¶ Return the list of all plugin instances which are loaded.
-
get_plugins_by_name
(*names)¶ Return a list of plugins by plugin class, or name.
-
register
(plugin)¶ Make a plugin known to the CMS.
Parameters: plugin ( ContentPlugin
) – The plugin class, deriving fromContentPlugin
.The plugin will be instantiated once, just like Django does this with
ModelAdmin
classes. If a plugin is already registered, this will raise aPluginAlreadyRegistered
exception.
-
The plugin_pool
attribute¶
-
fluent_contents.extensions.
plugin_pool
¶ The global plugin pool, a instance of the
PluginPool
class.
Model fields¶
New in version 0.9.0.
The model fields ensure a consistent look and feel between plugins. It’s recommended to use these fields instead of the standard Django counterparts, so all plugins have a consistent look and feel. See Optional integration with other packages for more details.
-
class
fluent_contents.extensions.
PluginFileField
(verbose_name=None, name=None, upload_to='', storage=None, **kwargs)¶ A file upload field for plugins.
Use this instead of the standard
FileField
.
-
class
fluent_contents.extensions.
PluginHtmlField
(*args, **kwargs)¶ A HTML field for plugins.
This field is replaced with a django-wysiwyg editor in the admin.
-
__init__
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
formfield
(**kwargs)¶ Return a django.forms.Field instance for this field.
-
to_python
(html)¶ Convert the input value into the expected Python data type, raising django.core.exceptions.ValidationError if the data can’t be converted. Return the converted value. Subclasses should override this.
-
-
class
fluent_contents.extensions.
PluginImageField
(verbose_name=None, name=None, width_field=None, height_field=None, **kwargs)¶ An image upload field for plugins.
Use this instead of the standard
ImageField
.
Classes for custom forms¶
New in version 0.9.0: The canonical place to import this class has moved, previously it was available via fluent_contents.forms
.
-
class
fluent_contents.extensions.
ContentItemForm
(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, instance=None, use_required_attribute=None, renderer=None)¶ The base form for custom
ContentItem
types. It displays the additional meta fields as hidden fields.When creating custom admin forms (e.g. to add validation for specific fields), use this class as base to ensure all fields are properly set up.
Other classes¶
-
class
fluent_contents.extensions.
PluginContext
(request, dict=None, current_app=None)¶ A template Context class similar to
RequestContext
, that enters some pre-filled data. This ensures that variables such asSTATIC_URL
andrequest
are available in the plugin templates.-
__init__
(request, dict=None, current_app=None)¶ Initialize self. See help(type(self)) for accurate signature.
-
-
exception
fluent_contents.extensions.
PluginAlreadyRegistered
¶ Raised when attemping to register a plugin twice.
-
exception
fluent_contents.extensions.
PluginNotFound
¶ Raised when the plugin could not be found in the rendering process.