A couple of months ago, team ThinkShout quietly introduced a feature to the MailChimp module that some of us have really wanted for a long time—the ability to support multiple MailChimp accounts from a single Drupal installation. This happened, in part, after I reached out to them on behalf of the stakeholders at Cornell University's ILR School, where I work. Email addresses can be coveted resources within organizations, and along with complex governance requirements, it's not uncommon for a single organization to have internal groups who use separate MailChimp accounts. I'm not going to comment on whether this is a good or wise practice, just to acknowledge that it's a reality.

In our case, we currently have three groups within school who are using MailChimp extensively to reach out to their constituents. Up until this week, this required a manual export of new subscribers (whom we are tracking with entityforms), some custom code to transform the csv values into the correct format for MailChimp, and then a manual import to the respective list. However, as our most recent deployment, we are now able to support all three group's needs (including one who is using MailChimp automations). Let's dig into how we're doing it.

The important change that ThinkShout introduced came from this commit, which invokes a new alter hook that allows a developer to modify the key being used for the API object. And though this is an essential hook if we want to enable multiple keys, it also doesn't accomplish much given that mailchimp_get_api_object is called in dozens of places through the suite of MailChimp modules and therefore it's difficult to know the exact context of the api request. For that reason, we really need a more powerful way to understand the context of a given API call.

To that end, we created a new sandbox module called MailChimp Accounts. This module is responsible for five things:

  1. Allowing developers to register additional MailChimp accounts and account keys
  2. Enabling developers to choose the appropriate account for MailChimp configuration tasks
  3. Switching to the correct account when returning to configuration for an existing field or automation entity
  4. Restarting the form rendering process when a field widget needs to be rendered with a different MailChimp account
  5. Altering the key when the configuration of a MailChimp-related field or entity requires it

If you want to try this for yourself, you'll first need to download the newest release of the MailChimp module, if you're not already running it. You'll also need to download the MailChimp Accounts sandbox module. The core functionality of the MailChimp Accounts module relies on its implementation of a hook called hook_mailchimp_accounts_api_key, which allows a module to register one or more MailChimp accounts.

In order to register a key, you will need to find the account id. Since MailChimp doesn't offer an easy way to discover an account id, we built a simple callback page that allows you to retrieve the account data for a given key. You'll find this in the admin interface at /admin/config/mailchimp/account-info on your site. When you first arrive at that page, you should see the account values for your "default" MailChimp account. In this case, "default" simply means it's the API key registered through the standard MailChimp module interface, which stores the value in the variables table. However, if you input a different key on that page, you can retrieve information about that account from the MailChimp API.

MailChimp Account info callback page

The screenshot above offers an example of some of the data that is returned by the MailChimp API, but you will see additional information including list performance when you query an active account. The only essential piece of information, however, is the account_id, which we will use to register additional accounts that we can then use via hook_mailchimp_accounts_api_key(). Here's an example of how to implement that hook:


/**
 * Register API key(s) for MailChimp Accounts
 *
 * @return array
 *   The keys are the account id and the values are the API keys
 */
function mymodule_mailchimp_accounts_api_key() { 
  $keys = array(
    '2dd44aa1db1c924d42c047c96' => 'xxxxxxxx123434234xxxxxx3243xxxx3-us13',
    '411abe81940121a1e89a02abc' => '123434234xxxxxx23233243xxxxxxx13-us12',
  ); 
  return $keys; 
}

Once there is more than one API key registered in a Drupal site, you will see a new option to select the current account to use for any MailChimp configuration taking place in the administrative interface. After selecting a different account, you will also see a notice clarifying which API key is currently active in the admin interface. You can see an example in the screenshot below.

MailChimp account notice and select menu

After choosing an account to use for configuration, administrative tasks such as MailChimp subscription fields will use that key when making API calls. Therefore, the available options for lists, merge fields and interest groups will correspond to the appropriate account. Additionally, when the field widget renders the form element, the API key is altered yet again so that the subscriber will be added to the appropriate list, interest groups, etc. Additionally, I can confirm from my testing that the interface for Mailchimp Automations entities also uses the correct API key, enabling support for that MailChimp submodule.

This concludes our walkthrough of the new MailChimp Accounts module. Admittedly, it's not the most elegant solution ever created, but it not only satisfies our organization's complex governance requirements, but it also allows our stakeholders to begin thinking about new possibilities for improving their marketing and communications efforts.

Tags
Drupal

Up Next

Creating Reusable Dynamic Content Components

A screenshot showing the "up next" reusable tagged content block
This is part 2 in this series that explores how to use paragraph bundles to store configuration for dynamic content. The example I built in part 1 was a "read next" section, which could then be added as a component within the flow of the page. The strategy makes sense for component-based sites and landing pages, but probably less so for blogs or content heavy sites, since what we really want is for each article to include the read next section at the end of the page. For that, a view that displays as a block would perfectly suffice. In practice, however, it can be really useful to have a single custom block type, which I often call a "component block", that has an entity reference revisions field that we can leverage to create reusable components.
Tags
Drupal

Drupal Pullquotes

Several powerful quotes with a pullquote sprinkled off to the side to draw a reader's attention
"Pullquotes", as described here, differ from blockquotes because they duplicate a section of text within the page, and get styled in a way that draws the reader's attention to the quote. As such, one simple solution that I've been using is to allow content editors to select a section of text while editing and click a button in the interface to designate it as a pullquote.
Tags
Drupal

Creating Paragraphs Entities for Dynamic Content

Logos with Paragraphs, Drupal and Atomic Design
The paragraphs module has become a central ingredient for many component-based sites in recent years. However, our content strategy also often requires components that display dynamic content (think "Read Next", or "Also of Interest"). In this tutorial, I'll demonstrate how we've been solving this problem, by building paragraph bundles that serve as configuration entities that we can then use as arguments that we pass to a view via the Twig Tweak module. You can see a working version of the dynamic content component we'll be building in the "Up Next" card grid at the bottom of this tutorial.
Tags
Drupal