collective.megaphone 2.1.2

Run an online advocacy campaign from your Plone site.

Introduction

Megaphone makes it easy to build powerful online advocacy campaigns in Plone.

Letters to decision makers

• Collect arbitrary fields

• Required and optional recipients

• Save data locally

• Save data to Salesforce.com (requires salesforcepfgadapter)

• E-mail template-based letters to targets

• Customizable thank-you letter to sender

Petitions

• Collect arbitrary fields

• Save data locally

• Save data to Salesforce.com (requires salesforcepfgadapter)

• List signatures within your Plone site

• Customizable thank-you letter to sender

Limitations

No product is perfect. There are some important things Megaphone doesn’t do (yet), including:

• Delivery to targets who don’t have a publicly-accessible email address

How it works

Megaphone builds on top of several fantastic Plone products to do its work without reinventing the wheel.

• The heart of Megaphone is PloneFormGen, which provides the core form-handling capabilities.

• Because Megaphone actions are a fairly complicated PloneFormGens with lots of defaults, we’ve built collective.z3cform.wizard which lets us make a very user-friendly wizard for building out the advocacy letter. The wizard can be run and then re-run to let a user change the settings. More advanced users can directly edit the PloneFormGen fields and objects to create more complex setups.

• Salesforce integration is via the Salesforce PFG Adapter and the underlying Salesforce Base Connector.

Installation

Megaphone has been tested with Plone 3.3 and Plone 4.

Adding to buildout

Megaphone has several dependencies. These should get pulled in automatically if you add the collective.megaphone egg to your buildout. _However_, you need to make sure that you get versions of the dependencies that are compatible with your version of Plone. To do so, you may extend the following known good sets of version pins:

For Plone 4:

[buildout]
extends = http://good-py.appspot.com/release/collective.megaphone/2.1?plone=4.0.4

[instance]
...
eggs =
    ...
    collective.megaphone

For Plone 3:

[buildout]
extends = http://good-py.appspot.com/release/collective.megaphone/2.1?zope=2.10.x

[instance]
...
eggs =
    ...
    collective.megaphone

Of course, you may need to adjust the specified Plone version, or create a derivative set of version pins if the ones in this set conflict with those recommended for some other add-on.

Activating Megaphone

After running buildout and starting your Zope instance, install collective.megaphone via the Add/Remove Products configlet in Plone Site Setup.

Now you should be able to add a ‘Megaphone Action’ via the add item menu. The wizard will walk you through the rest of the steps.

Make sure that you configure your Plone site’s e-mail settings before trying to send a letter.

Configuring default settings

There is a control panel in Plone Site Setup called “Megaphone Defaults”. This can be used to configure default settings that should be used for all new Megaphones. For example, this can be used to replace the default US-centric “State” field with a list of provinces from another country.

Salesforce export

In order to create a letter that saves contact information to Salesforce, you must install the Products.salesforcepfgadapter and Products.salesforcebaseconnector eggs.

CAPTCHA support

In order to include CAPTCHA fields, you must also install the collective.captcha or collective.recaptcha egg, and load its ZCML.

If using collective.recaptcha, you must also configure your recaptcha keys via the /@@recaptcha-settings view.

Legislator lookup

An optional add-on, collective.megaphonecicerolookup, makes it possible to determine the Megaphone recipient by automatically looking up a legislator’s e-mail address based on the sender’s mailing address, using Azavea’s commercial Cicero API.

Upgrading

If you have a previous version of Megaphone already installed, update your buildout as described above. (Make sure you have a backup first!)

Then start your Zope instance, go to the Add/Remove Products configlet in Plone Site Setup, and find the button to upgrade Megaphone.

Megaphone will also automatically update its dependencies plone.app.jquerytools and plone.app.z3cform to compatible versions.

Bug tracker

Please report issues at http://plone.org/products/megaphone/issues

Customizing Megaphone

There are a number of ways that developers can extend Megaphone’s functionality.

PloneFormGen-based customizations

