Champagne 2Version 2.3.2

Buy Now

Prerequisites

Make sure your installation meets the minimum requirements:

Example Code

To help you get started, we have included examples for subscriber forms and campaign templates in the Champagne 2 download. You can find them in the examples directory.

Installation

  1. Copy system/expressionengine/third_party/champagne to your expressionengine/third_party directory.
  2. Copy system/expressionengine/third_party/html_to_text_email to your expressionengine/third_party directory.
  3. Copy themes/expressionengine/third_party/champagne to your themes/third_party folder.
  4. Within the EE Control Panel, go to Add-Ons > Modules. Find Champagne in the list of modules and click Install
  5. Select to install all Champagne artifacts — the Module, Extension and the Fieldtype.

Settings

Champagne 2 settings are managed via the Extension Settings area.

  1. To configure your settings, go to Add-Ons > Extensions. Find Champagne in the list of extensions and click Settings.
  2. Enter your Campaign Monitor Settings first. You will need to locate your API Key and Client ID. We have provided inline instructions for locating these two items within the settings form.
  3. Enter your Channel Settings next. You will select the template path for rendering your HTML and Text email campaigns.

Security

In order for non-admin members to be able to publish campaigns, you must grant the following security privileges to the member group the user belongs to:

  1. Go to Members > Member Groups
  2. Click on the Edit Group link for the Group you wish to grant access to.
  3. Under the Control Panel Access section > Can access ADD-ONS section
    • select Yes.
  4. Under the Control Panel Access section > Can access ADD-ONS: Modules - select Yes.
  5. Under the Module Access Privileges section > Can access module: Champagne - select Yes.
  6. Click Update to save your changes.

Publishing Campaigns

In order to begin publishing campaigns, you will need to complete the following steps:

  1. Create and configure the channel, channel fields, etc as you would normally do for creating a standard channel.
  2. Create your template group (e.g. campaigns) and templates (e.g. text and html) as you would normally do for displaying content within a channel. Sample templates are provided to get you started.
  3. Code your templates to display a HTML version as well as a Text version of the campaign. The html_to_text_email plugin is a handy tool for coding the Text version.
  4. Verify/update your extension settings so that the correct templates are selected for the channel you will be using to store your campaigns.
  5. Go to Publish → Your Campaign Channel
  6. Enter your content and save. You cannot publish a campaign until the entry is saved in EE.

Once you’ve completed the steps above, you are ready to publish! Here are the typical steps for publishing a campaign.

  1. Open your campaign for editing.
  2. Click on the Champagne tab.
  3. Step 1 – Provide a name and subject for your campaign.
  4. Step 2 – Select recipient(s) from your list of Subscriber Lists and Segments.
  5. Step 3 – Choose delivery option (3 options).
    • Send a Test Preview of the campaign. This will create a draft campaign that you can later choose to send immediately or schedule a date. Specify multiple email addresses separated by a comma.
    • Send Immediately.
    • Schedule the Campaign for delivery at a future date.
  6. Click the green button which will be labeled according to your selection in Step 3.
  7. If all goes well, you should see a success message. Otherwise, you will see an error explaining the problem. Errors come straight from the Campaign Monitor API.

When you send a preview of the campaign or if you schedule a campaign, a draft is created in your Campaign Monitor account. If you need to change the name, subject, specify a different recipient or need to reschedule you must first delete the existing campaign. The Campaign Monitor API doesn’t support editing a draft or editing a scheduled campaign; therefore you must first delete the campaign within the Champagne tab.

Sent Campaigns

You can view a summary report for sent campaigns by opening the entry in edit mode and clicking on the Champagne tab.

Subscriber Forms

Need to add Campaign Monitor subscriber forms to your site. Below you will find examples and documentation.

Input Fields

name (optional)

The input field for capturing the subscriber’s name.

email (required)

The input field for capturing the subscriber’s email address.

list_id (required if not specified as a parameter)

Value should be set to the list id obtained from your branded version of Campaign Monitor. Use if you want users to choose what list to join. The user must select at least one list before submitting or an error will occur.

    <input type="checkbox" name="list_id[]" value="1111" />
    <input type="checkbox" name="list_id[]" value="2222" />

