OK, so the Connect module has actually been around for a while now, but the first version was painfully difficult to use, and the second version has only just seen an official, albeit beta, release.

Connect arose because we wanted to create a flexible and extensible online campaign platform for Drupal. The goal was to produce a framework that would allow different features to be added as necessary. Thus, a single tool could be used to create a simple petition or a sophisticated online email- or fax-sending campaign.

Furthermore, we wanted campaigns to be highly customizable. Connect ships with functions that allow you to automatically record people in your CiviCRM database, offer participants the opportunity to rewrite or append to the campaign-provided text, display a list of participants, enforce unique participation, and more.

The internal structure of Connect is highly modular, like Drupal itself. Thus, new features can be quickly and easily added by developers as desired. The code is *ahem* fairly thoroughly documented, and should offer straightforward models that can be copied and modified with relative ease.

Despite its slow progress in terms of releases, Connect will continue to see active development, and will hopefully be ported to Drupal 6 in the not-too-distant future.

Check out the drupal.org project page here.

What follows is the help text provided with the connect module, and details the nuts and bolts of how it is used:

The connect module 'connects' child nodes to parent nodes. The parent nodes could be petitions, online email or fax actions, or even event registrations. We refer to them generically as the 'parent' or 'campaign' nodes. The child (or 'participant') nodes represent the petition signers, action participants, etc.

This module lets you assign a variety of functions to a parent node (such as sending an email or a fax, adding participants to CiviCRM, allowing participants to customize the fax or email, displaying a progress meter, etc.). When the parent node is displayed, connect creates a form that allows users to enter the required information to create a new participant record. When the form is submitted, all the actions are launched, the participant is recorded as having participated in the action, and the participant information is saved.

To create a campaign

• declare what node types can be managed by connect from Site configuration > Connect module settings (see the "Node types" discussion below)
• create a new campaign node of the proper type, and fill out the fields as desired
• from the "settings" tab, choose the basic campaign settings
• from the "functions" tab, select the functions you want to add to the campaign
• return to the "settings" tab to configure the new functions (note that choosing some settings will cause additional settings to appear, so make sure all the required elements are filled out before using your new campaign)
• set up a CAPTCHA challenge for the connect forms (see the "CAPTCHA" section below)
• displaying the campaign node will now also display the participant form; filling out that form will trigger the associated functions

Node Types

Before using connect, you need to set up at least one parent and one child node type. Any node types that you set up as child/participant or parent/campaign nodes will be subject to processing by the connect module, so create node types specifically for use with this module.

The parent node types can contain any fields you want to display, but when you set up your connect functions, additional fields may become necessary. (For example, fax and email campaign functions save the success or failure of the fax/email in the child node, so there has to be a field available to hold that information.) The "required fields in parent/campaign node" and "required fields in child/participant node" sections of the settings form identify what fields are necessary in each node type for the functions you have selected.

To prevent any 'administrative' fields in the child node from being displayed on the connect participation form, set the teaser display to 'hidden' when you add the field.

Campaign functions

Connect comes with the following functions.

CiviCRM: add participants

If you use CiviCRM, this functions allows you to automatically insert campaign participants into your CiviCRM records. By default, it creates a group named after the parent campaign and adds new participants to CiviCRM as members of that group.

Content: append

This function is only relevant in cases where something is being done with the content by another function. It allows participants to add their own comments, etc. to the content provided by the parent node. In practice, this means that the content from the child field is appended to the content from the parent field before any further action (email or fax, for instance) is taken.

Content: rewrite

Allows participants to revise the content provided by the parent node. In this case, a designated field in the parent node is copied to the child node, where it can be edited as part of the form submission. The resulting text is used in the place of the parent version for any further actions (such as emailing or faxing) and is saved in the participant node.

Display participants

Adds a "display participants" link above the form, which presents a tabular list of participants who have indicated they are willing to be so listed.

Display progress bar

Adds a CSS-based display showing how many of the target number have participated.

Double opt-in

This function sends a configurable email to the participant that includes a URL to confirm their participation. This has only been partially implemented. It records their successful double opt-in in a field in the participant node, which is available for use by other functions (only the "display participants" function currently uses it). Plans for this function include making the entire action dependent on the double opt-in, so that no functions will fire until it is approved.

MyFax (defined target)

Sends fax (using the myfax.com service) to a specified name and fax no.

MyFax (target lookup)

Sends fax (using the myfax.com service) to a target determined by the participant's information.

Redirect on submit

Adds the ability to redirect to a specified URL or node when the participation form has been submitted successfully. This overrides the default behavior of returning to the parent node.

Send Email

Allows the campaign to send email. A list of To/CC/BCC addresses can be provided, and one target can be determined on the basis of information provided by the participant (such as an elected representative selected on the basis of postal code).If you experience delivery failures (as indicated by "Failed" in the email result field in the participant nodes), you can attempt to re-send the failed emails using the "Re-send emails" tab. Only failed emails will be re-sent.

One vote per person

Prevent the same person from participating more than once. NOTE: the connect module does not by default enforce single participation. Enable this feature to do so.

Configuration examples

Petition

A petition allows participants to add their names and other identifying information to the list of participants. Thus, the node types for a petition might look like this.

campaign_petition

• title
• body
• petition text

participant_petitioner

• title
• name
• city
• province/state
• postal code

That represents the most basic functionality provided by the connect module — associating many participants with a single campaign. Additional functions allow it to do may more things, but new functionality requires more node fields to hold additional information.

Email campaign

For instance, if you want participation to trigger an email message that is sent to a defined target, you would enable the "Email (defined target)" function and create node types like so:

campaign_email

• title
• body
• email_subject
• email_body

participant_email

• title
• name
• city
• province/state
• postal code
• email address
• email result

(The email will appear to come from the participant's email address, and the 'email result' field is a text field that will hold a message regarding the success or failure of the attempt to send the email.)

Email campaign + custom message

And if you want to enable the participant to edit the content of the email that is sent, you would also turn on the "Content: rewrite" function and add another field to the participant_email nodetype:

participant_email

• title
• name
• city
• province/state
• postal code
• email address
• email result
• participant email body

When you add and configure the "Content: rewrite" function, the parent email_body will be available for the participant to revise, and the revised version of the text will be emailed to your target (and saved in the 'participant email body' field).

Sending HTML Email

Connect can send plain-text or HTML emails. Plain text is simple: make sure the email body field (which is usually in the parent node, but can be in the child node if you are using the "Content: replace" function) has its "Text processing" option set to "Plain text". This ensures that your email content will not contain any HTML tags when it is sent.

In order to send HTML mail, you must first install and configure the mimemail module. Connect uses this module to send HTML-formatted emails. Note that you do not need to make mimemail the default mail handler for your whole site if you just want to use it for connect. Next, make sure the "Text processing" option in the node type set to "Filtered text" and that the filter in the node itself is set to one of the HTML filters. This will preserve your HTML when it's mailed. To activate the HTML mail option using the "Send HTML email using the mimemail module?" option under the node's connect settings tab.

Captcha

The connect module by default requires that a captcha be assigned to its forms. To set this up, enable and configure the captcha module. Make sure you enable the "Add CAPTCHA administration links to forms" option. As user 1, or another user enabled both to avoid captchas and administer connect, view a connect campaign node. You will have the opportunity to add a captcha to the "connect_form" form ID. Once this is done, captcha will automatically handle adding the desired challenge and response to your connect module forms.

It is possible to turn this requirement off in the admin settings for connect, but it it strongly discouraged, especially if you are setting up an email or fax campaign that could be the target of spam or DoS attacks.