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 behaviour 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 partcipation. 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 adminstration links to forms" option. As user 1, or another user enabled both to avoid captchas amd 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.