README

Provides an Ajax-powered MailChimp mailing list signup component and an API-driven mailing list dropdown field for use with SilverWare.

Requirements
Installation
Configuration
Usage
Issues
Contribution
Attribution
Maintainers
License

Requirements

Installation

Installation is via Composer:

$ composer require silverware/mailchimp

Configuration

As with all SilverStripe modules, configuration is via YAML. Extensions and required JavaScript are defined by config.yml. You may also modify the default timeout for the API via YAML:

SilverWare\MailChimp\API\MailChimpAPI:
  default_timeout: 10

Before this module can be used, you will need to create a MailChimp API key. Once you have created your API key, you can define it for your app in one of two ways:

via site configuration (Settings tab)
via YAML configuration file

This module will add a MailChimp tab to the Services tab under SilverWare in your site settings. You can paste your API key into the 'MailChimp API Key' field.

Alternatively, you can add your API key to YAML config for your app:

SilverWare\MailChimp\API\MailChimpAPI:
  api_key: <paste the key here>

The key defined in site configuration will take precedence over the YAML key.

Usage

This module provides a MailChimpSignup component and a MailChimpListField for use within forms. The MailChimpSignup component can be added to your SilverWare templates and layouts using the CMS.

MailChimp Signup Component

The MailChimpSignup component is an Ajax-powered signup form for a particular mailing list within your MailChimp account.

If you have added your API key correctly, when you create a new MailChimpSignup component you will see a 'Mailing List' dropdown field. Select the mailing list you would like users to subscribe to when using the form. You may also enter introductory content which will appear above the signup form.

On the Options tab, you can choose whether the fields for first and last names are shown and/or required. You may also modify the messages that are shown to users for certain events, such as when the user subscribes, is already subscribed, or encounters an error.

If the form validates correctly, it will be submitted via Ajax and the appropriate message will appear above the form. The controller will handle a regular POST submission if the Ajax submission does not work.

MailChimp List Field

The MailChimpListField is an extension of a regular DropdownField that connects via the MailChimp API and retrieves the mailing lists within your account. You may use it anywhere you require a user to select a mailing list:

use SilverWare\MailChimp\Forms\MailChimpListField;

$field = MailChimpListField::create(
    'MailingListID',
    'Choose a mailing list'
);

In order to improve performance and to also reduce traffic via the MailChimp API, the field will cache the mailing list results for five minutes by default. You can change this by calling the setCacheTimeout() method and passing the number of seconds as an argument:

$field->setCacheTimeout(60);

Issues

Please use the GitHub issue tracker for bug reports and feature requests.

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.

Attribution

Makes use of MailChimp API by Drew McLellan.

silverware / mailchimp

Maintainers

Details