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`_. .. _`PloneFormGen`: http://plone.org/products/ploneformgen .. _`collective.z3cform.wizard`: http://plone.org/products/collective.z3cform.wizard .. _`Salesforce PFG Adapter`: http://plone.org/products/salesforcepfgadapter .. _`Salesforce Base Connector`: http://plone.org/products/salesforcebaseconnector 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`_. .. _`collective.megaphonecicerolookup`: http://plone.org/products/collective.megaphonecicerolookup .. _`Cicero API`: http://www.azavea.com/Products/Cicero/API.aspx 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