Updated for version 0.83 18th Dec 2011
[ecampaign to='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 form is constructed using the Target form template on the Ecampaign page under settings. Copies of the outgoing emails are sent to the campaign email address. You can override the campaign email address on one 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 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 second form does not appear until the first email is sent.
The forms above will be constructed using the Target form template and the Friend form template on the Ecampaign page under settings. 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. |
| to | Email address of target. Addresses of multiple recipients should be separated by commas. |
| targetEmail | Alias for 'to' field, kept for back compatability. |
| 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} There is nothing special about these checkboxes accept this data is collected in named columns in the ecampaign log (available through the wp-admin pages) and makes filtering very easy. |
| {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 actions that have been completed on this page. |
| {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 and probably ought to include HTML tags. The default class ecOK in conjuction with the default style sheet causes the success message to be printed in blue and bold to catch the site visitors eye. It's position in the form 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.
Custom fields can be added to a template. For example, to prompt for organisation:
{organisation}
{bike label='make of bicycle'}
Checkboxes are similar.
{foldable type='checkbox' My bike is foldable}
Not that these fields are not used but they are saved in the info field in ecampaign log. The fields can also be passed to another service or stored, see subscription.
Attributes can be added to any field. There are special attributes, type, label and data-min. Examples are
{listsignup type='checkbox' checked='checked' Add me to the email list} Render a checkbox. The default is text field.
{organisation label='My organisation'} change the label to be something other than the field name.
{name data-min=6} sets minimum number of characters of any field. 'data-min' is currently enforced at the server. Note that if a field is declared mandatory it only has to meet the 'data-min' requirement if it is one or more characters long. (Although 'data-min' is not a legal HTML attribute, most browsers accept additional attributes).
Any other 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.
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..
Subscription functionality is provided by the configurable site visitors subscription class. Site visitors should not normally be added to a list or table without the visitor opting using one of the checkboxes. The checkbox is specified in configuration string below the subscription class on the ecampaign settings page.
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.
Using the class EcampaignSubscribeUser, site visitors can be added as wordpress users if they opt-in using a checkbox on the form. The checkbox used to opt-in is defined in the configuration screen, for example to register site visitors who opt-in using checkbox2 use:
optin=checkbox2
Note that new wordpress users are given a 6 character random password which they can reset, and they can update and delete their account.
If site visitors are required to verify their email address, the code supplied in the verification email (inserted the token %code) will subsequently become their wordpress account password.
If site visitors do not have to verify their email address, and the site visitor is signing an email, the password of any freshly created wordpress account can be included in the the petition confirmation email (inserted using the token %password). If an account with the the same visitor name already exists, the %password will be blank.
Fields in the template that have the attribute save=usermeta are stored in the usermeta for the wordpress user. For example to add a prompt for group name and store in the field organisation:
{organisation save=usermeta label='Group name' size='60' data-min=4}
These additional fields can be viewed in the 'User Profile' view of the ecampaign log.
Using the class EcampaignPHPList, site visitors can be added to a specific PHPList.
The configuration string consists of:
optin=checkbox-field-name listID='PHPList No' configFile='Full server path to PHPList configuration file'
The config file is PHPList's own config.php that contains the database username and password etc. It need not be the actual 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. Any checkbox (not just checkbox1 and checkbox2) can be mapped from a specific action to a specific email list.
In the example configuration below, site visitors who check checkbox1 will be subscribed to PHPList No 6.
optin=checkbox1 listID=6 configFile="/home/web/phplist/public_html/lists/config/config.php"
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.
It is possible to use another class to subscribe to other lists.
The class should implement the methods:The class should be present in a file with the suffix 'class.php'. Take a look at EcampaignPHPList.class.php as an example.
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 Uses http://findyourmp.parliament.uk/api to find the constituency name, MP name, MP email address and a link to the MP's biography web page. That web page is scraped to find the 'address as' field e.g. Dr John Smith and the preferred email address for Westminster (as opposed to constituency) business. When the site visitor clicks lookup, if the email body contains with Dear [name], [name] will be replaced with the 'address as' field. If the biography cannot be read, then the site visitor must do this him/herself before the message can be sent. |
| 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 [name]
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.