ContactForm v0.2.0 documentation

Manual¶

ContactForm is a simple contact form with reCapcha support implemented as an extension for a Flows application. You should read the Flows documentation on extensions before reading this documentation (not written yet).

Tutorial¶

Let’s assume we want to use this as the contact extension.

Install:

wget pylonsbook.com/virtualenv.py
python2.5 virtualenv.py ~/env
~/env/bin/easy_install ContactForm

Example Config:

contact.to[0].name = James Gardner
contact.to[0].email = james@example.com
contact.to[1].name = Web Master
contact.to[1].email = james@example.com
contact.public_key = 6LcQcAk8huyamajPZgxIZOmAaSjgIVMED9oeihQbn5
contact.private_key = 6LcQcAjahvananuADRmWqxqwPw5LuGDjs0mjFwruBHn
contact.template = main.dwt
contact.subject = JimmyG Website Message!

This service also relies on the mail service being present and correctly configured. You’ll need to get your own public and private keys by signing up at http://recaptcha.net.

Example extension in ext/contact/dispatch.py:

import contactform

on_load_component = contactform.make_component('contact')

The template you specify should be a dreamweaver template relative to a Flows application static/Templates directory or it should be an absolute path. It should contain the following editable regions:

doctitle

The page title in the <head> section. The <title> and </title> tags should be part of the region.

head

An empty editable region in the <head> section which will be used to add CSS, JS and any required HTML tags.

heading

The page heading text

content

A region which will contain the form and any messages.

That’s it!

Advanced Configuration¶

If you want to get very advanced you can override the following events:

on_generate_form_html(flow): A function which takes flow.ext.form as its only argument and generates an HTML form.
on_generate_head_html(flow): A function which generates the correct HTML you’ll need in the <head> section of your HTML document
on_new_form(flow): Return a new page containg an empty form ready for the user to enter some data. Use the on_generate_form_html(flow) handler which will use the flow.ext.form object.
on_validation_error(flow): Return the HTML for a form containing all the original data and error messages but with a new captcha. Use the on_generate_form_html(flow) handler which will use the flow.ext.form object’s errors.
on_valid_data(flow): Handle the sending of an email and return the HTML to display a confirmation message. Use the flow.ext.result object. You will also find the flow.config.ext.subject config option useful.

The following objects are available in some of the events:

flow.ext.form

A FormBuild form, set up with all the values, options and errors you need to start building with it. The form object itself has some useful attributes:

flow.ext.form.value: The field values as a dictionary where the keys are the field names
flow.ext.form.error: A dictionary containing the errors associated with the each of the invalid fields. The keys are the field names.
flow.ext.form.option: The IDs and labels of any fields which take options (namely the to field).

flow.ext.on_generate_form_html

The on_generate_form_html() event handler, whether the ContactForm default or a custom override.

flow.ext.on_generate_head_html

The on_generate_head_html() event handler, whether the ContactForm default or a custom override.

flow.ext.result

A dictionary containig the following values from the successfully submitted form:

to_name: The name of the person to receive the message
to_email: The email address the form should be submitted to
from_name: The name of the person sending the message
from_email: The email address of the person sending the message
message: The message itself