Updated for version 0.82 6th Nov 2011
[ecampaign targetEmail='john.smith@hightown.gov' subject="Planning application P1234, wind turbines on Windy Hill"]
I am writing in support of the planning application P1234 to construct a cluster of
wind turbines on Windy Hill.
I think that wind turbines are quite visually attractive.
If we want to continue to use the same amount of energy we
must seriously address our carbon emissions.
We need to break our addiction to fossil fuels by making use
of the renewable energy sources available to us.
On shore wind turbines have short carbon payback periods and these turbines will provide us
with an unlimited source of fossil free energy for many years.
[/ecampaign]
The second form does not appear until the first email is sent.
You can configure testMode or override the campaignEmail address on this particular action, see 'Configuring the ecampaign plugin attributes' below.
This dual form mode is the only mode supported by earlier versions (< 0.80) of the plugin. If you want to site visitors to share with friends (by email) as well, add a <hr> tag (horizontal rule) and add the text of email to friends. Not that the subject lines of the two emails must be set using targetSubject and friendSubject.
[ecampaign targetEmail='john.smith@hightown.gov' targetSubject="Planning application P1234, wind turbines on Windy Hill" friendSubject="Please support the wind turbines on Windy Hill!"]
[Please customise this message and delete this text]
I am writing in support of the planning application P1234 to construct a cluster of
wind turbines on Windy Hill.
I think that wind turbines are quite visually attractive.
If we want to continue to use the same amount of energy we
must seriously address our carbon emissions.
We need to break our addiction to fossil fuels by making use
of the renewable energy sources available to us.
On shore wind turbines have short carbon payback periods and these turbines will provide us
with an unlimited source of fossil free energy for many years.
I have just sent an email an email to the council urging them to approve the planning application
for a wind farm on Windy Hill. I hope you will as well.
[/ecampaign]
The forms above will be constructed using the Target form template and the Friend form template on the settings page. You can add/remove/change the position of all the fields and the supporting text by editing that template and saving the new settings. If nothing else, the postal address fields should be adjusted to match the country!
The petition body is enclosed by the [ecampaign class=EcampaignPetition][/ecampaign] tags. Here is an example.
[ecampaign class='EcampaignPetition']
We call on Middletown Council to extend the 20 mph limit from residential
roads to include all the main roads in Middletown, where many people live,
shop, work and go school.
20mph limits would deliver a healthier, safer and less polluted street
environment for all local residents.
[/ecampaign]
The petition functionality is limited but will be improved in next release. The signatures added to the petition are shown in the ecampaign log. The ecampaign view shows the date, name and address of the signatories.
If you need more flexibility and want to use different forms for each campaign action, you can layout and define all the fields in the form inside the [ecampaign][/ecampaign] brackets. The easiest way to do this is to cut and paste a working template from the ecampaign settings page and just edit it until it looks the way you want. In the example below, testMode has been configured to suppress email delivery temporarily.
[ecampaign class=EcampaignTarget testMode='suppressed']
{to* john.smith@hightown.gov, andy.brown@gov.uk}
{subject* Planning application P1234, wind turbines on Windy Hill}
{body
I am writing in support of the planning application P1234 to construct a cluster of
wind turbines on Windy Hill.
I think that wind turbines are quite visually attractive.
If we want to continue to use the same amount of energy we
must seriously address our carbon emissions.
We need to break our addiction to fossil fuels by making use
of the renewable energy sources available to us.
On shore wind turbines have short carbon payback periods and these turbines will provide us
with an unlimited source of fossil free energy for many years.
}
<div class='text-guidance'>Your name and address as entered below will be added.
You do not need to add your name above.</div>
{visitorName*}
{visitorEmail*}
{address1}
{ukpostcode}
{send}
{checkbox1 checked="checked" Check if you want to receive alerts about related campaigns.}
<div class='text-contact'>{counter} people have taken part in this action. Please
contact {campaignEmail} if you have any difficulties or queries.</div>
{success <div class="ecOk bolder">Your email has been sent.</div>
<class="ecOk">You should receive a copy in your mailbox. Thank you for taking
part in this action.</div>}
[/ecampaign]
The body of the email is enclosed by the [ecampaign class=EcampaignFriend][/ecampaign] tags.
[ecampaign class=EcampaignFriend subject="Please support the wind turbines on Windy Hill!"]
I have just sent an email an email to the council urging them to approve the planning application
for a wind farm on Windy Hill. I hope you will as well. Here is the link:
[/ecampaign]
The link for the campaign is appended to the body of the email automatically.
You can explicitly define the fields on the form if you wish. Note that the site visitor's name and email fields are expected to be present somewhere on the post but not necessarily in this form.
Attributes can be added to the ecampaign tag. Phrases e.g. the email subject have to be wrapped in single quotes or double quotes. All the attributes must be on the same line; this appears to be a wordpress limitation.
[ecampaign name1=value1 name2=value2 name3=value3]
...
[/ecampaign]
| name | value and description |
| testMode |
normal emails sent to target address(es)
diverted emails diverted to campaign mailbox suppressed emails not set sent at all Setting this value overrides the site wide test mode setting. Use this (or the site wide setting) when setting up and testing a new campaign action. It prevents the emails being sent to to the target address prematurely. |
| targetEmail | Multiple addresses should be separated by commas. |
| campaignEmail | Override the site wide setting. Blind copies of emails are sent to this address |
| subject | subject line of email sent to target |
| targetSubject | subject line of email sent to target. |
| friendSubject | subject line of email sent to friend. |
| hidden | set hidden=true to hide form. Use this to hide this form e.g. 'email to friends' until email first sent to target. |
| class | specify (the path and) class that should provide the functionality. The default is EcampaignTarget which supports the 'send to target' functionality. For example use class='EcampaignFriend' when declaring a 'send to friend' form. Using class='uk/MP' will extend the ecampaign 'send to target' functionality to lookup an MPs email address from a uk postcode. |
All the fields must be declared inside [ecampaign][/ecampaign] brackets on the wordpress post. If no fields are declared, then the form will be constructed using the definitions specified in the site wide templates in the ecampaign settings page.
| Field name | How field is used |
| {to xx.yy@zzz.com} | A non editable field that holds the target email address(es). |
| {subject} | The editable subject of the outgoing email. |
| {body} | The editable body of the outgoing email. This field is rendered as an HTML textarea. Note that all other text fields are rendered using an HTML input field. Enclose any text in [..] if you want to force the site visitor to edit/remove it before the email can be sent. It might be desirable to set rows and columns depending on the wordpress theme being used, see setting field attributes below. |
| {name} {email} | Site visitors name and email address are used to create the 'from' address on all emails |
| {address1} {address2} {address3} {city} {postcode} {ukpostcode} {state} {zipcode} {country} | Postal address fields. Postal address fields are blocked together to create the postal address appended to the email sent to the target email address. Postal fields are also displayed in the in the petition view of the ecampaign log accessed through the admin pages. Blank/missing fields are ignored. Zipcode and ukpostcode are validated by javascript in the browser. The postcode field is not validated. |
| {captcha} | Adds the wordpress securimage captcha mechanism in the form |
| {verificationCode} | This field does not appear until the {sign} or {send} button is clicked at which time an email is sent to the site visitor's email address containing a 4 digit verification code. It should not be necessary to deploy both captcha and verificationCode on the same site but they will happily coexist. |
| {checkbox1} {checkbox2} | Adds checkboxes and to a form e.g. {checkbox1 Check if you want to stay in touch} This data is collected in the ecampaign log (available through the wp-admin pages) and included in emails sent to campaignEmail. |
| {sign} | Adds a button to the form which when clicked adds vistor's name and address to ecampaign log. Required in the form somewhere to add a name/address to a petition. (Used by the EcampaignPetition class) |
| {send} | Adds a button to the form which when clicked sends email to target. Required in the form somewhere in the to send an email to the target address. This action is logged. (Used by the EcampaignTarget class) |
| {campaignEmail} | This is just a string placeholder. The form text is replaced by the actual campaign email address. It is obfuscated by SPAN tags to make it less likely for spammers to find it in a web page. |
| {counter} | This is just a string placeholder. The form text is replaced by the number of people that have taken actions on this page/post. |
| {success} | This is just a string placeholder for the message sent to the site visitor after s/he has completed the campaign action. It can include HTML tags. It's position is irrelevant. |
| {friendEmail} | Adds one empty field. Additional fields/recipients can be added added and removed by the user. (Used by the EcampaignFriend class). |
| {friendSend} | Adds a button to the form which when clicked sends email to recipients specified in {friendEmail}. (Used by the EcampaignFriend class). |
| {lookup} | Adds a button to the form which when clicked looks up an email address using a ukpostcode. Used by some classes that extend EcampaignTarget which provides the basic 'send to target' functionality. |
To make a field mandatory, append an asterisk to the name of the field e.g. {name*}. Enforcement is done by the javascript in the browser.
Attributes can be added to any field. These attributes are conferred to the INPUT, TEXTAREA or DIV element that is being used to create the field. Examples are shown below:
{body rows=10 cols=70} adjust size of the textarea holding the body field.
{city size=20} adjust the length attribute of input element holding the city field.
{subject readonly='readonly'} prevents the site visitor from changing the subject line of the email.
{checkbox1 checked='checked'} pre checks a check box.
{name min=6} 'min' is not an official HTML attribute. It sets minimum number of characters of any field. 'min' is currently enforced at the server. Note that if a field is declared mandatory it only has to meet the 'min' requirement if it is one or more characters long. (Although 'min' is not a legal HTML attribute, most browsers accept additional attributes).
Attribute values can be single or double quoted. However some wordpress themes convert straight quotes to curly quotes and this conversion has to be disabled..
Ecampaign can directly add site visitors to PHPList if they opt-in using a checkbox on the form. Successful subscriptions are logged as well as any error and exceptions that occur. Errors and exceptions are not reported back to the user because any failed subscriptions can be subsequently be added manually to PHPList. Note that if a revisiting site visitor unchecks the box, the visitor is not unsubscribed from that list.)
The configuration string is fiddly. At present it consists of:
checkbox1='PHPList No' checkbox1='PHPList No' configFile='Full server path to PHPList configuration file'
The config file is the standard PHPList config.php file that contains the database username and password etc. It need not be the real file, it could be be just a copy kept locally. The 'PHPList No' is shown in the left hand column of the phplist/public_html/lists/admin/?page=list page. The first list is numbered 1. It is not possible to map checkboxes from specific actions specific pages to specific email lists.
An example configuration is shown below:
checkbox1=6 configFile=/home/web/phplist/public_html/lists/config/config.php
In the above example, site visitors who check checkbox1 will be subscribed to PHPList No 6.
The interface to PHPList is provided by the EcampaignPHPList class. PHPlist does not have an API that would allow emails addresses to be easily added. Therefore the ecampaign adds the new subscribers directly to the database. This has been tested against PHPList 2.10.17. However PHPList database schema changes may require changes to EcampapignPHPList.
Subscribing to other email lists could be supported using a different class.
Several classes under the 'uk' directory support the lookup of email addresses of UK elected representatives. To use these classes, specify the path and class of the appropriate PHP file as an ecampaign attribute (see above). These files can be removed if you are not using this functionality.
| uk/MP | to look up MP for a particular UK postcode Makes use of http://findyourmp.parliament.uk/api |
| uk/MSP | to look up MSP for a particular Scottish postcode Makes use of the UK based TheyWorkForYou API. You have to apply for an API key and enter it next to the 'API key' on the settings page. |
| uk/Councillor | to look up councillor for a particular UK postcode. You can restrict the campaign to a particular council by adding the attribute onlyIn=name-of-council to the ecampaign opening tag. Makes use of the UK government service http://openlylocal.com. However not all councils register their councillors email addresses with this site. |
The only other requirement is to add a {lookup} field to the form, possibly but not necessarily next to the {ukpostcode} field. Here is an example template to lookup up an M.P.:
[ecampaign class='uk/MP']
{name*}
{email*}
{address1* }
{city}
{ukpostcode*} {lookup}
{to* lookup@my.MP}
{subject* Please sign Early Date Motion 1234}
{body
Dear MP
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
}
<div class='text-guidance'>Your name and address as entered above will be added.
You do not need to add your name above.</div>
{send}
{checkbox1 checked=checked Keep me in touch with this campaign}
<div class='text-contact'>{counter} people have taken part in this action. Please
contact {campaignEmail} if you have any difficulties or queries.</div>
{success <div class="ecOk bolder">Your email has been sent.</div>
<class="ecOk">You should receive a copy in your mailbox. Thank you for taking
part in this action.</div>}
[/ecampaign]
The contents of the 'to' field is unimportant. It will be filled with the MP's email address. The MP's constituency will appear next to the lookup button. It should be easy to create a class to lookup politicians in other countries by cloning and renaming one of these classes.
Anyone with the role of Author or greater (i.e. able to publish posts) can create a new campaign action by creating a new post and embedding a campaign action between [ecampaign] [/ecampaign] tags.
Mail is sent directly via the PHPMailer class because it provides access to error messages which aren't available through the wordpress API via wp_mail.