Skip to content


Repository files navigation


A plugin for django-fluent-contents to show a simple contact form.


  • Configurable fields.
  • Configurable layouts.
  • Phone number validation.
  • IP-Address detection.
  • Admin panel with submitted messages.
  • Email notification to staff members for new messages.
  • Optional capcha / reCAPTCHA support.


First install the module, preferably in a virtual environment. It can be installed from PyPI:

pip install fluentcms-contactform

Backend Configuration

First make sure the project is configured for django-fluent-contents.

Then add the following settings:

    'crispy_forms',    # for default template

The database tables can be created afterwards:

./ migrate

Now, the ContactFormPlugin can be added to your PlaceholderField and PlaceholderEditorAdmin admin screens.

Make sure the following settings are configured:

DEFAULT_FROM_EMAIL = '"Your Name" <>'

FLUENTCMS_CONTACTFORM_VIA = "Sitename"    # Will send a From: "Username via Sitename" email.

To have bootstrap 3 layouts, add:


IP address detection

This package stores the remote IP of the visitor in the model. The IP Address is read from the REMOTE_ADDR meta field. In case your site is behind a HTTP proxy (e.g. using Gunicorn or a load balancer), this would make all contact form submissions appear to be sent from the load balancer IP.

The best and most secure way to fix this, is using WsgiUnproxy middleware in your

from django.core.wsgi import get_wsgi_application
from django.conf import settings
from wsgiunproxy import unproxy

application = get_wsgi_application()
application = unproxy(trusted_proxies=settings.TRUSTED_X_FORWARDED_FOR_IPS)(application)

In your, you can define which hosts may pass the X-Forwarded-For header in the HTTP request. For example:


Updating the form layout

The default form fields can be changed using:

FLUENTCMS_CONTACTFORM_DEFAULT_FIELDS = ('name', 'email', 'phone_number', 'subject', 'message')

# default CSS styles

For example, the subject can be removed using:

FLUENTCMS_CONTACTFORM_DEFAULT_FIELDS = ('name', 'email', 'phone_number', 'message')

Adding form fields

The form layout is fully configurable, as you can select your own form classes. The default settings are:

    ('default', {
        'title': _("Default"),
        'form_class': 'fluentcms_contactform.forms.default.DefaultContactForm',
        'required_apps': (),
    ('captcha', {
        'title': _("Default with captcha"),
        'form_class': 'fluentcms_contactform.forms.captcha.CaptchaContactForm',
        'required_apps': ('captcha',),
    ('recaptcha', {
        'title': _("Default with reCAPTCHA"),
        'form_class': 'fluentcms_contactform.forms.recaptcha.ReCaptchaContactForm',
        'required_apps': ('captcha',),

You can provide any form class, as long as it inherits from fluentcms_contactform.forms.AbstractContactForm. The current implementation expects the form to be a model form, so any submitted data is safely stored in the database too.

By providing a helper function, the form fields received default styling from django-crispy-forms. See the provided form code in fluentcms_contactform.forms for examples.

The form is rendered with the fluentcms_contactform/forms/*name*.html template.

Displaying phone numbers

The phone number field uses django-phonenumber-field to validate the phone number. By default, it requires an international notation starting with +. The PhoneNumberField can support national phone numbers too, which is useful when most visitors come from a single country. Update the PHONENUMBER_DEFAULT_REGION setting to reflect this.

For example, to auto insert a +31 prefix for Dutch phone numbers, use:

PHONENUMBER_DEFAULT_REGION = 'NL'   # Your country code, eg. .NL to

The phone numbers can be displayed in various formats, the most human readable is:


The supported formats are:

  • NATIONAL - nicely space separated, remove the country prefix.
  • INTERNATIONAL - nicely space separated
  • E164 - all numbers, suitable for data transmission.
  • RFC3966 - the tel: URL, suitable for URL display.

Displaying captcha's

The fluentcms_contactform.forms.captcha provides an example to create a captcha form. This requires a properly installed django-simple-captcha form:

pip install django-simple-captcha




urlpatterns = [
    # ...

    url(r'^api/captcha/', include('captcha.urls')),


Add the database tables:

python migrate

And optional settings to simplify the captcha:


This can be made more complicated when needed:

CAPTCHA_CHALLENGE_FUNCT = 'captcha.helpers.math_challenge'

See the documentation of django-simple-captcha for more examples.


In a similar way, you can use recapcha. Select the form option, and make sure everything is installed:

pip install django-recaptcha



NOCAPTCHA = True  # Use the new nocapcha

See the documentation of django-recaptcha for more details.


Don't install both django-simple-captcha and django-recaptcha as they both install a captcha package in the same location.

Frontend Configuration

If needed, the HTML code can be overwritten by redefining fluentcms_contactform/forms/*.html.

The template filename corresponds with the form style defined in FLUENTCMS_CONTACTFORM_STYLES. When no custom template is defined, fluentcms_contactform/forms/default.html will be used.

The staff email message can be updated by redefining fluentcms_contactform/staff_email/*.txt, which works similar to the form templates.


If you like this module, forked it, or would like to improve it, please let us know! Pull requests are welcome too. :-)