Since Megaphone is an extension built on top of PloneFormGen, standard techniques for extending PloneFormGen can be used. In particular, custom fields and action adapters (actions executed when the form is submitted) can be implemented.

Recipient sources

Megaphone includes one built-in recipient source, which lets a manager enter a name and e-mail address of a recipient. Additional recipient sources can be implemented to determine the recipient in other ways.

To create a custom recipient source, you must register two components:

• A named utility implementing collective.megaphone.interfaces.IRecipientSource

• A multi-adapter of collective.megaphone.interfaces.IMegaphone and zope.publisher.interfaces.browser.IBrowserRequest to collective.megaphone.interfaces.IRecipientSource, with the same name as the utility.

For an example of a custom recipient source, see collective.megaphonecicerolookup, which looks up the user’s legislator based on the address entered.

Variable providers

Megaphone allows the manager to configure various templates that can make use of variable substitution. By default, variables are provided based on the recipient information and on the form data entered by a user taking action. It’s possible to provide additional variables as well.

To add a new variable provider, register a named adapter of collective.megaphone.interfaces.IMegaphone and zope.publisher.interfaces.browser.IBrowserRequest to collective.megaphone.interfaces.IVariableProvider. The name of the adapter registration is the variable name, and the adapter should return the variable value when called.

Credits

Megaphone was originally developed by Groundwire (formerly ONE/Northwest) as part of the Civic Engagement Platform funded by Meyer Memorial Trust and Surdna Foundation.

Conceptual work by Jon Stahl, Drew Bernard, et al.

Development by David Glick and Jon Baldivieso.

Thanks also to:

• Kees Hink

Changelog

2.1.2 (2011-04-21)

• Added ‘Lead Source’ setting to the Salesforce.com wizard step. [davisagli]

2.1.1 (2011-04-08)

• Fix issue with editing string fields on the new defaults control panel. [davisagli]

2.1 (2011-03-24)

• Added ‘Campaign Status’ setting to the Salesforce.com wizard step. [davisagli]

2.1b3 (2011-03-22)

• Added a control panel in Site Setup to configure default values that will be used for new Megaphones. [davisagli]

• Fix javascript error affecting IE. [davisagli]

• Added render_recipients_list helper to the letter renderer. [davisagli]

• Revamped the UI of the fields wizard step. Field settings are now configured in an overlay. [davisagli]

2.1b2 (2010-11-16)

• Added a way to provide additional template variables by implementing an IVariableProvider adapter. [davisagli]

2.1b1 (2010-10-14)

• Raise AT ObjectInitializedEvent and ObjectEditedEvent when the wizard is finished. [davisagli]

• Updated the test setup to use a layer so that it can be extended by Megaphone plugins more easily. [davisagli]

• Added an upgrade step to remove the old “optional-recipients” field which is no longer needed. [davisagli]

• Revamped the UI of the recipients wizard step. Recipient settings are now configured in an overlay. [davisagli]

• Introduced the concept of pluggable “recipient sources”. Each recipient source has its own settings, can provide content for the Megaphone form, and is queried for recipients when the form is submitted. The old recipient functionality (with “required” and “optional” recipients) has been refactored into the “standard” recipient source. [davisagli]

2.0 (2010-10-14)

• Render the signatures portlet when sig_portlet_min_count is not set. [khink]

• Removed reference to “letter” from the default thank you message so that it makes sense for a petition too. [davisagli]

• Moved helper functions into the utils module. [davisagli]

• Only show “latest signatures” text in portlet if there are signatures to show. [jbaldivieso]

• Refer to “offline signature count” instead of “goose factor”. [jbaldivieso]

• Fix upgrade step for Plone 3 -> Plone 4 to only run for sites that have Megaphone installed. [jbaldivieso]

2.0b1 (2010-08-19)

• Move the main e-mail switch to the recipients wizard step, and rename the delivery step to salesforce since that’s all it covers now. Make it only show up if Salesforce support is installed. [davisagli]

• Added a permission to control who can view signatures. [davisagli]

