MODx Evolution and MailChimp
In this post we’re going to go over how to get the MailChimp snippet set up and working on your MODx Evolution site. MailChimp is a service that allows you to send email newsletters, manage subscriber lists, and track campaign performance. You can of course simply create the forms and such directly in MailChimp and paste the supplied code into your site, but this little snippet works just great. The directions I will outline here are also covered in the documentation inside the snippet folder, but I thought I would go over it for my own future reference and for anyone who may not be aware that this snippet exists or who may have had trouble setting it up. I am using MODx Evolution 1.0.2 and will be setting this demo up on the Learn MODx website.
You need a MailChimp account and at least one list to work through this tutorial. Setting up an account on MailChimp is free, and you can opt for the free plan to start out and then upgrade to the paid plan as your needs increase. We’re going to create a demo list for the coding pad for this tutorial.
Get the MODx MailChimp Snippet
The snippet to make this work was created and generously shared by MODx developer Garry Nutting and is available on the MODx forum. I am also attaching the snippet to this post for ease of download. But make sure you visit the thread for support and more comments.
Install the Snippet
As always, the process of installing the snippet is pretty straightforward.
- Extract the files to your desktop or other convenient location.
- Inside the zipped file you will find the folder named ‘mailchimp‘, inside of which are two folders – ‘classes‘ and ‘includes‘ as well as several files. Upload this mailchimp folder to your assets->snippets folder.
- Next, in your site manager, under Elements->Manage Elements->Snippets, create a new snippet and call it mailchimpSubscribe. In the code block, paste the code found in the subscribe.snippet.php file.
Configuring the snippet
So now we have the snippet installed and ready to go, but you need to do one more thing to make sure that it can access your account and get information about your specific lists. To do this, you need to edit the file config.inc.php that’s inside the includes folder. Here, you need to place your MailChimp account user name and password. Simply replace <USERNAME> with your username and <PASSWORD> with your password. You can do this before uploading the files, or afterward in the manager.
Create the Form
Next, you have to create a chunk with the actual form that users will fill out to subscribe to your list. Again the process is pretty straightforward. When you create a list in MailChimp, you decide how many fields the form should have. It can be a simple form with just an email address, or one that has more fields, such as first name, last name, and email. The default fields when you create a form are currently first name, last name, and email address. Adding more fields is easy, go to your list, and click “Settings”
Click on “List Fields and *|MERGE|* Tags“. Here, you can add new fields that your user will fill when subscribing to your list. For our demo list, we’re going to add a field for the subscriber to add their website url. You can also delete the first and/or last name fields here if you don’t want them to appear. The only field that must be present is the email field.
Make sure also that you note the tag names for the fields (highlighted below in green) as we will need these to create the form chunk.
To create the form, create a new chunk and call it whatever you want. I will call mine mcSubscribeForm. In this chunk, we simple enter the usual HTML for a form, with MODx variables, and our field tag names from MailChimp. Note that the field names have the prefix mc_ and then the tag name.
<p>[+MailChimp.message+]</p> <form method="post" action="[~[*id*]~]"> <label>First Name: <input type="text" name="mc_FNAME" value="" /></label><br /> <label>Last Name: <input type="text" name="mc_LNAME" value="" /></label><br /> <label>Email: <input type="text" name="mc_EMAIL" value="" /></label><br /> <label>Website: <input type="text" name="mc_URL" value="" /></label><br /> <input type="submit" name="subscribe" value="Subscribe" /> </form>
You can add more labels and inputs depending on your fields or remove the ones you don’t need. To add another field that you had created for your list form you would use the same syntax as above:
<label>LABEL : <input type=”text” name=”mc_TAG” value=”” /></label><br />
The Subscribe button MUST retain the name “subscribe”, so leave that unchanged. Once this is done, your snippet is more or less ready to go.
You can also add checkbox or dropdown type of fields but I honestly haven’t tried it, but I’m sure it’s doable. For now we’re going to keep this simple.
Calling the Snippet
The last thing we need to do before calling our snippet and setting things up is to find our listID. You can find this in MailChimp by going to lists and again by selecting “Settings” as before. Scroll down the page and you’ll find the list ID. Copy this somewhere, you will need to insert it into your snippet call.
So now you’re ready to go. The snippet call is pretty straightforward. The two parameters are &form, which is the name of your form chunk, and &listId, which is the list ID for your list.
[!mailchimpSubscribe? &form=`your_form_chunkname` &listId=`your_listID` !]
In my case, the snippet call with my form chunk name and my list ID would be:
[!mailchimpSubscribe? &form=`mcSubscribeForm` &listId=`9627f9b5a4` !]
If you’ve done everything right, you should now get a form on your site where your users can subscribe themselves to your list and you can send them newsletters and campaigns.
You can ofcourse style the form to your heart’s content by adding the appropriate CSS to your style files.
This snippet is nice and works well in allowing a more seamless integration of MailChimp within your MODx website. It doesn’t have a lot of parameters but it does the trick. Test it and let me know how you like it. Also, don’t forget to visit the forum thread and drop a thank you to Garry for creating this and making it available for us to use.