Skip to main content

Easy plugin forms for django CMS

Project description

PyPI Version Build Status Coverage Status

This package provides a mechanism for handling form-submissions in django-CMS plugins.

Jump to Quickstart below to get started, or see the proper documentation.

Background & Approach

Background

Plugins are a key component of django CMS for creating reusable, configurable content fragments in django CMS projects. Due to their flexibility and utility, project developers would benefit from emitting forms and handling form submissions using plugins.

Since CMS plugins are fragments of a page, they do not provide a unique, URL for receiving and handling form submissions. This presents numerous challenges when attempting to process form submissions.

Approach

To get around these limitations, the approach taken in this package is to direct form submissions from plugins which sub-class FormPluginBase to a URL that is outside of the django CMS URL-space and handled by a ProcessFormView provided by this package.

The ProcessFormView accepts form-submissions, processes them, and if valid, sends the resulting form back to the plugin class for handling and then responds to the request with a redirect to a success_url provided by the plugin.

On validation errors, the view will redirect the request back to the originating page and provide the form data via a session variable back to the plugin’s form.

The user experience is precisely as expected and the handling of the form is performed without “thrown HTTPRedirectResponses” or any special middleware.

This package encapsulates all extra logic so that the plugin developer need only to subclass FormPluginBase rather than the usual cms.plugin_base.CMSPluginBase.

The Form or ModelForm presented in the CMS plugin should also include the “mixin” FormPluginFormMixin.

Quickstart

To get started quickly, first install the package:

pip install cmsplugin-form-handler

Add the package to settings.INSTALLED_APPS:

# my_cool_project/settings.py

INSTALLED_APPS = (
    ...
    'cmsplugin_form_handler',
)

Add an extra line in your url configuration:

urlpatterns = i18n_patterns('',
    url(r'^admin/', include(admin.site.urls)),
    ...
    url(r'^plugin_forms/', include('cmsplugin_form_handler.urls',
                                   namespace='cmsplugin_form_handler')),
    url(r'^', include('cms.urls')),
)

Add the FormPluginFormMixin mixin to your Form:

# my_cool_project/forms.py

from django import forms
from cmsplugin_form_handler.forms import FormPluginFormMixin

class MyCoolForm(FormPluginFormMixin, forms.Form):
    # everything else is your normal form.
    my_cool_field = forms.CharField(...)
    ...

Or, if you’re using a ModelForm:

# my_cool_project/forms.py

from django import forms
from cmsplugin_form_handler.forms import FormPluginFormMixin

class MyCoolModelForm(FormPluginFormMixin, forms.ModelForm):
    # everything else is your normal form.
    class Meta:
        model = MyCoolModel
    ...

Subclass your cms plugin from FormPluginBase:

# my_cool_project/cms_plugins.py

from cmsplugin_form_handler.cms_plugins import FormPluginBase

class MyCoolPlugin(FormPluginBase):
    # Use your normal CMSPlugin attributes...
    render_template = 'plugins/my_cool_plugin.html'
    # Note that ``cache = False`` will automatically be set

    # These should be overridden in sub-classes
    form_class = MyCoolForm  # Or, see: get_form_class()
    success_url = '/static/success/url/here'  # Or, see: get_success_url()

    def render(self, context, instance, placeholder):
        context = super(MyCoolPlugin, self).render(context, instance, placeholder)

        # Do your normal thing here
        ...

        return context

    def get_form_class(self, request, instance):
        # Use this method to programmatically determine the form_class.
        # This is what this method does by default:
        return self.form_class

    def get_success_url(self, request, instance):
        # Use this method to programmatically determine the success_url.
        # This is what this method does by default:
        return self.success_url

    def form_valid(self, request, instance, form):
        # Optionally do something with the rendered form here
        # This is what this method does by default:
        form.save()

Finally, update your plugin’s template:

# my_cool_project/templates/plugins/my_cool_plugin.html

{% load cmsplugin_form_tags %}

<h2>Form Plugin</h2>
<form action="{% cmsplugin_form_action %}" method="post">
    {% csrf_token %}
    {{ cmsplugin_form }}
    <input type="submit">
</form>

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cmsplugin-form-handler-0.2.0.tar.gz (1.2 MB view details)

Uploaded Source

Built Distribution

cmsplugin_form_handler-0.2.0-py3-none-any.whl (21.4 kB view details)

Uploaded Python 3

File details

Details for the file cmsplugin-form-handler-0.2.0.tar.gz.

File metadata

File hashes

Hashes for cmsplugin-form-handler-0.2.0.tar.gz
Algorithm Hash digest
SHA256 1331add5e0d221da0fdacffab822b0d3bdc6ec9016344e7a4d793be0cc5e62e6
MD5 b8d43d4263f39303b489027de926032f
BLAKE2b-256 312034f457eda82dc370cd9e8aa40790d25c353194e994435ea5f1079f5b0014

See more details on using hashes here.

File details

Details for the file cmsplugin_form_handler-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for cmsplugin_form_handler-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8edd4f2c9f2a3a53b8aab16db5a523e451e8f87e534c5603e3fb10f281746a2f
MD5 c3308a17e0129e40aef313bd66cbedd0
BLAKE2b-256 c6885ba0493a3cb8bb7c0b57a5cd074902906a09a17888c10cbb4111820706d7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page