• Don’t display the Intro page of the wizard when returning to edit an existing Megaphone Action. [davisagli]

• Updated to new collective.z3cform.wizard with various fixes. [davisagli]

• In Plone 3, use the overlay styles from plone.app.jquerytools>=1.1.1, rather than supplying our own. [davisagli]

• Including a savedata adapter is no longer optional. [davisagli]

• Removed the old signers count portlet and replaced it with the new one which lists recent signers. [davisagli]

• Added wizard step for configuring display of signers in a portlet. [davisagli]

• Added petitions as a new type of action. Different options are available depending on whether you select letter or petition on the first page of the Megaphone Action wizard. Petitions also get a modified set of default form fields. [davisagli]

• Renamed the “Action Letter” type to “Megaphone Action”. An upgrade step must be run to update existing sites. [davisagli]

• Refactored test setup. [davisagli]

• Removed duplicate version number in version.txt [davisagli]

1.4 (2010-06-30)

• Fix table styling in Plone 4 Sunburst theme. [davisagli]

• Reimplement field reordering using HTML5 drag-and-drop to avoid Jquery UI dependency. [davisagli]

1.3 (2010-05-21)

• Add ‘Send’ button to send the letter immediately without Preview. [davisagli]

• Fix issue with preview popup fallback for when Javascript is disabled. [davisagli]

1.2 (2010-03-02)

• Fix issue where sender for the thank you e-mail was not properly loaded when editing the form after initial creation. [davisagli]

• Added option to disable thank you e-mail to activist. [davisagli]

• Fix wizard step listing styles for Plone 4. [davisagli]

• Make sure that the Next button takes precedence when submitting a wizard step by pressing enter, rather than Previous. [davisagli]

• Make sure the list of template variables can’t obscure the Prev/Next buttons. [davisagli]

• Increase the height of the default field for text fields in the form field wizard step. [davisagli]

• Fix regression from 1.1, wherein text fields would get transformed to HTML and then erroneously escaped. [davisagli]

1.1 (2010-02-18)

• Make sure collective.jqueryui’s ZCML is loaded. [davisagli]

• Added custom import handler to set the add_view_expr on the Action Letter FTI in Plone 4. Also an update step to add this when upgrading from Plone 3 to Plone 4. [davisagli]

• Workaround for change in the utranslate function in Plone 4 (or possibly just me misusing it before). [davisagli]

• Workaround for Zope interface changes in the Plone 4-compatible version of PloneFormGen. [davisagli]

• When creating Leads in Salesforce, default to setting the Lead Source to ‘Web’. (Requires salesforcepfgadpater >= 1.6b2). [davisagli]

• Use the htmlValue method of form fields to process the values in the request before rendering a letter. This makes it possible to set the values that will be displayed for a boolean field, for example. [davisagli]

1.0 (2009-11-11)

• No longer artificially restrict to z3c.form <2.0, as that is a deployment decision. Plone 3 users may need to pin z3c.form to version 1.9.0 or add additional fake eggs to avoid pulling in new zope.* packages. [davisagli]

• Only depend on plone.app.jquerytools, not Products.pipbox. [davisagli]

• Fixed issue with loading thank you page text when revisiting the wizard. [davisagli]

1.0rc1 (2009-8-26)

• Added options for configuring the thank you page message or an alternative thank you page URL. [davisagli]

• Fixed portlet link to view saved letters. [davisagli]

• Decode request variables before using them in dollarString substitutions, to avoid UnicodeDecodeErrors when casting the strings for interpolation. [davisagli]

• Decode UTF-8 values from Archetypes before passing them to z3c.form, to avoid UnicodeDecodeErrors when the system default encoding is ASCII. [davisagli]

• Check the persistent template setting in the formgen_tool when determining whether to update the mailer templates, rather than the default default from PFG’s config.py [davisagli]

• Fixed issue with marshalling field size. [davisagli]

• Fixed action adapter processing on the final send step when a CAPTCHA field is in use. [davisagli]

1.0a1 (2009-06-25)

• Initial release.