Campaign Monitor custom fields

In order to collect CM custom field data, you must name your form input fields 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" />

Parameters

list_id (required unless you are specifying list_id as a form

input)

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

return (required)

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

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.

form_id (optional)

Use the form_id parameter to assign a value to the id attribute of the form.

form_class (optional)

Use the form_class parameter to assign a value to the class attribute of the form.

Countries Tag

The countries tag will display a list of countries. Useful for country custom fields.

    <select name="country">
        {exp:champagne:countries}<option value="{country}">{country}</option>{/exp:champagne:countries}
    </select>

Example Subscriber Forms

Basic

    {exp:champagne:subscriber list_id="xxxx|xxxx" form_id="champagne" form_class="subscriber" return="/champagne/thanks"}
        <fieldset>
            <p>
                <label for="subscribe-name">Enter your name</label>
                <input type="text" size="30" name="name" value="" id="subscribe-name"/>
            </p>
            <p>
                <label for="subscribe-email">Enter your email</label>
                <input type="text" size="30" name="email" value="" id="subscribe-email"/>
            </p>      
        </fieldset>
        <p><input class="btn" type="submit" value="Join Subscriber List" /></p>           
    {/exp:champagne:subscriber}

Custom Fields

    {exp:champagne:subscriber list_id="xxxx" form_id="champagne_custom" form_class="subscriber" return="/champagne/thanks" custom_fields="country|interests|gender"}
        <fieldset>
            <p>
                <label for="subscribe-name">Enter your name</label>
                <input type="text" size="30" name="name" value="" id="subscribe-name"/>
            </p>
            <p>
                <label for="subscribe-email">Enter your email</label>
                <input type="text" size="30" name="email" value="" id="subscribe-email"/>
            </p>          
            <p>
                <label for="subscribe-country">Select your country</label>
                <select name="country" id="subscribe-country">
                    {exp:champagne:countries}<option value="{country}">{country}</option>{/exp:champagne:countries}
                </select>
            </p>
            <p>
                <input type="checkbox" name="interests[]" value="Cooking" id="subscribe-cooking" /><label for="subscribe-cooking">Cooking</label>
                <input type="checkbox" name="interests[]" value="Hiking" id="subscribe-hiking" /><label for="subscribe-hiking">Hiking</label>
                <input type="checkbox" name="interests[]" value="Music" id="subscribe-music" /><label for="subscribe-music">Music</label>
                <input type="checkbox" name="interests[]" value="Technology" id="subscribe-technology" /><label for="subscribe-technology">Technology</label> 
            </p>
            <p>
                <input type="radio" name="gender" value="Male" checked="checked" id="subscribe-male" /><label for="subscribe-male">Male</label>
                <input type="radio" name="gender" value="Female" id="subscribe-female" /><label for="subscribe-female">Female</label> 
            </p>
        </fieldset>
        <p><input class="btn" type="submit" value="Join Subscriber List" /></p>           
    {/exp:champagne:subscriber}

Selectable Subscriber Lists

    {exp:champagne:subscriber form_id="champagne" form_class="subscriber" return="/champagne/thanks"}
        <fieldset>
            <p>
                <label for="subscribe-name">Enter your name</label>
                <input type="text" size="30" name="name" value="" id="subscribe-name"/>
            </p>
            <p>
                <label for="subscribe-email">Enter your email</label>
                <input type="text" size="30" name="email" value="" id="subscribe-email"/>
            </p>      
            <p>
                <input type="checkbox" name="list_id[]" value="xxxx" id="xxxx" /><label for="xxxx">Champagne 2</label>
                <input type="checkbox" name="list_id[]" value="xxxx" id="xxxx" /><label for="xxxx">Geofinder</label>
                <input type="checkbox" name="list_id[]" value="xxxx" id="xxxx" /><label for="xxxx">Geotagger</label>
            </p>
        </fieldset>
        <p><input class="btn" type="submit" value="Join Subscriber List" /></p>           
    {/exp:champagne:subscriber}

Top of Page