MailChimp Newsletter Documentation
Module Installation
Download the module files here. The file you downloaded is a zip file. Unzip the file by right clicking it (Windows) and select Extract All. The folder will contain the following files:
- mailchimp.mvc
- Installation_Instructions.txt (This just contains a link back to this page)
- loading_graphic.gif
- Design Variations (Folder that contains code for 3 other design variations)
Add Module to Store - In the Miva Merchant Admin, click the plus next to Global Settings. Then click the [Add] link next to modules.
Upload the Module - Click the grey upload button and browse to where you downloaded the files in step 1. The module file you want to upload is mailchimp.mvc
Assign the Item to Pages - The module will automatically create an item in your store called mailchimp. This item will automatically assign itself to the following pages:
- SFNT
- CTGY
- PROD
- OCST
If you want your newsletter signup box globally (like in your global header/footer) then you will need to manually assign the mailchimp item to the rest of your pages in your store.
Assign the Item to all Pages (if necessary) - Click on pages then the items tab. Scroll down until you see the mailchimp item and click the edit button on the far right. Next, click on the pages tab. Click the check plus in the header of the check box column to assign the item to all pages. Scroll to the bottom and hit update to save.
Assign the Module to your Store - The last step is to assign the module to your store. From the left menu click on Utilities. On the right side check the box for MailChimp - Newsletter Signup. Click Update to save. This will add a new tab to your Utilities page named MailChimp Newsletter Signup.
Available Items
<mvt:item name="mailchimp" param="headtag" />
There are 3 items available to use with the mailchimp module. The headtag item is what controls all the JavaScript and CSS. You will need to insert this in the head tag of the individual page template you want the newsletter signup box to show up on (SFNT for example). If you want to show the newsletter signup box globally, you will put this item in your Head Tag Content / CSS tab, which will allow you to use the newsletter signup box on all pages.
<mvt:item name="mailchimp" param="textbox" />
The textbox item outputs the HTML for the newsletter signup box. This item can be put on any individual page template where you want to newsletter signup box to go, or if you want your newsletter signup box globaly, then you would typically put this item in your global footer.
Default look and feel for the newsletter signup textbox
<mvt:item name="mailchimp" param="checkbox" />
The checkbox item is only used on OCST (the customer bill to / ship to page). This will add a checkbox during checkout for customers to simply check to add themselves to your newsletter.
Installation Instructions for adding checkbox during checkout.
- In the Miva Merchant admin click on pages and click edit for the OCST page
- Click on the Customer Fields Tab
- Add the checkbox item where ever you want the checkbox to appear on the page. By default the item is configured to capture the Ship To email address however, you have full access to the JavaScript under Advanced Settings. This can be changed if you wish to have it send the Bill To email address instead. For most people, you will want to add it to the bottom of the ship to column.
If you are on CSSUI, look for this code. Place the item right below it.
<label class="required" for="ShipCountry">Country:</label> <mvt:item name="countries" param="ShipCountry" /> </div> <mvt:item name="mailchimp" param="checkbox" /></div>
This will add the check box, right after the select country. Example:
In MMUI add this code:
<tr> <td align="left" valign="middle" colspan="2"> <mvt:item name="mailchimp" param="checkbox" /> </td> <tr>
If you are using MMUI there are 3 additional changes you will need to make in order to get this to work correctly. The module needs to know what fields are the first name, last name and email address fields. In CSSUI they already have the correct ids so no additional editing is needed. In MMUI you also need to make the following changes to each of the 3 input fields:
<input type="text" name="ShipFirstName" size=25 value="" id="ShipFirstName"> <input type="text" name="ShipLastName" size=25 value="" id="ShipLastName"> <input type="text" name="ShipEmail" size=25 value="" id="ShipEmail">
Additionally if you have a customized checkout on CSSUI verify you still have these three ids above in red. The checkbox functionality during checkout will not work without them.
The CSS styles are setup for a default installation of CSSUI. You may have to modify the styles to get the positioning correct.
The styles you want edit are:
.mailchimp #checkbox {
width: 170px;
margin-left: 150px;
}
Create MailChimp Account
In order to use this module you first need to signup for a free MailChimp account. MailChimp is an online email list management software that offers a free account to send up to 12,000 emails a month and up to 2,000 subscribers. They offer paid plans above that as you need more capacity. In the module admin there is a button to create your MailChimp account or Click Here
API Key
The MailChimp API key allows the module to talk to your MailChimp account and add and remove subscribers. This is required before you can use this module. MailChimp makes this easy to get.
Click the "Get Your API Key" link. This will take you to the MailChimp website where it will ask you to login to your account. After you login you will see this screen which contains your API Key.
Enter this API key into the module admin and click update to save.
Lists
After you've successfully enter your API key, a new select drop down will appear called "Select List"
This will contain all the email lists configured in your MailChimp account. If this is a brand new account you should only see a single list. This is the list you want your subscribers to go into when they signup for your mailing list. You can create a new list in the MailChimp admin or you can send users into your default list. A list is required to be selected in order to use the module. If you do not select a list you will see a JavaScript warning when you try to enter in your email address on your store.
Loading Graphic
The loading graphic is the animated gif that appears while the module is communicating with MailChimp to add or remove subscribers. This is not required, but it lets the user know that there is something happening. Typically response times are about 1 to 2 seconds. The module comes with a default graphic which you need to upload or you can choose your own to fit your site.
Advanced Settings
One of the goals of this module was to give developers full access to all the code so they can customize it as needed for their particular needs. In the module tab, there is a sub menu for Advanced Settings. Clicking on this link gives you full access to all the HTML, CSS and JavaScript that is used in this module.
There are 5 text areas in this section which control each of these sections:
- Head Tag
- CSS Stylesheet
- JavaScript
- Checkbox HTML
- Textbox HTML
Each of these sections have full version control so any changes can be easily rolled back. You also will always have an easy way to get back to the original template for each section in case you want to revert back to the default.
Head Tag
The Head Tag is what adds the CSS, and JavaScript calls to the page that the module needs to work. Even though it is called Head Tag, it really can be put anywhere on the page. If you prefer to move this to the global footer so the JavaScript loads last, everything will still work.
The head tag loads the CSS needed, the JS needed and sets 4 global JavaScript variables that are used by the module.
You will see that the module references a mailchimp-style.css and a mailchimp-js.js file. Each of these files are automatically created upon installation of the module. You shouldn't need to edit these paths, however if you prefer to move these files into a different location you have access to do so.
jQuery - To Load Or Not To Load
The head tag also does another really important thing; It loads jQuery which is a popular JavaScript library the module uses. It does not just blindly load jQuery because this could cause problems with other scripts if they use a different version of jQuery. It first checks to see if you already have jQuery loaded. If you do, the JavaScript will not load a new version. I f you do not, it will load jQuery which is required for the module to work. The current version on jQuery is 1.6.4 at the time of this writing. The Key point here is to verify that you don't have any other JavaScript that will break if you load the newest version of jQuery.
If you use other JavaScript libraries such as Moo Tools you most likely will need to make a call to the jQuery noConflict function since many JavaScript Libraries use the $ as a function of variable name.
CSS Stylesheet
One very nice feature of this module is that it automatically creates an external CSS Stylesheet which the module references. No styles are embedded in the page. This file is automatically created upon installation at this location:
/mm5/css/mailchimp-style.css
The /mm5/ may be different for your particular store, but the module will automatically adjust for that. Every time you make an update in the admin to the css section under Advanced Settings the file automatically gets updated. No need to FTP the changes the stylesheet. It can be completely edited from the admin.
The CSS selectors are overly specific on purpose to avoid any conflicts with commonly used ids and classes.
JavaScript
Similar to the CSS, the external JavaScript file is also automatically created during module installation. Its path is located here:
/mm5/js/mailchimp-js.js
This file contains all the JavaScript functions that make the module work. Everything is easily edited via the module admin which will automatically update the file on the server. At the very top of the JS there are 4 variable declarations which can be changed by you to customize the module for your particular store:
//Success Message. Message that fades in once the user has successfully been subscribed. var success_message = "Successfully Subscribed"; //Success Message. Message that fades in once the user has successfully been subscribed. var already_subscribed_message = "Your are already subscribed to our mailing list."; //Unsubscribe Message. Message that shows up when a user has removed their email from your mailing list. var unsubscribe_message = "You have been removed from our email list"; //This is the color that will be used for both the subscribe and unsubscribe error messages. var message_color = "#2398C9";
Checkbox HTML
This the HTML that gets printed wherever you use the checkbox item:
<mvt:item name="mailchimp" param="checkbox" />
Gets Replaced with this:
<input name="newsletter" type="checkbox" value="subscribe" id="newsletter_checkbox" /> Signup for our Mailing List
Textbox HTML
This the HTML that gets printed wherever you use the textbox item:
<mvt:item name="mailchimp" param="textbox" />
Gets replaced with this:
Ecommerce360 Integration
This module has the MailChimp Ecommerce 360 fully integrated. Here is how it works:
When you send out an email campaign using MailChimp you have the option to add a tracking link to your URLs. The links will contain a parameter called ‘mc_cid’. This is the MailChimp Campaign Id. You will need to turn this on when setting up your campaign. There is a setting under advanced tracking options that will add this tracking parameter:
The module will automatically look for this id and if it exists in the url it will save it as a cookie so it can later be accessed if an order is placed and sent to MailChimp.
When a customer clicks on an email campaign link and also places an order, the contents of that order are sent back to MailChimp. This does two very useful things. It allows you to see how much money that email campaign generated and also you can then use MailChimp to create filters on your customers based on what they have purchased in the past.
See the ROI of your email campaigns:
The data above will also be available in Google Analytics (if you add analytics tracking code to your URLs - which you can easily do in MailChimp)
Now that you have all the order information about your list subscribers, you can easily create filters of your lists based on what they bought. Say for example you wanted to send a target email campaign to all customers who purchased a particular product. In MailChimp you can “Segment” your lists based on order history:
You have some great filters available to you such as location, products purchased, order total, and purchase date. Filters can even be chained together to get very targeted lists such as, “all customers in the state of California who purchased product X after a certain date.”
For very large lists, MailChimp has a desktop application that allows you to filter your data offline and upload the filters to MailChimp. You can read about it here:
http://blog.mailchimp.com/introducing-hairball-an-air-app-for-really-complicated-mailchimp-lists/
Important Note: One important thing to note about the ecommerce data that gets sent to MailChimp is if a customer is not subscribed to your list, their order data is still sent to MailChimp. However, they will not show up in any of your filters unless they subscribe to your mailing list. Once they do subscribe, MailChimp will have all their past order history and you will be able to use this data in future email campaign filters you create.
Debugging - Error Log
There is an error log that gets written to the root Miva Data folder named mailchimp_error.log. It is used for recording any errors that may happen for the ecommerce360 integration. If the e-commerce data is not being sent to MailChimp this error log should be able to tell you what the problem is.
Design Variations
There are three design variations you can download and use. Each one comes with new CSS and new HTML. The JavaScript is the same for all of them and does not need to be edited. When you download the module there are three design variations that come included in the download. Each one is separated into its own folder. Each one includes the following files:
Images folder - This contains the images need for this version of the newsletter signup box. These need to be uploaded to your server via FTP to the following location: \mm5\images
Stylesheet - This is the CSS needed to style the HTML newsletter signup box. This needs to be copied and pasted into the module admin: Utilities -> MailChimp Newsletter Signup -> Advanced Settings - >CSS Stylesheet
Textbox HTML - The HTML in this file needs to be copied and pasted into the module admin in the Textbox field: Utilities -> MailChimp Newsletter Signup -> Advanced Settings -> Textbox HTML
Here are the three variations available as part of the module:
Removing Module / Uninstal
To uninstall the module follow these steps:
- Remove the item code from all pages. There are three items available to the module. Go into any page template that references these items and delete the code from the pages.
- Unassign Items - Click on pages, then the Items tab. Edit the mailchimp item then unassign it from all pages.
- Unassign the module from the store - Click utilities. Uncheck the Mailchimp Newsletter Signup module.
- Expand Global Settings and click on modules. Find the mailchimp module and delete it.
The steps must be followed in that order for the module to uninstall successfully.
Error Codes
Module Installation
MER-MC-00001 - Unable to create item “mailchimp”
MER-MC-00002 - Error Assigning item to SFNT page
MER-MC-00003 - Error assigning item to PROD page
MER-MC-00004- Error assigning item to CTGY page
MER-MC-00003 - Error assigning item to OCST page
Templates
MER-MC-00010 - Compile error on head tag template
MER-MC-00011 - Compile error on CSS template
MER-MC-00012 - Compile error on JS template
MER-MC-00013 - Compile error on Checkbox template
MER-MC-00014 - Compile error on Textbox template
Database
MER-MC-00100 - Function: Load_Current_Templates Error: OPENVIEW error
MER-MC-00101 - Function: MAILCHIMP_Insert Error: Query error
MER-MC-00102 - Function: update_list_id Error: Query error
MER-MC-00103 - Function: update_api_key Error: Query error
MER-MC-00104 - Function: update_loading_graphic Error: Query error
MER-MC-00105 - Function: get_list_id Error: Query error
MER-MC-00106 - Function: get_api_key Error: Query error
MER-MC-00107 - Function: get_loading_path Error: Query error
MER-MC-00108 - Function: MailChimp_Category_Id_Lookup Error: OPENVIEW Error
MER-MC-00109 - Function: MailChimp_Category_Name_Lookup Error: OPENVIEW Error