cmsplugin_form_handler.cms_plugins

This module contains an alternative super-class for CMS plugins that encapsulates all plugin-related cmsplugin-form-handler logic.

FormPluginBase

class cmsplugin_form_handler.cms_plugins.FormPluginBase

This class is a sub-class of the normal cms.plugin_base.CMSPluginBase but offers additional functionality for dealing with plugin-based forms.

Attributes

cmsplugin_form_handler.cms_plugins.cache

This base-class will automatically set the normal cache attribute to False. This can be overridden in the project’s plugin class, but it is not recommended because presenting a form should also include a CSRF token, which should never be cached.

cmsplugin_form_handler.cms_plugins.form_class

Set this to the forms.Form or forms.ModelForm you wish this plugin to present. If the project needs to determine which form to present based on the specific plugin instance, implement get_form_class() instead.

cmsplugin_form_handler.cms_plugins.success_url

Set this to the URL of the “success page” of the form. Using this attribute is simple and suitable for static success URLs. If the project needs to determine the URL based on the request or the plugin instance, implement get_success_url() instead.

Methods

cmsplugin_form_handler.cms_plugins.get_form_class(request, instance)

Returns the class of the form that this plugin presents. The default implementation of this method is to simply return the contents of form_class. Override this method if different plugins instances of the same plugin class should return different forms.

Parameters:

• request (HTTPRequest) – This is the request object for the form-submission. This may be useful for making a determination about which form class to return.
• instance (CMSPlugin) – This is the CMS plugin instance of the plugin used to produce the form.

cmsplugin_form_handler.cms_plugins.get_form_kwargs(self, request, instance)

The return value of this method is added as kwargs when instantiating the form. This is useful if you need to pass additional parameters to the form.

Parameters:

• request (HTTPRequest) – This is the request object for the form-submission. This may be useful for determining which kwargs to send.
• instance (CMSPlugin) – This is the CMS plugin instance of the plugin used to produce the form. This may be useful for determining which kwargs to send.

The default implementation returns an empty dict.

cmsplugin_form_handler.cms_plugins.get_success_url(request, instance)

Returns the desired URL that the user should be redirected to if their form submission validates.

Parameters:

• request (HTTPRequest) – This is the request object for the form-submission. This may be useful for making a determination about which success URL to return.
• instance (CMSPlugin) – This is the CMS plugin instance of the plugin used to produce the form. (Hint: you could present a list of choices in the CMSPlugin``model using a ``cms.models.fields.PageField.)

The default implementation of this method is to simply return the contents of success_url, but in most cases, a static URL is inappropriate. For example, it may be better to return the absolute URL of a specific CMS page (which could be moved by the content managers to different paths). In this case, something like this may be useful:

# NOTE: only relevant code is shown here...

from cms.models import Page
from cms.utils import get_language_from_request
from cms.utils.i18n import get_default_language

from cmsplugin_form_handler.cms_plugins import FormPluginBase

class SomePlugin(FormPluginBase):
    ...
    success_url = '/'  # a sane default
    ...

    def get_success_url(self, request, instance):
        # Be sure to set this in the Advanced Settings tab of the
        # desired CMS Page.
        reverse_id = 'success_page'

        # We'll need to know which language is relevant...
        lang = get_language_from_request(request) or get_default_language()

        try:
            page = Page.objects.get(
                reverse_id=reverse_id,
                publisher_is_draft=False
            )
        except Page.DoesNotExist:
            # Can't find the success page, return the something sane...
            return self.success_url
        else:
            return page.get_absolute_url(lang)

Or, as hinted above, you could use the CMSPlugin model to present a set of choices using a cms.models.fields.PageField to the Content Manager when creating the plugin instance, then, use the get_success_url method to return the absolute URL of the selected choice.

cmsplugin_form_handler.cms_plugins.form_valid(request, instance, form)

This method is called if the form is valid.

Parameters:

• request (HTTPRequest) – This is the request object for the form-submission. This may be useful for determining what to do with the valid form.
• instance (CMSPlugin) – This is the CMS plugin instance of the plugin used to produce the form.
• form (Form) – This is the validated form.

The default implementation simply calls the save method on the form.