Champagne Documentation

Please contact us if you have questions or see incorrect or missing information.

Installation

1. Unzip downloaded file
2. Copy language/english/lang.champagne.php to your language directory (e.g. /_your_ee_system_dir_/language/english/).
3. Copy extensions/ext.champagne.php to your extensions directory (e.g. /_your_ee_system_dir_/extensions/).
4. Copy folder modules/champagne to your modules directory (e.g. /_your_ee_system_dir_/modules/).
5. Login to the ExpressionEngine Control Panel.
6. Go to the Modules Tab, find Champagne in the list of available modules and click “Install”.
7. Go to the Extensions Manager, find Champagne in the list of available extensions and click “Enable”.

Extension Configuration (Publishing Campaigns)

Base Settings

1. Click on the settings link for Champagne in the Extensions Manager.
2. Make sure Enable for this site is set to Yes.
3. Enter the label name that will appear on the Publish Form (e.g. Create Send).

Campaign Monitor Settings

1. Enter your Campaign Monitor API Key (While logged in to Campaign Monitor, located in Account Settings page).
2. Enter the Client ID (While logged in to Campaign Monitor, select your client and click on Client Settings).
3. Enter the From Name to be used in campaigns
4. Enter the From Email to be used in campaigns
5. Enter the Reply To Email to be used in campaigns
6. Enter the Confirmation Email to be used in campaigns
7. Enter the URL to your Campaign Monitor branded application

Weblog Settings

1. Find the weblog that you want to store campaigns in.
2. Select Yes for Display Tab in Publish Form
3. Enter the relative path that will be used for HTML versions of your campaigns (e.g. /campaigns/html/)
4. Enter the relative path that will be used for Text versions of your campaigns (e.g. /campaigns/text/)
5. The entry_id is appended to both values you specify above to render both HTML and Text versions of your campaigns. Keep that in mind when you build your templates for displaying campaigns.
6. Click Save Settings

Publishing Campaigns from ExpressionEngine

1. Complete Extension Configuration steps above.
2. Create weblog for campaigns (e.g. newsletter).
3. Create custom fields for campaigns weblog. Playa field types work great for newsletter style campaigns where you want to pull in existing content from other weblogs in your site to be included in your campaign (e.g. blog, events, etc).
4. Create template(s) used to render the HTML & Text version of the campaign. The entry_id should be used to render the appropriate campaign content.
5. Once weblog and template setup is complete, you are ready to create the content for the campaign.
6. Go to Publish > “Weblog Name” (e.g. Campaigns, Newsletters).
7. Enter your content for the campaign and save the entry (Entry must be saved before you can create campaign).
8. Go to Create Send tab (or your custom name for the tab) within publish form.
9. Select the lists or segments to send the campaign to.
10. Select send the campaign immediately or schedule the campaign to be sent at a later date
11. Use the preview links for quick access to view how your campaign will be rendered via ExpressionEngine
12. Click Create Campaign to publish the campaign to Campaign Monitor
13. If all goes well, you should see a “Successfully Published Campaign” message, otherwise you will see an error explaining the problem. Errors come straight from the Campaign Monitor API and are very straightforward so tracking down issues is quite easy.

Deleting Scheduled Campaigns from ExpressionEngine

1. It is very important to note, if you create a scheduled campaign from EE—only delete or modify the campaign from within EE. Doing otherwise will cause the campaign to be out of sync and cause issues.
2. To delete a campaign, find the entry in EE and open it for editing
3. Click on the tab label you created for Champagne
4. Click the Delete Campaign button.
5. If all goes well, you should see a “Successfully deleted campaign” message.
6. You may now reschedule the campaign if you wish.

Viewing Campaign Summary Report from ExpressionEngine

1. After successfully sending a campaign that was generated within EE, you can go to the Edit tab to find the campaign.
2. After opening the entry, click on the tab label you created for Champagne and you will be able to view the summary report data.
3. A link is also provided to view the full report for the campaign. This links to your Campaign Monitor branded app.

Adding subscriber forms to your ExpressionEngine site

Basic Subscriber Form Example

