README

Easy Forms for Mailchimp

Latest Stable Beta Release Candidate

This is the development repo for the Easy Forms for Mailchimp plugin by YIKES, Inc. where we work on new features and bug fixes.

Minimum Requirements

WordPress 3.8+
PHP v5.3+

Plugin Preview Screenshots

Cloudup Gallery

Documentation

For full documentation, please visit our Knowledge Base.

Integrations

Easy Forms for Mailchimp integrates well with many popular third party plugins for WordPress:

WooCommerce
Easy Digital Downloads
BuddyPress
BbPress
Contact Form 7
Visual Composer

Questions?

Have any questions? Feel free to open up an issue in the issue tracker and we'll get back to you as soon as possible.

Grunt.js

To develop with Grunt place Gruntfile.js file inside the plugin root during development (/wp-content/yikes-inc-easy-mailchimp-extender/). The paths inside Gruntfile.js are setup relative to the plugin root, so placing it anywhere else without changing the paths will cause an error.

First, make sure you install the latest version of Grunt to the local project directory.

$ npm install -g grunt -cli

$ npm install -g grunt

Finally, run the install task to install the required dependencies.

$ npm install

Shortcode

[yikes-mailchimp form="#"]

Full List of Shortcode Parameters

form - the ID of the form you want to display (required)
submit - the text of the submit button below the form (optional - defaults to "Submit")
title - display the title above the form (1 or 0) (optional - defaults to 0)
description - display the description above the form (1 or 0) (optional - defaults to 0)

API Key Constant

A few users requested the ability to store their API key in a PHP constant, inside of wp-config.php. With version 6.1.2, users can now define a new constant inside of wp-config.php, YIKES_MC_API_KEY, and assign the API key there, which will then be used throughout the plugin. Note: When you define the constant, you'll still need to head into the settings page and update the plugin options.

Example: define( 'YIKES_MC_API_KEY', '12345679-us2' );

CSS Ready Classes

2 Column Layout

field-left-half / field-right-half - assign this class to place the field in the left/right column of a 2 column form layout.

3 Column Layout

field-left-third / field-right-third - assign this class to place the field in the left/right most column of a 3 column form layout.

2/3/4 Colum Radio Buttons

option-2/3/4-col - split the radio or checkbox options into 2, 3 or 4 columns

Filters + Hooks

Filters

yikes-mailchimp-form-title - Alter the output of the form title of the specified form. @params: $title, $form_id
yikes-mailchimp-form-description - Alter the output of the form description of the specified form. @params: $description, $form_id
yikes-mailchimp-redirect-timer - Alter the amount of time in milliseconds the user sees the success message before being redirected. Default: 1500 - @params: $time, $form_id
yikes-mailchimp-redirect-url - Alter the URL of the page that the user will be redirected to on a successful submission. @params: $url, $form_id, $page_data
yikes-mailchimp-filter-before-submission and yikes-mailchimp-filter-before-submission-{$form_id} - Catch the merge variables before they get sent over to Mailchimp. @params: $merge_variables
yikes-mailchimp-after-submission and yikes-mailchimp-after-submission-{$form_id} - Catch the merge variables after they get sent over to Mailchimp. @params: $merge_variables
yikes-mailchimp-user-role-access - Alter who can access this plugin page by capability. Default: manage_options - @params: $capability
yikes-mailchimp-international-phone-pattern - Alter the regex pattern for acceptable international phone number formats. Default: '[0-9,-,+]{1,}' - @params: $regex_pattern
yikes-mailchimp-us-phone-pattern - Alter the regex pattern for acceptable US phone number formats. Default: ^($[0-9]{3}$|[0-9]{3}-)[0-9]{3}-[0-9]{4}$ - @params: $regex_pattern
yikes-mailchimp-zip-pattern - Alter the zip code regex pattern. Default: \d{5,5}(-\d{4,4})? - @params: $regex_pattern
yikes-mailchimp-process-default-tag - Alter the default form field value for text fields. @params: $default_value
yikes-mailchimp-{$merge_tag}-label - Alter the specified form field's or interest group's label text. @params: $label
yikes-mailchimp-{$merge_tag}-description - Alter the specified form field's or interest group's description text (note: if targeting an interest group, it will be the group_id instead of the merge tag). @params: $description_content, $form_id.
yikes-mailchimp-address-{$type}-label - Alter the field sub-label text for a specific address field (e.g. addr1). @params: $label
yikes-mailchimp-form-submit-button - Alter the submit button to your liking. @params: $submit_button, $form_id
yikes-mailchimp-form-submit-button-text - Alter the submit button text. Default: submit - @params: $submit_button_text, $form_id
yikes-mailchimp-form-submit-button-classes - Add additional classes to the submit button for further styling. @params: $classes, $form_id
yikes-mailchimp-form-container-class - Add additional classes to the <section> element container that wraps the form. @params: $class_name, $form_id
yikes-mailchimp-form-class - Add additional classes to <form> element of your opt-in form. @params: $class_name, $form_id
yikes-mailchimp-front-end-form-action-links - Add custom front end action links alongside Edit Form, Customize Form etc. @params: $form_action_links, $form_id, $form_name
yikes-mailchimp-custom-default-value-tags - Define your own custom pre-defined tags to populate the default value fields with - these tags appear in the modal. @params: $pre_defined_tags_array
yikes-mailchimp-parse-custom-default-value - Process your custom default merge tag into a custom value to populate the form field with (note: Goes hand in hand with yikes-mailchimp-custom-default-value-tags filter). @params: $default_tag
yikes-mailchimp-field-data - Filter form field data such as placeholder, label, etc. @params: $field_array, $field, $form_id
yikes-mailchimp-subscriber-count-value - Alter the returned value for the total subscriber count of a given Mailchimp list. @params: $subscriber_count
yikes-mailchimp-frontend-content - Custom content filter for this plugin to prevent others from hooking in where not wanted.
yikes-mailchimp-recaptcha-parameters - Alter any of the possible reCAPTCHA shortcode parameters. @params: $recaptcha_parameter_array, $form_id
yikes-mailchimp-preloader - Add a custom preloader image. Default: WordPress's wpspin_light.gif. @params: $url_to_spinner_gif
yikes-mailchimp-update-email-subject - Filter the subject line for the email that is generated and sent when a user needs to update their subscription info. @params: $email_subject
yikes-mailchimp-update-email-content - Filter the content of the email that is generated and sent when a user needs to update their subscription info. @params: $email_body
yikes-mailchimp-success-response - Alter any success response text. @params: $response_text, $form_id, $submitted_form_variables
yikes-mailchimp-default-country-value - Alter the default country selected in the country dropdown. Default: US - @params: $country_slug
yikes-mailchimp-recaptcha-required-error - Filter the error displayed back to the user when an error occurs during the reCAPTCHA submission process. @params: $error_text, $form_id
yikes-mailchimp-sslverify - Toggle sslverify on/off when attempting to validate your API key with the Mailchimp API servers. Default: true (on) - @params: $use_ssl
Version 6.3.0:

yikes-mailchimp-success-double-optin-response - Filter the "Success: Double opt-in" custom message. @params: $message, $form_id
yikes-mailchimp-success-single-optin-response - Filter the "Success: Single opt-in" custom message. @params: $message, $form_id
yikes-mailchimp-success-resubscribed-response - Filter the "Success: Re-subscriber" custom message. @params: $message, $form_id
yikes-mailchimp-user-already-subscribed-link-text - Filter the "Success: Re-subscriber with link to email profile update message" custom message. @params: $message, $form_id
yikes-mailchimp-general-error-response - Filter the "Error: General" custom message. @params: $message, $form_id
yikes-mailchimp-user-already-subscribed-text - Filter the "Error: Re-subscribers not permitted" custom message (note: this replaced yikes-mailchimp-user-already-subscribed-error). @params: $message, $form_id
yikes-mailchimp-filter-groups-before-submission and yikes-mailchimp-filter-groups-before-submission-{$form_id} - Filter the interest groups before they're submitted. @params: $groups, $form_id
yikes-mailchimp-address-2-required - Change the address 2 field's required value. Default: '' (it is never required) - @params: $required, $form_id
yikes-mailchimp-filter-subscribe-request and yikes-mailchimp-filter-subscribe-request-{$form_id} - Filter all of the fields sent over to the Mailchimp API (not just the form fields). @params: $subscribe_body, $form_id
yikesinc_eme_default_api_version - Filter the API version. Default: 3.0 - @params: $version
yikesinc_eme_api_url - Filter the URL used for a request to the Mailchimp API. @params: $full_path, $path
yikesinc_eme_api_user_agent - Filter the user agent used in API request. @params: $user_agent
yikesinc_eme_api_auth_headers - Filter the authentication headers used in the API request. @params: $auth_headers, $api_version
yikesinc_eme_api_headers - Filter the headers used for a request to the Mailchimp API. @params: $headers, $path, $method, $params
yikesinc_eme_api_timeout - Filter the timeout (in seconds) used when sending an API request. Default: 15 @params: $timeout
yikesinc_eme_api_args - Filter the arguments used for a request to the Mailchimp API. @params: $args, $path, $method, $params

Hooks

