Simple Subscription Popup
Documentation
Table of Content
- Item Name : Simple Subscription Popup-jQuery Email Signup Form
- Minimum Required : jQuery 1.10.2
- Author by : Pantherius
- Support via Email : Contact Link
Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here.
With this attention-grabber jQuery Plugin, you can collect your visitor's email address on your website. It has a lot of optional customization options, but you can setup simply in minutes. Using the latest CSS3 animations with AJAX validation the Signup Form will build your email list effectively in no time. You can use it with MailChimp, but if you have any other email database manager, you can use it with that as well. In that case, the plugin will send you a message about every subscription with the user's email address, therefore you can easily add it to your own email list manager. You can also use this function as a signup notification.
File Structure #back to top
You will see 3 folders in the files (inside the ZIP) directory: css, js, php
These assets are responsible for the MailChimp connection and email notifications. The plugin automatically use these files, therefore you don't need to include any of them directly to your code. Find all included PHP files under the files/php folder:
- - MailChimp.php - Manage the connection between the plugin and the MailChimp API
- - handler.php - Handle the form submissions, send email notification and connect to MailChimp
These are the primary CSS files used for general front-end styling. Use these to customize your theme even further. Find all included CSS code under files/css folder
- - simplesubscriptionpopup.css - Frontend style of the Subscription Form
These are the core files of the plugin, you may also find the minified and the unminified version of the main JS files. If you decided to modify it, you have to use the unminified version. Find all included JavaScript codes under the files/js folder
- - ssp.min.js - Minified version of the core JavaScipt file
- - simplesubscriptionpopup.js - Original (unminified) version of the core file
Install Guide #back to top
Copy all folders ( css, js, images ) from the files directory to your server's document root folder, next to your index.html file.
Integration
Open your index.html file and copy the following lines between the <head> and </head> elements:
If you have already included jQuery, then you can ignore the second line above. Without jQuery, you have to add the following lines (after the already implemented jQuery file):
Again, these lines must be included between the <head> and </head> elements of your website. In some cases, you can also place the JS files at the bottom of your file before the </body> closure tag.
Please note: If you have already included jQuery in your index.html, you don't need to include it once again. The order is very important. jQuery included first, then the plugin file (ssp.min), finally the initialization with parameters.
Basic Initialization
You have integrated the required files, so you need to start the plugin now and customize the options to fit to your needs. Place the following default configuration after the included JS files in the <head> tag:
In some cases when you use it with other jQuery plugins, you have to use the $ sign in the document ready section instead of the jQuery command, like this:
In this state of the integration, the plugin needs to work when you call your index.html in your browser. Read more about the customization options in the next sections.
HTML Markup
The signup form doesn't need any HTML markup, but in some cases, you may assign the form to a specified DIV element. Place the DIV into your HTML code with a unique ID or CLASS:
The DIV must contains the simplesignuppro class to apply the required CSS styles. Then you can initialize the form directly to the inserted DIV element:
With this method, you can embed the form into the content instead of the popup display style. Just specify the embed parameter with true value:
Customization #back to top
Initialization with Full Parameters
The customization is simple, you can pass the parameters during the initialization. Use the Popup Form Builder (example folder in your downloaded ZIP) to get the values (color, font-size, etc.) then use it like this way:
Here are the details for each parameters:
mode (mailchimp, mail or mixed): If you using mailchimp, it will connect to your MailChimp account, with mail option, you will get a mail notification about each signup. (You need to define your email address in PHP/handler.php). With mixed mode, MailChimp and also Notification mode will be active.
animtime (in seconds): Specify the time of the animation for the popup
animation (slide, rotatein, perspectivein, scalein): You can set the incoming and outgoing animation type.
autoopen (true or false): With true, the signup form will appears automatically, delay depends on the timer parameter.
customfields (object): Example for custom fields:
'customfields': '[{"id":"NAME","name":"Name","required":"false","type":"text","warning":"dfff","minlength":"3"},{"id":"PHONE","name":"Phone","required":"false","type":"text","warning":"","minlength":""},{"id":"COUNTRY","name":"Country","required":"false","type":"text","warning":"","minlength":""},{"id":"CHECKBOX","name":"I accept the term of conditions:agreed",{"id":"TAREA","name":"Description","required":"true","type":"textarea","warning":"fill out","minlength":"0"},{"id":"RADIO","name":"Female:female,Male:male,Not Specified:na","required":"true","type":"radio"},{"id":"SELECT","name":"Select Fruits,Apple:applevalue,Orange:orangevalue,Banana:banana,Lemon:lemon","required":"true","type":"select"},{"id":"NAME2","name":"Name2","required":"false","type":"text","warning":"","minlength":""},{"id":"NAME3","name":"Name3","required":"false","type":"text","warning":"","minlength":""}]',
id is a string that you can define in MailChimp. The plugin will pass the parameters and MailChimp will save the values in your List. The name parameter will be visible for the visitors as placeholder in the input field. You can also set the field as mandatory, then it is recommended to define a warning text. These are the currently available custom field types:
- text
- textarea
- radio button
- checkbox
- select box
Select box: The first parameter will be the title (eg.: Select from the list), then you have to list the title:value pairs. Pay attention to use valid string as values. (space, special characters are not allowed).
Wrong example:
'customfields': '[{"id":"SELECT","name":"Select Fruits,Apple:apPle value,Orange:orangevalue,Banana:banana,Lemon:lemon","required":"true","type":"select"}]',
Including space to applevalue (apple value) is invalid, also don't use capital letters as a value.
Correct example:
'customfields': '[{"id":"SELECT","name":"Select Fruits,Apple:applevalue,Orange:orangevalue,Banana:banana,Lemon:lemon","required":"true","type":"select"}]',
facebook_appid (integer): You can find it on Facebook after you created your Facebook Application. Go to this link to create your app: https://developers.facebook.com/apps
googleplus_clientid (string): Register on Google Plus, enable Google Plus API and get your Client ID on this link: https://console.developers.google.com/
googleplus_apikey (string): You can also get your API Key on the link described above.
customfieldsmargin (in pixels): The vertical distance of the custom fields from each other.
bgcolor, buttonbgcolor, closecolor, color, contentcolor (rgb, rgba or hex color code): Allows to set custom color for the background, the signup button, the close icon, title and for the content.
fontsize, contentfontsize, closefontsize (numbers in px or in pt or in em): You can define the size of the title, content and the close icon.
fontfamily, contentfontfamily (Google Font Family): Visit http://google.com/fonts and choose the one you like and pass the name with this parameter to set fancy font family for the title and the content. Quite simple.
openwithlink (true or false): With false, you can disable the option to open the form with clicking on a specified link (with opensspopup-formid classname).
bottomtitle (string): Add bottom-line text with smaller font size.
inputborderradius (in pixels): The border radius of the input fields.
once_per_filled (true or false): It won't display the popup for the users who already filled out. (using cookies)
filled_cookie_days (integer): Days to do not display the form again for users, who already signed up.
closewithlayer (true or false): Enable the option to close the form by clicking on the transparent background (you can use it only with setting lock: true).
preset (predefined style name - string): You can set predefined styles. See the actual preset list below:
default, business, baby, dating, technology, financeThe presets doesn't contains images, just the color and font settings. You can check the examples to find out how can you use images in title or in the content like on the demo page.
timer (in milliseconds): Configure the delay time to display the form.
fontweight, contentweight (normal or bold): This is the font weight attribute of title and content.
title, text (string): With this parameter, you can set the text of the title and the content.
invalid_address, signup_success (string): The callback message for invalid email address and the successful signup.
vspace, hspace (number in px): If you using the popup on any side of the screen, you can specify the vertical and horizontal distance relative to the side of the window in pixels.
position (lefttop,leftcenter,leftbottom,centertop,centercenter,centerbottom,righttop,rightcenter,rightbottom): The position of the Subscription Form after displayed.
borderradius (number in px): Set the radius of the popup form's border.
openbottom (false or number in percentage): If you set a number in percentage (like: 90%) it will open automatically when the user reach that position while scrolling down the website. You can disable this feauture with false value.
double_optin (MailChimp attribute: true or false): The potential subscriber will get an email with a link to confirm their subscription. If they don't click this link, they won't be added to your list. To disable this confirmation, set false to this attribute.
update_existing (MailChimp attribute: true or false): Existing subscribers will be updated with true value.
mailchimp_listid (MailChimp listid or false): Option to pass your MailChimp List ID during the initialization. This gives an ability to use multiple lists on different pages.
once_per_user (true or false): Track users to prevent reopen signup form for the same users. This setting only works with autoopen and openbottom options.
cookie_days (integer - cookie lifetime in days): Specify the number of days to prevents auto open the signup form for each user.
lock (boolean - true or false): Lock the screen with a transparent background. Clicks on this layer will close the popup.
hideclose (boolean - true or false): Hide the close button of the popup, you can use it when you lock the screen.
trackform (boolean - true or false): If you have Google Analytics included on your website, you can track how many times displayed the signup form. The plugin automatically store an event with name Simple Subscription in your Google Analytics.
media (empty or YouTube video ID or image URL): Use this parameter to include YouTube Video or Image to the signup form.
mediawidth (empty or size in pixels or size in percentage): Specify the YouTube Video or image width.
mediaheight (empty or size in pixels or size in percentage): Specify the YouTube Video or image height.
mediapos (integer - number): This number set the video or image position.
YouTube Video:
- 1 - Video placed above the Content
- 2 - Video placed below the Content
- 3 - Video placed below the Title
- 4 - Video used as background
Image:
- 1 - Image placed above the Content
- 2 - Image placed below the Content
- 3 - Image placed below the Title
- 4 - Image used as background (cover style)
- 5 - Image used as background (content style)
yaplay (boolean - true or false): Enable auto play if you using YouTube video ID in the media parameter.
yinfo (boolean - true or false): Set true to hide YouTube info in the video.
yloop (boolean - true or false):With true value the video will repeat itself constantly.
ycontrols (boolean - true or false): Set true to hide YouTube controls in the video.
imgrepeat (boolean - true or false): Repeat image if you using it as background. ( mediapos: 4 or mediapos: 5 )
imgopacity (decimal - between 0 and 1): Specify the opacity the media image. (only with media: imageurl.jgp)
embed (boolean - true or false): Embed the signup form instead of the popup style.
How to add images
Specify your image URL in the media parameter during the initialization stage. These parameters helps you to customize the display:
Read more about these parameters in the customization section.
Adding images with simple HTML
Alternatively, the plugin also accepts HTML codes, therefore you can easily add your own image with HTML code to the header, content and bottom areas:
The example above add the image to the title element, that will displayed at the top of the signup form. Let's see how it will look like, when we want to add image to the content with HTML:
Finally, you can also add image to the footer, that will show the image at the bottom of the form:
How to add YouTube video
Specify your YouTube video ID in the media parameter during the initialization stage. These parameters helps you to customize the display:
jQuery( document ).ready( function() {
jQuery( 'body' ).sspopup({
media: "gRgZnZz_Tj4",
mediawidth: "480px",
mediaheight: "270px",
mediapos: 4,
yaplay: true,
yinfo: false,
yloop: true,
ycontrols: true,
});
});
Read more about these parameters in the customization section.
Adding YouTube Video with simple HTML
Alternatively, you can add YouTube video to the title or content part via HTML code as well. The process is the same as it mentioned before with the images, but you have to use iframe:
Sample 1
In this example, we set the screen to lock with force the users to sign up and display the form only once per user. We also specify the rotatein animation type.
Sample 2
To update our previous form, we add some styles to the signup form, like this:
In this example, we added a background color to the overall form, set the font color of the texts and changed the subscribe button background and font color.
MailChimp Integration #back to top
Visit http://mailchimp.com and click on the Sign Up Free button on the right-top of the screen. Fill with your informations then activate your registration if needed and login on: https://login.mailchimp.com
You'll see something like this:
Select Lists - #back to top
After a successful login, you will be redirected to your Dashboard, click on the Lists menu.
Select Settings - #back to top
Click on the List name & Defaults in the Settings menu and you will see your list ID.
Copy List ID - #back to top
You have to use this ID to connect Simple Subscription Popup to MailChimp. Open the handler.php in the PHP folder and search for this line:
define('_MAILCHIMP_LISTID','b9c0fde42d');
Replace b9c0fde42 to your own list ID.
Select API Keys - #back to top
We almost finished, visit your Account page on this link: https://us3.admin.mailchimp.com/account/ and click on the Extras followed by the API Keys menu. Scroll down and click on the Create A Key button.
Copy your API Key to the handler.php replaced with the ba7a2f8f9dc267557de6a3fb241471c9-us3 string:
define( '_MAILCHIMP_APIKEY', 'ba7a2f8f9dc267557de6a3fb241471c9-us3' );
When you initialize the plugin, you can enable the MailChimp Support with the following parameter:
If you also would like to get email notifications on each signups, you can choose the mixed mode:
In this case, don't forget to add your email address to handler.php in the PHP folder ( replace your@email.com to your own email address ):
define( '_EMAIL', 'your@email.com' );
F.A.Q. #back to top
You can use 'once_per_user': true parameter, during the initialization:
If you would like to display it once for users who already signed up, then add:
In the most cases, it caused by a duplicated jQuery file. If your website already use jQuery, you don’t need to include it again, because it will be included twice. Check your website and look for jquery.js or jquery[version number].js, then change the source to use only one.
It is also very important to include the jQuery file BEFORE you add the plugin file, so it has to be:
//first: jQuery file //second: Plugin file
Support#back to top
- * Answer for questions related with the plugin
- * Answering technical questions about item’s features
- * Assistance with reported bugs and issues
- * Help with included 3rd party assets
- * Customization Services
- * Installation Services
Please remember you purchased a very affordable plugin and you don't have to pay for a full-time web design agency for the developing. Occasionally, I will help with small tweaks, but these requests will be put on a lower priority due to their nature. Support is also 100% optional and I provide it for your convenience, so please be patient, polite and respectful.
Please visit my profile page or ask question in the plugin's the comments section
- * Make sure your question is a valid Plugin Issue and not a customization request.
- * Make sure you have read through the documentation before asking support on how to accomplish a task.
- * Make sure you double checked the plugin's FAQs.
- * Try disabling the other active plugins to make sure there isn't a conflict with any other plugins. If you found a conflict this way, you can let me know.
- * If you have customized your plugin and now have an issue, back-track to make sure you didn't make a mistake. If you have made changes and can't find the issue, please provide me with your changelog.
- * Almost 80% of the time we find that the solution to people's issues can be solved with a simple "Google Search". You might want to try that before seeking support. You might be able to fix the issue yourself much quicker than I can respond to your request.
- * Make sure to state the name of the plugin you are having issues with when requesting support via CodeCanyon.
Version History ( Changelog ) #back to top
You can find the version history ( changelog.txt ) file in the downloaded plugin ZIP file or you can check the changelog on plugin's page here.
If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. With more general question relating to the plugins on CodeCanyon or with this plugin, you might consider visiting the comment section of this plugin, maybe somebody also faced with the same question.
Changelog
----------------------------------------------------------------------------------------- Version 1.6.6 ----------------------------------------------------------------------------------------- - added checkbox support to custom fields ----------------------------------------------------------------------------------------- Version 1.6.5 ----------------------------------------------------------------------------------------- - updated MailChimp API to V3 - send_welcome parameter deprecated (you can set it in your MailChimp List) - replace_interest parameter deprecated - minor improvements on email sending ----------------------------------------------------------------------------------------- Version 1.6.4 ----------------------------------------------------------------------------------------- - fixed http protocol issue ----------------------------------------------------------------------------------------- Version 1.6.3 ----------------------------------------------------------------------------------------- - reconstructed documentation ----------------------------------------------------------------------------------------- Version 1.6.2 ----------------------------------------------------------------------------------------- - fixed Facebook Login doesn't provide email issue in rare cases ----------------------------------------------------------------------------------------- Version 1.6.1 ----------------------------------------------------------------------------------------- - fixed minor parameter issue in code generator ----------------------------------------------------------------------------------------- Version 1.6 ----------------------------------------------------------------------------------------- - added element animations - added radio button, textarea, select box custom fields - added option to use multiple instances - option to set custom width - added embed mode with or without animation - added YouTube video background option - added Image implementation options - improved built-in code generator - improved code - updated documentation - fixed minor animation bug in Internet Explorer - improved email sendings - updated documentation - added error messages for exceptions - fixed custom fields issue related with the close button - fixed minor bug with cookies ----------------------------------------------------------------------------------------- Version 1.5 ----------------------------------------------------------------------------------------- - minor bugfix for the Form Builder - added code generator to the Visual Form Builder - added YouTube video support - added automatic height detection, no longer needs to specify the overall height when you added images to the signup form - updated documentation - fixed some minor issues - fixed minor FireFox bug - minor code optimization - minor changes in the documentation ----------------------------------------------------------------------------------------- Version 1.4 ----------------------------------------------------------------------------------------- - added more animation types (slide, rotate, perspective, scale) - option to add unlimited custom fields - added signup with Facebook - added signup with Google Plus - added option to set margin for custom fields - added option to disable open with link method - added option to display footer text - added option to set border radius - added option to hide signup form for already signed up users - added option to enable or disable form closing with clicking on the background layer - opacity setting deprecated - updated documentation ----------------------------------------------------------------------------------------- Version 1.3 ----------------------------------------------------------------------------------------- - added option to lock the screen with ability to close the popup clicking on the transparent layer - added option to hide the popup's close button (usable with lock the screen setting) - optimized form elements to avoid conflicts with other forms of the website ----------------------------------------------------------------------------------------- Version 1.2 ----------------------------------------------------------------------------------------- - added option to change Subscribe button and the email input placeholder texts - added option to specify the inbuilt PHP email handler path ----------------------------------------------------------------------------------------- Version 1.1 ----------------------------------------------------------------------------------------- - added option to pass MailChimp List id during initialization (multiple lists on different pages) - prevents reopen form after signup or closed by the user with autoopen option - added cookie tracking to prevents auto open signup form for the same users (optional) - updated documentation ----------------------------------------------------------------------------------------- Version 1.1 ----------------------------------------------------------------------------------------- - added text support to images - added option to set Google Fonts on texts - ability to set the position, color, font size and font family for the image texts - updated example and documentation
Credits #back to top
Thanks for the following resources:
- - MailChimp API
- - MailChimp
- - jQuery