{exp:champagne:subscriber id="subscribe" return="subscribe/thanks" error="subscribe/error" list_id="{cm_subscriber_list_id}" api_key="{cm_api_key}"}
			<fieldset>
			<p class="name input"><label for="name">Name:</label><input type="text" size="30" name="name" id="name" value="Full Name" onfocus="this.value='';" onblur="if (this.value == '') { this.value = 'Full Name'; }"/></p>
			<p class="email input"><label for="email">Email:</label><input class="required" type="text" name="email" id="email" size="30" value="you@yourdomain.com" onfocus="this.value='';" onblur="if (this.value == '') { this.value = 'you@yourdomain.com'; }" /></p>			
			<p class="submit"><button class="btn subscribe" type="submit">Subscribe Now</button></p>
			</fieldset>		    
	{/exp:champagne:subscriber}	

Subscriber Form with CM Custom Fields Example

{exp:champagne:subscriber id="subscribe" return="subscribe/thanks" error="subscribe/error" list_id="{cm_subscriber_list_id}" api_key="{cm_api_key}" custom_fields="Location|Interests"}
			<fieldset>
			<p class="name input"><label for="name">Name:</label><input type="text" size="30" name="name" id="name" value="Full Name" onfocus="this.value='';" onblur="if (this.value == '') { this.value = 'Full Name'; }"/></p>
			<p class="email input"><label for="email">Email:</label><input class="required" type="text" name="email" id="email" size="30" value="you@yourdomain.com" onfocus="this.value='';" onblur="if (this.value == '') { this.value = 'you@yourdomain.com'; }" /></p>
			<p><select name="Location">
				<option>Australia</option>
				<option>UK</option>
				<option>USA</option>
				</select></p>
			<p><input type="checkbox" name="Interests[]" value="Cooking" /><label>Cooking</label>
				<input type="checkbox" name="Interests[]" value="Hiking" /><label>Hiking</label>
				<input type="checkbox" name="Interests[]" value="Music" /><label>Music</label>
				<input type="checkbox" name="Interests[]" value="Music" /><label>Technology</label>					
			<p class="submit"><button class="btn subscribe" type="submit">Subscribe Now</button></p>
			</fieldset>		    
	{/exp:champagne:subscriber}

Subscriber Form Input Fields

• “name”
• “email”
• Handling CM custom fields

name (optional)

The input field for capturing the subscriber’s name

email (required)

The input field for capturing the subcriber’s email

Handling CM custom input fields

In order to collect CM custom field data, you must name your form input fields exactly the same as how they appear in Campaign Monitor.

Multi-select fields should use the following format for names (note open and closed brackets signifying multi-value input type):

<input type="checkbox" name="Interests[]" value="Cooking" />

Subscriber Form Parameters

• “api_key” (required)
• “list_id” (required)
• “return” (required)
• “error” (required)
• “custom_fields” (only required if capturing custom field values)
• “id” (optional)

api_key (required)

The Campaign Monitor API key or reference to global variable name that holds it.

list_id (required)

The Campaign Monitor list id for the subscriber list. Separate multi list_id’s with “|”.

return (required)

The relative path to return the user to once form is submitted.

error (required)

The relative path to return the user to when errors occur during form submission. The Campaign Monitor API error code will be appended to the path so that you have the option of displaying meaningful, context sensitive error messages for each error code.

custom_fields (only required if capturing custom field values)

The names of the Campaign Monitor Custom Fields that you are gathering. Separate each custom field with the “|” character. Ensure the custom field name you specify matches what you have setup in Campaign Monitor and the name attribute for the input itself.

id (optional)

Use the id parameter to assign a value to the id attribute for the form.

Changelog

1.0

• Initial Release

1.0.1

• Fixed bug where adding new channels caused error in extension settings
• Fixed bug “Invalid Get Data” caused by illegal characters.

1.0.3

• New feature – You can now set the subject for a campaign or default it to the title of the entry.
• New feature – When sending campaigns for immediate delivery, you are now prompted for a confirmation before the campaign is generated.
• New feature – Now you can preview campaigns that have a status not set to “open”.
• Better citizen – We’ve improved handling for certain Campaign Monitor status codes (e.g. When client’s don’t have approval to send to a large list and when payment details for a client need to be sorted out.)

Table of Contents