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 call plugin_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 and render_template fields. The model should be a subclass of the ContentItem 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 the ModelAdmin classes in Django.

To customize the admin, the admin_form_template and form can be defined. Some well known properties of the ModelAdmin class can also be specified on plugins; such as:

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 the radio_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 the radio_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.

cache_output_per_site = False

New in version 0.9.

Cache the plugin output per SITE_ID.

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 and ADVANCED).

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 (or get_render_template()). By default, it returns the model instance as instance 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 the class 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() and get_output_cache_keys() rely on this. By default, this function generates the cache key using get_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 a get_output_cache_key() function. By default, this function generates the cache key using get_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 or ContentPlugin.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 the MIDDLEWARE_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 override get_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 the redirect() method.

To render raw HTML code, use mark_safe() on the returned HTML.

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 from ContentPlugin.

The plugin will be instantiated once, just like Django does this with ModelAdmin classes. If a plugin is already registered, this will raise a PluginAlreadyRegistered 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.

class fluent_contents.extensions.PluginUrlField(*args, **kwargs)

An URL field for plugins.

Use this instead of the standard URLField.

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 as STATIC_URL and request 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.