forked from EvanHerman/yikes-inc-easy-mailchimp-extender
-
Notifications
You must be signed in to change notification settings - Fork 0
/
readme.txt
1301 lines (992 loc) · 57.9 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=== Easy MailChimp Forms ===
Contributors: yikesinc, hiwhatsup, liljimmi, eherman24, seriouslysean
Donate link: http://yikesinc.com
Tags: mailchimp, marketing, email, mailing lists, newsletter, sign up, forms, sign up form
Requires at least: 3.0
Tested up to: 4.3.1
Stable tag: 5.4.4
License: GPLv2 or later
Easy MailChimp Forms allows you to painlessly add MailChimp sign up forms to your WordPress site and track user activity with interactive reports.
== Description ==
Easy MailChimp Forms allows you to painlessly add MailChimp sign up forms to your WordPress site. You can add forms to posts, pages or sidebars with shortcodes, widgets or template tags. Simply copy and paste your MailChimp API Key into the plugin admin settings and it will pull in all your MailChimp lists. From there you can choose the lists you want to make forms for. For a single list you can check off the fields you want to include on your form and order them via an easy drag-and-drop interface. This plugin adds plenty of CSS selectors to the form code allowing you to completely customize the look of your forms. Now with the ability to track sent campaigns, you can view and print interactive reports from based on previously sent campaigns.
**Note:** You will need a MailChimp API key to allow this plugin to communicate with your MailChimp account. For help on retrieving your API key, check out [question #4 of the FAQ](http://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/faq/). You can also read the MailChimp knowledge base article [Where can I find my API key and how can I use the API](http://kb.mailchimp.com/article/where-can-i-find-my-api-key/).
**Features**
* Add interest groups and new fields to forms directly from the dashboard without leaving your site (*new*)
* Error log for diagnosing user issues (*new*)
* All new No-Captcha Re-Captcha in place (*new*)
* Design your own sign up form templates
* Style your forms without writing a single line of code
* Full Integration of MailChimp into WordPress
* Easily import MailChimp forms from an active MailChimp account
* View/Print Interactive Account Growth Reports and Campaign Reports (Statistics Tracking)
* Monitor MailChimp account activity
* Use MailChimp Interest Group/Segments
* Add MailChimp forms sidebars/widgetized areas with widgets
* Set forms to single or double opt-in
* Customize the success message
* Customize the submit button text
* Redirect users to a page on submission
* Un-subscribe users from MailChimp lists
* View subscriber MailChimp profiles
* View individual form subscriber count
* Display multiple forms on a single page
* Add commenter's to your MailChimp lists with a comment form opt-in check box
* Easily add forms to pages and posts with a button in the page/post editor
* Use cURL error detection to troubleshoot MailChimp connection issues
Instructions on how to use the plugin can be [found in the FAQ](http://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/faq/). If you experience any problems, please submit a New Issue on our [Github Issue Tracker](https://github.com/yikesinc/yikes-inc-easy-mailchimp-extender/issues) and we'll look in to it as soon as possible.
== Installation ==
1. Download the plugin .zip file
2. Log in to yourdomain.com/wp-admin
3. Click Plugins -> Add New -> Upload
4. Activate the plugin
5. Head over to [MailChimp.com](http://www.mailchimp.com) and login.
6. On the right hand menu, click your profile picture and select 'Account Settings' and then go to 'Extras > API Keys'.
7. Enter your API key into the text field inside 'MailChimp Forms > MailChimp Settings'
8. (Optional) Sign up for a reCAPTCHA API Key Head over to [https://www.google.com/recaptcha/admin#whyrecaptcha](https://www.google.com/recaptcha/admin#whyrecaptcha) and login.
9. (Optional) Register for an API key. Enter your public <em>and</em> private keys into the reCAPTCHA settings page and save your settings.
9. Go to the 'Manage List Forms' page, start importing forms from MailChimp and adding them to posts, pages and widgets!
10. Start collecting user emails and growing your subscriber list!
== Frequently Asked Questions ==
= Do I need to have a MailChimp Account? =
Yes, you can register for one for free at [MailChimp](https://login.mailchimp.com/signup? "MailChimp").
= Do I need to have lists already set up in MailChimp? =
Yes, you have to have at least 1 list set up in MailChimp.
For more help, visit the MailChimp Support article [How do I create a new list?](http://kb.mailchimp.com/article/where-can-i-find-my-api-key "How do I create a new list?")
= What do I do first? =
The first step is to add your MailChimp API key. This will allow your site to communicate with your MailChimp account. This is done on the plugin "MailChimp Settings" page.
= Where do I find my API Key? =
From your MailChimp Dashboard, click on your account name in the upper left hand corner of the screen under the MailChimp logo to expose the "Account Settings" menu. Click on "Account Settings" to go to the Account Settings screen and the click on the "Extras" menu. Under "Extras" choose "API keys." From there you can create a new key if you do not already have one.
For more help, visit the MailChimp Support article [Where can I find my API Key?](http://kb.mailchimp.com/article/where-can-i-find-my-api-key "Where can I find my API Key?")
= How to I add my MailChimp lists? =
After you add your API key, the plugin will fetch all of your MailChimp list information and load it into the plugin admin. Go to the plugin "Manage List Forms" page to choose the lists you want to make forms for.
= How do I add the MailChimp sign up forms to my site? =
You can use a shortcode to add a form to a page or post, use the MailChimp form button in the visual editor or use a widget to add it to a sidebar. Each list on the plugin "Manage List Forms" displays a shortcode at the top. Copy the shortcode and paste it into any post or page where you want a form to appear. For example, if my form had the shortcode [yks-mailchimp-list id="1234567891"] I would copy and paste that into the page or post I wanted to add that form to.
= I input a valid MailChimp API key, but it returns invalid every time. I've already tried a new API key, but no dice. What's up? =
**Step 1:** Ensure that cURL is enabled at the server level. You will see an error at the top of the settings page if cURL is disabled. If you see no error, continue to step 2.
**Step 2:** If you have entered your MailChimp API key and are still getting the error "*Error: Please enter a valid Mail Chimp API Key*," please check the developer console inside your browser for further information.
- Right-click in the API Key input field, and select 'Inpsect Element'
- Once the developer console is open, select the Console tab to view a more specific error returned from the MailChimp API.
For information on how to use your browser's developer console, read the WordPress Codex article, [Using Your Browser to Diagnose JavaScript Errors](http://codex.wordpress.org/Using_Your_Browser_to_Diagnose_JavaScript_Errors).
**Possible Errors And Resolutions**
* Could not resolve host: xxxx.api.mailchimp.com - the host you have provided is incorrect. The host is the string after the last dash (example: us2)
* Invalid Mailchimp API Key: xxxxxxxxxxxxxxxxxx-xxx - Your API key is invalid. You can confirm a valid key by logging into [MailChimp](http://mailchimp.com) and checking the active API key registered to your account.
= I don't want the form to be the 100% width. How can I adjust the width myself? =
You can adjust the width of the forms on your site by changing the width of the element with the class .yks-mailchimpFormContainer. This is the parent container for the form. Adjusting this width will control the width of the input fields inside of it.
= How can I translate this plugin? =
Easy MailChimp Forms is now translated into multiple languages:
* Arabic
* Chinese
* English
* French
* German
* Greek
* Hebrew
* Hindi
* Hong Kong
* Italian
* Japanese
* Korean
* Persian
* Portuguese (Brazilian)
* Portuguese (European)
* Romanian
* Russian
* Spanish
* Swedish
* Taiwanese
* Tamil
* Urdu
* Vietnamese
* Welsh
Read the Codex article [Installing WordPress in Your Language](http://codex.wordpress.org/Installing_WordPress_in_Your_Language) for more information. Also, please refer to our [Developer Docs](http://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/other_notes/).
= Do you provide any hooks, or filters for me to take advantage of? =
Yes! With the 4.0 version of our plugin we have added a few hooks that allow you to add or manipulate existing data. Check out the [Other Notes](http://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/other_notes/) tab for more information.
= Do you offer integration with reCAPTCHA? I keep getting spam entries from bots and spammers. =
Yes! Since version 4.4 of Easy MailChimp Extender, we have added [reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) support. You can sign up for a reCAPTCHA API key [here](https://www.google.com/recaptcha/admin#whyrecaptcha). You will need to provide your <em>public</em> key as well as the <em>private</em> key. Don't worry, its free :)
= When I input my API key and hit save, it immediately reverts to a much shorter string of text and returns invalid. What's going on? =
You most likely have a password manager installed and active (LastPass, OnePass, TeamPassword etc.). The API key input field is set to type="password" for security reasons. Most password managers auto-fill password fields based on the URL of the current page. So, what happens when you click save is that the password manager auto fills in the field with the password that you have saved for your site, and thus returning 'invalid API key'. To resolve the issue you'll need to temporarily disable any active password manager and re-enter and save your API key. Once the key has been successfully saved, you can re-enable your password manager.
= How do I create my own custom MailChimp template? =
**Step 1:**
First you'll want to import the boilerplate template files bundled with the plugin. These are files that were created for easy customization. You can import the boilerplate files by going to the manage list forms page and clicking 'import boilerplate templates'.
<em>Note :</em> Alternatively, you can manually import the template files by copying the 'yikes-mailchimp-user-templates' directory inside of the plugin root ( 'yikes-inc-easy-mailchimp-extender/templates/' ) over to your theme root. ( ie: /wp-content/themes/twentyfourteen/ ).
**Step 2:**
Once imported you'll find the boilerplate files in your theme root. Each boilerplate template file comes with an associated .css file located inside of the styles directory. To get started on your first template, we recommend that you duplicate one of the existing boilerplate tempalate files and its associated .css file, and changing the name.
**Step 3:**
Finally, change the MailChimp template, author and description headers at the top of each template file. The 'MailChimp Template' header dictates the name of your template, and what will appear in the drop down field. You'll also want to make sure that the correct .css file is properly being enqueued at the top of the template file.
**Step 4:**
Once setup, you can assign the template to your form from the 'Manage List' page. Make sure to select the checkbox 'use custom form' and then in the drop down select your newly created template.
= I'm trying to set up the opt-in commenting checkbox. When users opt-in and leave a comment, an error is thrown and I can't figure out why. What could be wrong? =
For the optin comment check box, you'll want to make sure that the form you have set to assign users to only has the email field set to required.
= I'd like to define my own default value tags. For example, I want to populate a field with the current page URL dynamically. Is this possible? =
Yes! In the release of YIKES Inc. Easy MailChimp Extender version 5.2 we enabled all sorts of new features. One of these features is the ability to pre-populate text fields with a string of text, or with one fo the provided default value tags.
The default value tags available to you out of the box are :
* {post_title} - populates the field with the current <strong>page or post title</strong> that the user was on when they subscribed to the form.
* {post_id} - populates the field with the current <strong>page or post ID</strong> that the user was on when they subscribed to the form.
* {page_url} - populates the field with the current <strong>page URL</strong> that the user was on when they subscribed to the form.
* {blog_name} - populates the field with the current <strong>blog name</strong>. Very useful for multi-site installations, when tracking which blog the user has signed up from is crucial to your marketing efforts.
* {user_logged_in} - populates the field with with a dynamic value based on weather the user is logged in or not. When the user is logged in when signing up, the field populates with "User Logged In". If the user is not logged in, "Guest".
Simply click the link below the default value input field to add that tag as the default value. Easy as that!
We've also provided a way for you to define your own default value tags, and return any data you choose. This is done through the use of two separate filters ( `yikes_mailchimp_default_value_tag` and `yikes_mailchimp_process_default_value_tag` ). Check out the developer documentation for how to use the filters. The examples provided are extremely helpful.
= Can I move the success/error message to below the form instead of displaying them above? =
Yes! In version 5.3, we've allowed users to declare a constant which dictate where the error and success messages will appear in relation to the forms.
By default , the error and success messages appear above the form. If you'd like them to appear below the form, simply add the following definition to your active themes function.php file.
`
define( "display_yikes_mc_form_messages", "after" );
`
== Developer Docs. ==
**Text Domain**
**Name:**
`yikes-inc-easy-mailchimp-extender`
**Description:**
90% of the plug-in is localized and ready for translation. This means that you can manipulate text using the provided text domain, using a gettext filter.
**Accepted Parameters:**
N/A
**Example:**
This example will alter text on the admin dashboard on the manage lists page.
`
<?php
/**
* Change Specific Test on the 'Manage List Forms' page.
*
*/
function theme_change_comment_field_names( $translated_text, $text, $domain ) {
switch ( $translated_text ) {
case 'Your Lists' :
$translated_text = __( 'MailChimp Lists', 'yikes-inc-easy-mailchimp-extender' );
break;
case 'Save Form Settings' :
$translated_text = __( 'Save Form', 'yikes-inc-easy-mailchimp-extender' );
break;
case 'Create a Form For This List' :
$translated_text = __( '<== Import This List', 'yikes-inc-easy-mailchimp-extender' );
break;
}
return $translated_text;
}
add_filter( 'gettext', 'theme_change_comment_field_names', 20, 3 );
?>
`
<br />
**Hooks**
**Hook Name:**
`yks_mc_before_form_$formID`
**Description:**
Used to place content before a specific MailChimp form. Use the form id to specify which form to place text before.
**Accepted Parameters:**
N/A
**Example:**
This example will print out a thank you message before a specific form.
`
<?php
/**
* Function to add text before the form with ID '0b071c0bd1'
* You can get form ID's from the 'MailChimp List' page
*/
function custom_before_form_action() {
echo '<p>Thanks for checking out our mailing list. Fill out the form below to get started!</p>';
}
add_action( 'yks_mc_before_form_0b071c0bd1' , 'custom_before_form_action' );
?>
`
*Note: in our add_action call we add the specific form ID to target a single form.*
<br />
**Hook Name:**
`yks_mc_after_form_$formID`
**Description:**
Used to place content after a specific MailChimp form. Use the form id to specify which form to place text after.
**Accepted Parameters:**
N/A
**Example:**
This example will print out a disclaimer message after a specific form._
`
<?php
/**
* Function to add text after the form with ID '0b071c0bd1'
* You can get form ID's from the 'MailChimp List' page
*/
function custom_after_form_action() {
echo '<p><em>Your information is for internal use only, and will never be shared with or sold to anyone.</em></p>';
}
add_action( 'yks_mc_after_form_0b071c0bd1' , 'custom_after_form_action' );
?>
`
**Note**: in our add_action call we add the specific form ID to target a single form.
<br />
**Hook Name:**
`yks_mc_before_form`
**Description:**
Used to place content before *all* MailChimp Forms.
**Accepted Parameters:**
N/A
**Example:**
`
<?php
/**
* This example will print out a disclaimer to the user,
* above all MailChimp forms.
*/
function custom_before_all_forms_action() {
echo '<p><em>Your information is for internal use only, and will never be shared with or sold to anyone.</em></p>';
}
add_action( 'yks_mc_before_form' , 'custom_before_all_forms_action' );
?>
`
<br />
**Hook Name:**
`yks_mc_after_form`
**Description:**
Used to place content after *all* MailChimp Forms.
**Accepted Parameters:**
N/A
**Example:**
`
<?php
/**
* This example will print out a disclaimer to the user,
* below all MailChimp forms.
*/
function custom_after_all_forms_action() {
echo '<p><em>Your information is for internal use only, and will never be shared with or sold to anyone.</em></p>';
}
add_action( 'yks_mc_after_form' , 'custom_after_all_forms_action' );
?>
`
<br />
**Filters**
**Filter Name:**
`yikes_mc_field_label`
**Accepted Parameters:**
`$label`
**Parameter Info:**
`$label = the text of the field label you would like to alter.`
**Description:**
The following example will change the default 'Email Address' label to 'Email!'
**Example:**
This example will alter the 'Email Address' field label, and return 'Email!'
`
<?php
/**
* This example will alter the 'Email Address' field label, and return a
* new custom label name ('Email!')
* anything else falls under 'default' and returns the un-altered label
*/
function alter_mailchimp_field_labels( $label ) {
switch ( $label ) {
default :
echo $label;
break;
case 'Email Address': // text of the existing label
echo 'Email!'; // new email label text
break;
}
}
add_filter( 'yikes_mc_field_label' , 'alter_mailchimp_field_labels' );
?>
`
<br />
**Filter Name:**
`yks_mailchimp_user_role`
**Accepted Parameters:**
`$capability`
**Parameter Info:**
`$capability = the lowest capability allowed to access the administration pages. defaults to 'manage_options' (admins).`
**Description:**
The following example will allow editors to access the YIKES MailChimp administration pages on the dashboard.
**Example:**
The following example will allow editors to access the YIKES MailChimp administration pages on the dashboard.
`
<?php
/**
* This example will allow editors to access the YIKES MailChimp administration pages
* If you would like authors or another user role to be able to access the admin pages, you
* must set this to the lowest capability allowed. ( check : http://codex.wordpress.org/Roles_and_Capabilities for role capabilities )
* <em>note: for authors, you would use the 'publish_posts' capability.</em>
*/
function yikes_mailchimp_allow_editors( $capability ) {
$capability = 'edit_others_pages';
return $capability;
}
add_filter( 'yks_mailchimp_user_role' , 'yikes_mailchimp_allow_editors' );
?>
`
<br />
**Filter Name:**
`yikes_mc_get_form_data`
**Accepted Parameters:**
`$Form_ID` and `$merge_variables`
**Parameter Info:**
`$Form_ID = the ID of the specific MailChimp Form ( can be retrieved from the 'MailChimp Forms > Manage List Forms' menu ).`
`$merge_variables = a multi-dimensional array containing all user entered data being sent to the MailChimp API (The email, first name, last name etc. will be contained here).`
**Description:**
Used to catch user data, *from all forms*, before it gets sent to the mailchimp API. Useful when you want to manipulate data before being sent to the MailChimp API or if you'd like to use the entered data locally.
**Example:**
This example will catch the user submitted data, *of all forms*, store the users firstname in a variable and then update the current logged in user firstname profile field with the value in the First Name MailChimp field.
`
<?php
/**
* This example will catch the user submitted data, of all forms, store the users firstname in a variable and then update
* the current logged in user firstname profile field with the value in the First Name MailChimp field.
*/
function catch_user_data( $form_ID, $merge_variables ) {
// if the user is logged in
if ( is_user_logged_in() ) {
// get the logged in user id
$user_id = get_current_user_id();
// if the first name field is set
if ( isset( $merge_variables['FNAME'] ) ) {
// update logged in users first name with the provided name in MC form
wp_update_user( array( 'ID' => $user_id, 'first_name' => $merge_variables['FNAME'] ) );
// can be used for any of the fields in the form + any fields in the user profile
}
}
}
add_filter( 'yikes_mc_get_form_data' , 'catch_user_data', 10, 2 );
?>
`
<br />
**Filter Name:**
`yikes_mc_user_already_subscribed`
**Accepted Parameters:**
`$errorMessage` , `$update_user_link` and `$email`
**Parameter Info:**
`$errorMessage = the error message returned by the MailChimp API. By Default : "email@domain.com is already subscribed to the list."`
`$update_user_link = the link that will re-submit the form to update the current users info. Default link text : "Update My Info"`
`$email` = the email address provided in the Email field
**Description:**
Used to display a custom error message back to the user, when a user attempts to subscribe to a list they already exist on.
**Example:**
The following example will alter the error returned from the MailChimp API. Useful when you would like to provide a more custom error message. The 'Update' link will re-submit the form using the 'update_existing' parameter to update the current users profile.
`
<?php
/**
* This example will return a custom error message to the user when they attempt to subscribe to
* a list they already exist on. The following will show something similar "Sorry, John@johnsmith.com is already subscribed to this list. Please Update My Information."
*/
function custom_user_already_subscribed_error( $errorMessage , $update_user_link , $email ) {
$errorMessage = 'Sorry, ' . $email . ' is already subscribed to this list.';
$errorMessage .= str_replace( 'Update My Info.' , 'Please Update My Information' , $update_user_link );
return $errorMessage;
}
add_filter( 'yikes_mc_user_already_subscribed' , 'custom_user_already_subscribed_error' , 10 , 3 );
?>
`
<br />
**Filter Name:**
`yikes_mc_subscriber_update_message`
**Accepted Parameters:**
`$success_message`
**Parameter Info:**
`$success_message = the success message to be displayed to the user, defaults to "Thanks, your information has been successfuly updated."`
**Description:**
Used to alter the success message returned when a user updates their account information for a given list
**Example:**
The following example will alter success message displayed back to the user after they have updated their account information for a given list. Defualts to : "Thanks, your information has been successfuly updated."
`
<?php
/**
* The following example will alter the success message when a user re-submits
* the form data to update their information for a given form
*/
function custom_resubmit_info_message( $success_message ) {
$success_message = "Thanks for updating your info! You're so awesome!";
return $success_message;
}
add_filter( 'yikes_mc_subscriber_update_message' , 'custom_resubmit_info_message' , 10 );
?>
`
<br />
**Filter Name:**
`yks_redirect_add_post_types`
**Accepted Parameters:**
`$post_array `
**Parameter Info:**
`$post_array = an array of post type names that you would like to be included into the drop down as a redirect option on the manage list page`
**Description:**
Use this filter to add any number of custom post types to the redirect dropdown
**Example:**
The following example will add any and all posts with the custom post type 'portfolio' to the redirect dropdown
`
<?php
/**
* This example will add the custom post type 'portfolio' to the
* redirect dropdown on the manage list forms page
*/
function add_portfolio_post_type_to_yikes_redirect_dropdown( $post_array ) {
$post_array[] = 'portfolio';
return $post_array;
}
add_filter( 'yks_redirect_add_post_types' , 'add_portfolio_post_type_to_yikes_redirect_dropdown' );
?>
`
<br />
**Filter Name:**
`yikes_mailchimp_default_value_tag`
**Accepted Parameters:**
`$custom_tag_array `
**Parameter Info:**
`$custom_tag_array = an array of custom default tags. eg: array( '{custom_default_tag_1}' , '{custom_default_tag_2}' );`
**Description:**
***Note: if you're trying to set up custom default value tags, you'll want to use this filter as we'll as the one directly below it (yikes_mailchimp_process_default_value_tag). This filter adds your custom tag to the array, the `yikes_mailchimp_process_default_value_tag` filter processes the tag and replaces it with specific data.***
Using this filter you can add new default value tags to the accepted tags. Any tags that you setup with this filter will appear in the list of selectable tabs to populate the default value field. The default value tags available to use out of the box are :
* {post_title} - populates the field with the current <strong>page or post title</strong> that the user was on when they subscribed to the form.
* {post_id} - populates the field with the current <strong>page or post ID</strong> that the user was on when they subscribed to the form.
* {page_url} - populates the field with the current <strong>page URL</strong> that the user was on when they subscribed to the form.
* {blog_name} - populates the field with the current <strong>blog name</strong>. Very useful for multi-site installations, when tracking which blog the user has signed up from is crucial to your marketing efforts.
* {user_logged_in} - populates the field with with a dynamic value based on weather the user is logged in or not. When the user is logged in when signing up, the field populates with "User Logged In". If the user is not logged in, "Guest".
**Example:**
The following example will add two new default value tags to the accepted default value tags array list, `{new_custom_tag}` and `{new_custom_tag_2}`.
`
<?php
/**
* This example will add two new user defined tags to the list of accepted default value tags array list
* - note, this will only add your tags to the the list. use the next function to parse the tag and return some value
**/
function custom_yikes_mailchimp_default_value_tag( $custom_tag_array ) {
$custom_tag_array = array( '{new_custom_tag}' , '{new_custom_tag_2}' );
return $custom_tag_array;
}
add_filter( 'yikes_mailchimp_default_value_tag' , 'custom_yikes_mailchimp_default_value_tag' , 10 );
?>
`
<br />
**Filter Name:**
`yikes_mailchimp_process_default_value_tag`
**Accepted Parameters:**
`$field `
**Parameter Info:**
`$field = the $field variable is a serialized array of data for the specific field. The array includes things such as the name, default value etc.`
**Description:**
***Note: if you're trying to set up custom default value tags, you'll want to use this filter as we'll as the one directly above it (`yikes_mailchimp_default_value_tag`). This filter is used to parse your code and return a value to the field. Use this in conjunction with `yikes_mailchimp_default_value_tag`.
You'll use this filter to parse the custom default value tag you set up in the filter directly above this one (`yikes_mailchimp_default_value_tag`). Here you can perform all sorts of complex queries and functions to pull specific user data, page data, site data or anything else you can image.
**Example:**
The following example will add two new default value tags to the accepted default value tags array list, `{new_custom_tag}` and `{new_custom_tag_2}`.
`
<?php
/**
* You can use the following function to process the custom default value tag into some useful data
* ( note : you must pass in your new default custom tags using the provided yikes_mailchimp_default_value_tag filter (see example above ) )
* ---------------------------------------------------------------------------------------------------------
* Example #1 : Converts {new_custom_tag} into the users display name
* Example #2 : Converts {new_custom_tag_2} into the referral page ( used to track how users landed on this page )
**/
function process_custom_yikes_mailchimp_default_value_tag( $field ) {
switch ( $field['default'] ) {
// convert {new_custom_tag} into usable data
case '{new_custom_tag}':
global $current_user;
// get current user info.
get_currentuserinfo();
// set this custom default tag to the users display name
$default_value = $current_user->display_name;
break;
// convert {new_custom_tag} into usable data
case '{new_custom_tag_2}':
$default_value = $_SERVER["HTTP_REFERER"];
break;
default:
$default_value = $field['default'];
break;
}
// return the default field value
return $default_value;
}
add_filter( 'yikes_mailchimp_process_default_value_tag' , 'process_custom_yikes_mailchimp_default_value_tag' , 10 );
?>
`
<br />
**Filter Name:**
`yikes_mc_get_form_data_$formID`
**Accepted Parameters:**
`$merge_variables`
**Parameter Info:**
`$merge_variables = a multi-dimensional array containing all user entered data being sent to the MailChimp API (The email, first name, last name etc. will be contained here).`
**Description:**
Used to catch user data, of a specific form, before it gets sent to the mailchimp API. Useful when you want to manipulate data before being sent to the MailChimp API or if you'd like to use the entered data locally.
**Example:**
This example will catch the user submitted data *from a specific form*, store the users firstname in a variable and then update the current logged in user firstname profile field with the value in the First Name MailChimp field.
`
<?php
/**
* This example will catch the user submitted data, store the users firstname in a variable and then update
* the current logged in user firstname profile field with the value in the First Name MailChimp field.
* This catches data from ALL forms being submitted.
*/
function catch_user_data_from_specific_form( $merge_variables ) {
// if the user is logged in
if ( is_user_logged_in() ) {
// get the logged in user id
$user_id = get_current_user_id();
// if the first name field is set
if ( isset( $merge_variables['FNAME'] ) ) {
// update logged in users first name with the provided name in MC form
wp_update_user( array( 'ID' => $user_id, 'first_name' => $merge_variables['FNAME'] ) );
// can be used for any of the fields in the form + any fields in the user profile
}
}
}
add_filter( 'yikes_mc_get_form_data_3d13f0f784' , 'catch_user_data_from_specific_form', 10, 2 );
?>
`
***Customizing Templates Using Filters***
**Filter Name:**
`yks_mc_template_header`
**Description:**
Use this filter to alter the header text in any of the bundled sign up templates.
**Example:**
The following will alter the header text in any of the bundled sign up forms. In the 'Clean Blue' template, this will change 'Sign Up Now' in the header, to 'Sign Up Below'.
`
<?php
/**
* The following example will alter the header text in any the bundled template
* from 'Sign Up Now' to 'Sign Up Below'
*/
function yks_easy_mailchimp_custom_template_header_text() {
return 'Sign Up Below';
}
add_filter( 'yks_mc_template_header' , 'yks_easy_mailchimp_custom_template_header_text' , 10 );
?>
`
<br />
**Filter Name:**
`yks_mc_template_sub_text`
**Description:**
Use this filter to alter the sub text in any of the bundled sign up templates. The sub text is the text below the header, and above the form. eg: "Sign up for mailing list and receive new posts directly to your inbox."
**Example:**
The following will alter the sub text in any of the bundled sign up forms. In the 'Clean Blue' template, this will change "Sign up for mailing list and receive new posts directly to your inbox." to "Sign up for our amazing mailing list today!".
`
<?php
/**
* The following example will alter the sub text in any the bundled template
* from 'Sign up for mailing list and receive new posts directly to your inbox.' to 'Sign up for our amazing mailing list today!'
*/
function yks_easy_mailchimp_custom_template_subtext() {
return 'Sign up for our amazing mailing list today!';
}
add_filter( 'yks_mc_template_sub_text' , 'yks_easy_mailchimp_custom_template_subtext' , 10 );
?>
`
<br />
**Filter Name:**
`yks_mc_template_footer_text`
**Description:**
Use this filter to alter the footer text in any of the bundled sign up templates. The footer text is the text below the form eg: "We promise never to share or sell any of your personal information."
**Example:**
The following will alter the sub text in any of the bundled sign up forms. In the 'Clean Blue' template, this will change "We promise never to share or sell any of your personal information." to "Your information will remain private at all times.".
`
<?php
/**
* The following example will alter the sub text in any the bundled template
* from 'Sign up for mailing list and receive new posts directly to your inbox.' to 'Sign up for our amazing mailing list today!'
*/
function yks_easy_mailchimp_custom_template_footer_text() {
return 'Your information will remain private at all time.';
}
add_filter( 'yks_mc_template_footer_text' , 'yks_easy_mailchimp_custom_template_footer_text' , 10 );
?>
`
<br />
**Helper Functions**
**Description:**
These functions are defined inside of the Easy MailChimp plugin and they exist to help test and view the user data that is being submitted by the user through the MailChimp form. These functions will prevent the default form functionality, so no user data will be sent to MailChimp while testing.
These functions should be used in conjunction with the `yikes_mc_get_form_data` or the `yikes_mc_get_form_data_$formID` filters. Whatever data the user has provided will be returned for viewing.
**Provided Functions**
`yks_mc_print_user_data( $form_ID, $merge_variables );` and `yks_mc_dump_user_data( $form_ID, $merge_variables );`
**How to Use**
*Print User Data*
`
<?php
/**
* This example will return all of the submitted
* user data In a nice readable format
*/
function print_user_data_from_form( $form_ID, $merge_variables ) {
if( class_exists( 'yksemeBase' ) ) {
$yikes_easy_mailchimp = new yksemeBase();
}
$yikes_easy_mailchimp->yks_mc_print_user_data( $form_ID, $merge_variables );
}
add_filter( 'yikes_mc_get_form_data' , 'print_user_data_from_form', 10, 2 );
?>
`
*Dump User Data*
`
<?php
/**
* This example will dump all of the submitted
* user data, so you can see the full array of data
* being returned
*/
function dump_user_data_from_form( $form_ID, $merge_variables ) {
if( class_exists( 'yksemeBase' ) ) {
$yikes_easy_mailchimp = new yksemeBase();
}
$yikes_easy_mailchimp->yks_mc_dump_user_data( $form_ID, $merge_variables );
}
add_filter( 'yikes_mc_get_form_data' , 'dump_user_data_from_form', 10, 2 );
?>
`
== Screenshots ==
1. YIKES Easy MailChimp General Form Settings Page
2. YIKES Easy MailChimp reCAPTCHA settings page
3. YIKES Easy MailChimp Account Activity Overview
4. YIKES Easy MailChimp Campaign Overview
5. YIKES Easy MailChimp Campaign Statistics Reports
6. *New* Yikes Easy MailChimp Redesigned Form Listing Page
7. View all subscribers of a given list, click to reveal individual subscriber info
8. Custom widget to easily add forms to sidebars and widgets
9. Form rendered on the front end of the site
10. Optional opt-in checkbox on the comment forms, easily add commenter's to your email list
11. Custom tinyMCE button allows you to easily add imported forms to pages and posts at the click of a button
12. About YIKES page
13. Admin Dashboard Widget - Account Activity ( With Live Updating )
14. *New* Form customizer, with simple UI including color pickers
== Changelog ==
= 5.4.4 - September 24th, 2015 =
* Added: Admin notice to warn about the upcoming release (major re-write)
= 5.4.3 - March 17th, 2015 =
* Fixed: Re-import form fields function not properly refreshing the page
* Fixed: Updating a MailChimp list field no longer throws an empty error
= 5.4.2 - March 10th, 2015 =
* Fixed: custom class names on input fields merged together with other class names making them un-usable.
= 5.4.1 - March 3rd, 2015 =
* Fixed: tinyMCE error thrown when saving settings page, ultimately preventing the ability to store the API key.
= 5.4 - March 2nd, 2015 =
* Enhancement: Re-bundled unaltered MailChimp API wrapper class file, and added appropriate class check to prevent conflicts with other MailChimp plugins (Gravity Forms etc.)
* Enhancement: Removed the WYSIWYG editor from the options page. This caused issues for some users who were unable to validate the MailChimp API key.
* Enhancement: Added a new setting to toggle the sending of the welcome email. Users can now disable the email all together, on a list by list basis. (checked = disabled)
* Enhancement: Prevented users from being able to update the 'EMAIL' merge variable. Added a notification with instruction on what filter to use.
* Enhancement: Replced all instances of the old class name (wpyksMCAPI) with the appropriate MailChimp class (Mailchimp)
* Enhancement: Stripped slashes and properly escaped interest group labels
= 5.3.3 - February 26th, 2015 =
* Enhancement: Added a new filter to alter field labels. Very helpful when you want to alter the default 'Email Address' field label to something else. (`yikes_mc_field_label`) (see 'filters' section in 'Other Notes')
= 5.3.2 - February 17th, 2015 =
* Fixed: Patched the error displayed below the opt-in forms when `display_yikes_mc_form_messages` is not defined.
= 5.3.1 - January 13th, 2015 =
* Enhancement: Added new filter to allow users to change which role has access to the MailChimp administration pages ( `yks-mailchimp-user-role` ) ( check readme for example )
= 5.3 - January 11th, 2015 =
* Enhancement: Added ability to move the success + error messages above or below the form based on a defined constant ( `display_yikes_mc_form_messages` [options: before/after] )
* Enhancement: Added new settings and the ability to show/hide * = required field , from the top of the forms, via the settings page
* Enhancement: Fixed incorrect error 'click here to update your profile' shown on front end on all errors
= 5.2 - December 10th, 2014 =
* New Feature: Added ability to add, edit or delete form fields directly from the WordPress dashboard
* New Feature: Added ability to add, edit or delete interest groups directly from the WordPress dashboard
* New Feature: Added "Update" link to forms when a user has previously subscribed
* New Feature: Added 'default' option to text fields ( with custom pre-defined tags : {post_id} , {post_title} , {page_url} , {blog_name} , {user_logged_in} with the ability to define your own! )
* New Feature: Added the ability to adjust required state, visibility state, merge tag and more
* New Feature: Added the ability to toggle between ssl_verifypeer true/false
* New Feature: Added an error log to help users diagnose errors happening within the plugin (and updated advanced debugging) - found on the debug options of the settings page
* Enhancement: Remove JavaScript dependency to populate place holder values
* Enhancement: Replaced Captcha with the all new No-Captcha reCaptcha API from Google
* Enhancement: Introduced all new filters ( check documentation for examples )
* Enhancement: Un-checking 'visibility' now hides the input field (instead of not generating it at all)
* Enhancement: Re-defined YKSEME_PATH for users who have the plugins folder outside of wp-content
* Enhancement: Added new classes to labels and input fields on the front end forms ( new classes yks-mc-label-field-label , yks-mc-form-row-field-label , yks-mc-input-field-row-field-label , yks-mc-input-field-label )
* Bug Fix: Re-sorting fields that had a stored custom class name didn't store properly
* Bug Fix: Wrapped bundled template text in filters
* Bug Fix: Repaired some broken filters (get_form_data_before_send)
* Bug Fix: Fixed labels on 'Manage List Forms' page and added field names to titles
* Bug Fix: Fixed path to check box images on 'Clean Blue' bundled templates
* Bug Fix: Fixed empty API key from outputting any string (confused some users)
* Other: Split main class file into multiple included files (help organize the main class file (sub-files located in /lib/inc/)
* Other: Began to build up a [Wiki](https://github.com/yikesinc/yikes-inc-easy-mailchimp-extender/wiki) on Github , for plug in installation/usage instructions
* Other: Altered single/double opt-in strings inside shortcode_form.php ([reference thread](https://wordpress.org/support/topic/code-mangling-on-script-use-in-messageserror-handling))
* Other: Removed 'Interest Group Label' option, as users can now update the name from within the plugin
= 5.1.2 - December 3rd, 2014 =
* Fix: remove type="password" from the API key input field
= 5.1.1 - November 5, 2014 =
* Fix: repair 'Opt In' default list drop down on options page
* Fix: repair errors being thrown when a commenter is added to a list
= 5.1.0.1 - November 4, 2014 =
**Updates**
* Remove update profile info link, replaced with user already subscribed error
**Fixes**
* Fix missing argument in getFrontendFormDisplay_field when using the table view
= 5.1 - November 3, 2014 =
**Updates**
* Release v5.1
* Added brand new templating framework, to allow users to create custom form templates for use with any MailChimp List
* Re-style Manage List page
* Added missing label to radio buttons inside the form
* Added missing closing parentheses on subscriber count inside view subscribers page
* Added custom color picker to easily stylize forms without writing a single line of code
* Added ability to specify a custom class names for each field of the form ( easily add custom class names to MailChimp form fields for further customization )
* Only run API Key check when a new key is entered ( not on each page load )
* Added new Welcome page with features+update notifications for users
* Security vulnerability re-patched - props @g0blinResearch for privately disclosing the potential vulnerability
* Added `yks_redirect_add_post_types` filter, to allow custom post types to be added to the redirect drop down (view [docs](https://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/other_notes/) for example)
* Added `yikes_mc_user_already_subscribed` filter to allow users to alter the message displayed to the user when they are already subscribed to a given list (view [docs](https://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/other_notes/) for example)
* Added `yikes_mc_subscriber_update_message` filter, to alter the success message when a user updates their account information for a given list (view [docs](https://wordpress.org/plugins/yikes-inc-easy-mailchimp-extender/other_notes/) for example)
* Added a new link to allow users to update profile information if previously subscribed to a given list
* Added 5 bundled templates, and 2 boilerplate files for users to use as a starting point for new templates
= 5.0.9 - October 3rd, 2014 =
**Fixes**
* Added autocomplete="false" to API input field
* Added event listener to form submission (forms can now be placed in modals/slideout menus)
= 5.0.8 - September 23, 2014 =
**Fixes**
* Band-aid fix for the -1 response returned from ajax.php
= 5.0.7 - September 19, 2014 =
**Fixes**
* Security Vulnerability patched - props @g0blinResearch for privately disclosing the issue
= 5.0.6 - August 22, 2014 =
**Fixes**
* fix bug with nonce security check when using table 'Preferred Form Layout' setting
= 5.0.5 - August 21, 2014 =
**Fixes**
- added `stripslashes()` to the following settings fields :
- Single Opt-in Confirmation Message
- Double Opt-in Confirmation Message
- Interest Group Label
- Opt-in Checkbox Text
**Updates**
- Updated readme FAQ section
= 5.0.4 - August 6, 2014 =
* Update SSL conditional in main plugin file
* Added mcrypt module check, for API encryption
* Conditionally loaded scripts and styles in admin ( prevent conflicts )
* Included NONCE security checks on form submissions ( helps prevent CSRF and other attacks )
* Added proper update task function to add missing settings to the options page ( prevents undefined variables for new settings )
* Added missing styles to post page ( added missing icon to tinyMCE button )
* Added missing styles to widget page
* Adjusted Chimp Chatter activity time formatting to return correct time based on user time zone
* New Feature : Real time updates to Account Activity ( utilizing the heartbeat API )
* New Feature : Added account activity widget to dashboard ( with live updates using heartbeat API )
* Added screenshot of admin dashboard account activity widget
= 5.0.3 =
* Re-Apply missing styles to new 'My MailChimp' Section
= 5.0.2 =
* Remove extra spacing in provided short code, which caused parsing issues