+61 (3) 9642 8454   hello@thirststudios.com

Give us a call

+61 (3) 9642 8454

Drop us a line

Or drop in for a coffee at our funky office → Level 3, 360 Little Collins Street, Melbourne, Victoria, 3000, Australia.

Ready to get started with us for your next project? Launch our project planner »

Our blog

Andrew Gunstone

Written by
Andrew Gunstone
30 Mar 2009

A recent project had a lot of requirements. Most were straightforward, and things we come across in our daily lives as web developers... blog, news, about us, contact form, etc. As with all clients, they also had a few requirements that were not quite "out of the box". Along with these usual features, the site required the Content Management System (CMS) to create petition forms for individual campaigns that they were running. It may come as no surprise to those who know me... but of course I turned to ExpressionEngine to help solve my problems.

This tutorial is for people who are already familiar with ExpressionEngine, it's templating, weblog and module methods.

The objective

Our objective for this is pretty simple. Allow site authors to create campaigns that may (or may not) have a petition form attached.

Each petition form must track users individually, plus users must be able to "sign" multiple petitions, but can only "sign" a single petition once.

Validation for the single "sign up" on petitions will be using the users email address (okay so this is not the most stringent testing, but in my case it didn't need anything more!).

Getting set-up

Clearly from the title of this tutorial you may have guessed that we will be using ExpressionEngine (EE), and the fantastic (and free!) Solspace Freeform module. So to get started, install both ExpressionEngine and the Freeform module as per their instructions!

One thing to make sure of... once you have successfully installed EE, then installed the Freeform module, make sure that you have enabled the module via the "Modules" tab in the EE Control Panel.

From here, we won't go into how to setup all the lovely other bits you are going to use with your website, such as the About Us page, or the Contact page, or even your very witty and informative blog page. I am guessing you already know how to do this, or can find some other great tutorials about it (you can find some great tutorials at the Train-EE website).

The Campaigns weblog and custom fields

It's now time to setup a new EE Weblog where we can add in our new campaigns. Give the weblog a Full Weblog Name of 'Campaigns', and a short name of 'campaigns'. At this point, I also create a new Template Group with (unsurprisingly) the name 'campaigns'. Creating the Template Group now simply saves us having to do it later.

Next up we need to create our custom field group for the Campaigns weblog.

The custom field group should contain (at least) the following fields:

Field Label - Summary
Field Name - campaign_summary
Field Type - Textarea
Default Text Formatting for This Field - XHTML
Field Label - Body
Field Name - campaign_body
Field Type - Textarea
Default Text Formatting for This Field - XHTML
Field Label - Email Address
Field Name - campaign_email
Field Type - Text Input
Default Text Formatting for This Field - None
Field Label - Is a Petition?
Field Name - campaign_is_petition
Field Type - Drop-down List
Select Options - No | Yes *
Default Text Formatting for This Field - None

(* Note that each Select Option should be on an individual line. Put the 'No' option first, so it can be the default).

Once you have created all of your custom fields, remember to change the Campaigns weblog 'groups' to use the new Campaigns custom fields group.

Now that we have our new Campaign weblog, and have created our custom fields, it might also be worth create a couple of 'sample' weblog entries. Mix it up a little bit for testing, so that some of the campaigns use the petition (i.e. the Is a Petition? field is set to 'Yes'), and some don't.

Create the templates

If you haven't already created a Campaign Template Group, then go ahead and do it now. This will automatically add an 'index' web-page template into the group.

As well as the 'index' template, create two new web-page templates - 'details' and 'campaign_form'.

The 'index' template

I am not going to go into much detail for the 'index' template. It is a pretty normal weblog listing page, that simply displays a list of your current Campaigns entries. I tend to use the {comment_url_title_auto_path} tag, but you need to remember to set this up correctly in the Campaigns weblog preferences page.

** HEADER **
<h1>Campaigns</h1>
{exp:weblog:entries weblog="campaigns" dynamic="off" disable="member_data|pagination|trackbacks" limit="10"}

<h3><a href="{comment_url_title_auto_path}">{title}</a></h3>
<p>Posted by {author} on {entry_date format="%F %d %Y"}</p>
{campaign_summary}

<p>&raquo; <a href="{comment_url_title_auto_path}">Read more</a></p>
{/exp:weblog:entries}
** FOOTER **

The 'details' template

The 'details' template is where it starts getting a little more interesting. For the most part it is a pretty standard template, which 'finds' the right entry from the URL (i.e. dynamic is set to ON), and outputs the title, summary and body.

As part of this template we use the if statement to test whether the 'campaign_is_petition' is set to 'Yes', and then if required, we embed the 'campaign_form' template. Note that we pass two extra parameters to the 'campaign_form' embed - we pass the '{url_title}' field to 'form_name' parameter and the ' {campaign_email}' field to 'petition_email' parameter.

By using the power of the EE {embed} tag, we can start to customise each petition form for individual campaigns! Neat!

** HEADER **
{exp:weblog:entries weblog="campaign" dynamic="on" disable="member_data|pagination|trackbacks"}
<h1>{title}</h1>
<p>Posted by {author} on {entry_date format="%F %d %Y"}</p>
{campaign_summary}
{campaign_body}

{/exp:weblog:entries}
** FOOTER **

The 'campaign_form' template

Here is where the very simple, but very clever stuff actually happens. It is simple because all we are doing is embedding a simple form as appropriate into our campaign details page. The form is run using the 'out of the box' {exp:freeform:form} tag. So far so good.

The great thing about Freeform is that if we simply change the 'form_name' parameter of the {exp:freeform:form} tag, it captures, and reports on these separately in the Freeform Module interface. In this case, we are using the campaign entries 'url_title' (which by default has to be unique to an entry) as the 'form_name', which ultimately allows us to track which petition a user has 'signed'.

The other great thing about Freeform, is that we can also check to see if a user has already 'signed' a petition form using the 'prevent_duplicate_on' parameter! This parameter only checks against the list of entries under a given 'form_name'... thus allowing a user to sign a single petition only once, but sign any of the multiple petitions that they are interested in!

As one last piece of cleverness, we also pass the 'campaign_email' (using ' {embed:petition_email}') into the 'notify' parameter. If no email was added to the Campaign entry, then no email is sent, however if you want to be notified whenever a user 'signs' the petition, simply add your email address into the 'campaign_email' field!

{exp:freeform:form required="name|email|postalcode" require_ip="yes" prevent_duplicate_on="email" form_id="petitionForm" form_name="{embed:form_name}" return="thank_you" notify="{embed:petition_email}" template="default_template" }
<fieldset>
  <p>
   <label for="name">Name:</label>
   <input type="text" name="name" value="" />
  </p>
  <p>
   <label for="email">Email:</label>
   <input type="text" name="email" value="" />
  </p>
  <p>
   <label for="postcode">Postcode:</label>
   <input type="text" name="postalcode" value="" maxlength="4" />
  </p>
  <p>
   <input type="submit" value="Submit" name="send" class="submit" />
  </p>
</fieldset>
{/exp:freeform:form}

Note that I have added a 'return' parameter of 'thank_you'. You will need to create the 'thank_you' template separately. You can add a 'return' page template of whatever you like.

Testing your petition

Testing your petition is now easy. If you haven't already linked the Campaigns page into the main navigation, you should be able to get to it via a URL like this:

http://www.mydomain.com/index.php/campaigns/

Clearly this will depend on many factors including, what your domain name is, whether you have removed the 'index.php', etc.

Checking the results

If everything has been set-up correctly, and you have done a few tests on your 'sample' petitions, you can then check your results from the Freeform module page in your EE Control Panel.

Simply open the Control Panel, click on the Modules tab, then on the Freeform module. The first page you shown has two columns... Form Name, and Count. There should be a Form Name for each of the unique 'url_title' fields in your Campaign entry, with the total amount of 'signatures' you have for the petition under the Count column. To see individual entries, click on the Form Name.

Conclusion

That's it. I am sure you clever EE guys and girls will figure out many ways to extend this little tutorial, but it is a simple, easy way to set-up petitions using only built-in EE functionality, and free modules (thanks Solspace!).

Any comments on how to you may have used, or improved this, please add them below.

Enjoy!

blog comments powered by Disqus