yikes-mailchimp-form-submission and yikes-mailchimp-form-submission-{$form_id} - Do something with the user email + form data on form submission. @params: $email, $merge_variables, $form_id, $notifications
yikes-mailchimp-after-submission and yikes-mailchimp-after-submission-{$form_id} - Do something with only the $merge_variables (note: these actions are fired off directly after yikes-mailchimp-form-submission).
yikes-mailchimp-before-submission and yikes-mailchimp-before-submission-{$form_id} - Do something with the $merge_variables before the API request. @params: $merge_variables
yikes-mailchimp-after-form - Do something after a form has been loaded. @params: $form_id
yikes-mailchimp-before-checkbox - Do something (e.g. output custom content) before the opt-in checkbox for all integrations.
yikes-mailchimp-after-checkbox - Do something (e.g. output custom content) after the opt-in checkbox for all integrations
yikes-mailchimp-support-page - Do something (e.g. output custom content) on the support page (note: we use this to add our support form for premium users).
yikes-mailchimp-edit-form-section-links - Add additional links to the edit form page next to 'Custom Messages'.
yikes-mailchimp-edit-form-sections - Add custom section to the edit form page.
yikes-mailchimp-edit-form-notice - Hook to display a custom notice on the edit form page.
yikes-mailchimp-shortcode-enqueue-scripts-styles - Hook to enqueue custom scripts & styles wherever the shortcode is being used. @params: $form_id
yikes-mailchimp-additional-form-fields - Define additional fields to add below all forms. @params: $form_data
yikes-mailchimp-custom-form-actions - Add custom action links on the manage forms page (alongside Edit, Duplicate, Shortcode, Delete). @params: $form_id
yikes-mailchimp-list-form-fields-metabox - Add additional content to the 'Form Fields' metabox on the view list page.
yikes-mailchimp-list-interest-groups-metabox - Add additional content inside of the interest groups metabox on the view list page.

Hooks for Extensions

yikes-mailchimp-menu - hook to add additional menu items inside of the "Easy Mailchimp" menu item
yikes-mailchimp-settings-field - hook to register additional settings fields for add-ons
yikes-mailchimp-ADDON-SLUG-options-path - hook to load up a custom settings page

Helper Shortcodes

Display current number of subscribers [yikes-mailchimp-subscriber-count form="1"]

Display the current number of subscribers for a given list. Pass in the form ID whos list you want to display. (also accepts list="mailchimp_list_id")

If you want to use the snippet inside of your form description, you can exclude the form ID and list ID altogether, and the shortcode will reference the list associated with the displayed form.

Example Form Description: Join the [yikes-mailchimp-subscriber-count] happy subscribers who receive our mailing list!

which might display on the front end like: Join the 1,543 happy subscribers who receive our mailign list!

Custom Edit Form Sections API

Since we've built out a few add-ons to extend the base functionality, we've also built out an API to allow users to rapidly define custom sections on the edit form screen. This allows you to assign additional data to your forms.

We use this API extensively to build out additional sections on the edit form page.

Example:

First hook in to the proper locations, and attach a function:

add_action( 'yikes-mailchimp-edit-form-section-links' , 'add_custom_section_link' );
add_action( 'yikes-mailchimp-edit-form-sections' , 'render_custom_section' );

Next , define your sections and fields by passing in a multi-dimensional array.

/* Add custom link to the links (next to fields & custom messages) */
public function add_custom_section_link() {
	// creating a new link on the edit form page
	Yikes_Inc_Easy_Mailchimp_Extender_Helper::add_edit_form_section_link( array(
		'id' => 'custom-section', // section id
		'text' => 'Custom Section', // the text that will display in the link
		'icon' => 'admin-appearance' // dashicon icon class
	) );

	// creating a new link on the edit form page
	Yikes_Inc_Easy_Mailchimp_Extender_Helper::add_edit_form_section_link( array(
		'id' => 'custom-section-2', // section id
		'text' => 'Custom Section 2', // the text that will display in the link
		'icon' => 'admin-appearance' // dashicon icon class
	) );
}

/* Add custom section associated with link created above */
public static function render_custom_section() {
	// defining a new section, associated with the link above
	Yikes_Inc_Easy_Mailchimp_Extender_Helper::add_edit_form_section( array(
		'id' => 'custom-section',  // section id (must match link id above)
		'main_title' => 'Main Section Title', // title of the main block of this custom section
		'main_description' => __( 'This is a custom description for the main section' , 'test' ),
		'main_fields' => array(
			array(
				'label' => 'Custom Field #1', // label text for this field
				'placeholder' => 'Placeholder Value',  // placeholder value for the input field
				'type' => 'text', // type of field (text,select,checkbox,radio)
				'id' => 'custom-field-1', // field id - determines how data is saved in database
				// 'description' => __( 'Testing custom description for field #1' , 'test' ), // field description
			),
			array(
				'label' => 'Custom Field #2', // label text for this field
				'placeholder' => 'Placeholder Value #2', // placeholder value for the input field
				'type' => 'text', // type of field (text,select,checkbox,radio)
				'id' => 'custom-field-2', // field id - determines how data is saved in database
				'description' => __( 'Testing custom description for field #2' , 'test' ), // field description
			),
		),
		'sidebar_title' => 'Sidebar Section Title', // sidebar title of the sidebar section
		'sidebar_description' => __( 'This is a custom description for the sidebar section' , 'test' ),
		'sidebar_fields' => array(
			array(
				'label' => 'Dropdown Field',
				'type' => 'select',
				'options' => array(
					'1' => 'one',
					'2' => 'two',
					'3' => 'three',
				),
				'id' => 'select-field',
				'description' => __( 'this is a select field.' , 'test' ),
			),
		),
	) );
}

yikesinc / yikes-inc-easy-mailchimp-extender

Maintainers

Details