Package: collective.megaphone
IntroductionMegaphone makes it easy to build powerful online advocacy campaigns in Plone.Letters to decision makersCollect arbitrary fieldsRequired and optional recipientsSave data locallySave data to Salesforce.com (requires salesforcepfgadapter)E-mail template-based letters to targetsCustomizable thank-you letter to senderPetitionsCollect arbitrary fieldsSave data locallySave data to Salesforce.com (requires salesforcepfgadapter)List signatures within your Plone siteCustomizable thank-you letter to senderLimitationsNo 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 addressHow it worksMegaphone builds on top of several fantastic Plone products to do its work
without reinventing the wheel.The heart of Megaphone isPloneFormGen, which provides the core
form-handling capabilities.Because Megaphone actions are a fairly complicated PloneFormGens with lots of
defaults, we’ve builtcollective.z3cform.wizardwhich 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 theSalesforce PFG Adapterand the
underlyingSalesforce Base Connector.InstallationMegaphone has been tested with Plone 3.3 and Plone 4.Adding to buildoutMegaphone 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.megaphoneFor Plone 3:[buildout]
extends = http://good-py.appspot.com/release/collective.megaphone/2.1?zope=2.10.x

[instance]
...
eggs =
    ...
    collective.megaphoneOf 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 MegaphoneAfter 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 settingsThere 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 exportIn order to create a letter that saves contact information to Salesforce, you
must install the Products.salesforcepfgadapter and
Products.salesforcebaseconnector eggs.CAPTCHA supportIn 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 lookupAn 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 commercialCicero API.UpgradingIf 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 trackerPlease report issues athttp://plone.org/products/megaphone/issuesCustomizing MegaphoneThere are a number of ways that developers can extend Megaphone’s functionality.PloneFormGen-based customizationsSince 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 sourcesMegaphone 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 implementingcollective.megaphone.interfaces.IRecipientSourceA multi-adapter ofcollective.megaphone.interfaces.IMegaphoneandzope.publisher.interfaces.browser.IBrowserRequesttocollective.megaphone.interfaces.IRecipientSource, with the same name as the
utility.For an example of a custom recipient source, seecollective.megaphonecicerolookup,
which looks up the user’s legislator based on the address entered.Variable providersMegaphone 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 ofcollective.megaphone.interfaces.IMegaphoneandzope.publisher.interfaces.browser.IBrowserRequesttocollective.megaphone.interfaces.IVariableProvider. The name of the adapter
registration is the variable name, and the adapter should return the variable
value when called.CreditsMegaphone 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 HinkChangelog2.1.5 (2011-10-25)Updated Spanish translation (thanks to Manuel Gualda Caballero).
[davisagli]Add some missing message ids.
[davisagli]Fix bug where translated strings in the defaults control panel could not
be saved.
[davisagli]Fix display of non-ASCII characters in the signers portlet.
[davisagli]2.1.4 (2011-10-20)Make sure some field properties are stored encoded.
[davisagli]Fix editing of label fields.
[davisagli]Fix bug preventing saving form fields in the defaults control panel.
[davisagli]2.1.3 (2011-10-19)Add Spanish translation (thanks to Acento Web).
[davisagli]Add locales folder for translations and make some more strings
translatable.
[davisagli]Make sure field titles are decoded when loading existing form settings.
This fixeshttp://plone.org/products/megaphone/issues/30.
[davisagli]Use Salesforce’s “other” address fields for Contacts by default.
[yomatters]Added a description field to the general wizard step.
[yomatters]Added the ability to configure a Salesforce Contact adapter using
the wizard.
[yomatters]Updated popup form so that it closes correctly with
plone.app.jquerytools 1.2b4.
[yomatters]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.