unipromo modal plugin

The social campaign jQuery plugin

Include the files

Paste the following code into the page head.
		<script type='text/javascript' src='jquery.min.js'/>
		<script type='text/javascript' src='jquery.pubsub.js'/>

		<link rel='stylesheet' type='text/css' href='unipromo.css'/>
		<script type='text/javascript' src='jquery.unipromo-1.0.min.js'/>

Create a Facebook Application

In order to function properly, the plugin needs a Facebook Application key. Without one, the login detection will not work in Internet Explorer and Opera.

Tim Ware wrote a very helpful tutorial about creating an application.

Once you've got your key, paste this code at the end of your page, before the body tag closes.

		<script>jQuery.fn.socialpost({ apikey : FACEBOOK_APP_ID });</script>

Plugin options

The following options are available for each modal on the screen and can be changed either individually or globally( by using jQuery ).

Option name Default value Possible values Information
name an empty string String A string representing the id of the main element, used for namespacing events and timing functions
title false String A string representing the title
iframe false URL Use the video URL from Youtube or Vimeo for embedding, or the url of the page you want to frame
buttons [] Array of button objects Reserved for internal use, add buttons using the 'addButton' method
theme default For now only default is available the current theme
scheme light light or dark Use match with the luminosity of the website
type custom error, alert, success or info Represents the styling of the modal
background transparent any CSS background declaration Images can be used
delay 0 Number The number of seconds after which the modal should appear
every -1 Number The number of seconds after the modal should be displayed again to the same user, this option uses cookies and requires a name to be specified
subscribe an empty string conditional classes Represents a condition to open the modal, see Conditional Classes
redirect false URL Redirects to the specified URL if the subscribe condition was true
width 640 Number The desired width, resizing will apply if the modal is bigger than the screen
height 360 Number Default height
margin 25 Number The minimum space between the modal and the window both horizontally and vertically
exit true 0 or 1 The exit icon in the corner of the modal
cancelable true 0 or 1 The ability to close by clicking anywhere outside the modal

All of the above options can be modified in HTML by prefixing them with 'data-'( to be HTML5 compliant ) and used as attributtes of the main element. Note that the changes done in the script overwrite these kind of declarations.

Basic usage

This section will cover the basic usage including both HTML and jQuery examples. To integrate with other plugins you should use jQuery, but for itself the plugin is perfectly functional by writing only HTML.

The main element

The following element should be used to open an empty modal with no content.
		<div class='unipromo-modal'></div>

Adding a title and some content

Let's add a title, and change the color scheme to dark and decrease the width. Now our element looks like this.

	$('<div>Why are you testing this, scroll down and do some fun stuff with jQuery.</div>').unipromo({ width: 240, title: 'This is a dark modal', scheme: 'dark' })
		<div class='unipromo-modal' data-width='240' data-title='This is a dark modal' data-scheme='dark'>
			<div class='unipromo-content'>
				Why are you testing this, scroll down and do some fun stuff with jQuery.

Buttons maybe?

Buttons consist of list and anchor tags and have some properties of themselves.

Button option Default Other values Description
href undefined URL Applies to the anchor tag
close 1 0 or 1 Closes the modal when the button is clicked
class empty string String A class for custom styling, note that it is applied to the list element
text empty string String The button text, useful when creating buttons via jQuery
trigger false String Will trigger the event, subscribe using $.subscribe( trigger_value, function(){} )

In this example will open a license agreement, where the user is required to accept the terms. Lets see how we can add some buttons to a new modal element.

		<div class='unipromo-modal' data-exit='0' data-cancelable='0' data-title='License Agreement' data-width='480' data-background='rgba(0,0,0,0.3)'>
			<div class='unipromo-content'>
				You must accept the following conditions: 
				Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
				Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?
			<ul class='unipromo-buttons'>
				<li class='custom_styling'>
					<a href='#accepted'>Accept</a>
					<a data-close='0'>Decline</a>

Even if the Decline button isn't closing the modal, the user can still close the modal. In this particular case we want to remove this behaviour. By looking at the available options we see that adding data-exit='0' and data-cancelable='0' to the main element solves the problem.


To open a image, use it as the content adding the unipromo-content class to it.
		<div class='unipromo-modal' data-background='rgba(0,0,0,0.7)'>
			<img class='unipromo-content' src='example_4.jpg'></img>

Iframe and videos

Use data-iframe attribute to set an url. If it's an Youtube or Vimeo video it will be embedded, otherwise iframed. All parameters like autoplay and loop are supported for Youtube videos.

		<div class='unipromo-modal' data-title='Sasquatch festival' data-scheme='dark' data-height='500' data-width='480' data-iframe='http://www.sasquatchfestival.com'></div>

Instead of the ususal music video, let's do some real-world example.

		<div class='unipromo-modal' data-title='Promote your mobile app' data-scheme='dark' data-iframe='http://www.youtube.com/watch?feature=player_embedded&v=Lep_DSmSRwE&autoplay=1'>
			<ul class='unipromo-buttons'>
				<li><a href='http://facebook.com/home'>Install now</a></li>
				<li><a>Not now</a></li>

Page example

The following code was used on this page, though the name option has been ommitted.
	// Facebook SDK
	(function(d,s,id){var js, fjs = d.getElementsByTagName(s)[0];if (d.getElementById(id)) return;js = d.createElement(s); js.id = id;js.src = "http://connect.facebook.net/en_US/all.js";fjs.parentNode.insertBefore(js, fjs);}(document, 'script', 'facebook-jssdk'));$(document).ready(function(){})
	// Twitter API
	!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');
	// Google API
	(function(){var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;po.src = 'https://apis.google.com/js/plusone.js';var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po,s);})();

	// Modal script
	(function( $ ){
		$.subscribe( 'login_status_detected', function( event, status ){
			var buttons = {
				fb : { m : 'Like this page', b : '<div class="fb-like" data-send="false" data-layout="button_count" data-show-faces="true"></div>' },
				tw : { m : 'Tweet it', b : '<a href="https://twitter.com/share" class="twitter-share-button">Tweet</a>' },
				gp : { m : '+1 this', b : '<div class="g-plusone" data-size="medium"></div>' }
			for( var i in buttons ) 
				if( status[ 'on_' + i ] )
					$( '<div><h1 style="font-size:30px;margin:6px 0">' + buttons[ i ].m + '</h1><hr style="margin:12px 0;border-color:#ddd;border-width:1px 0 0 0"/>' + buttons[ i ].b + ' </div>' ).unipromo({
						width : 350, 
						background : 'rgba(0,0,0,0.25)',
						cancelable : false,
						name : 'promo_' + i,
						every : 0

	})( jQuery );

More examples


Methods and events

Init method

The use the init method to change the defaults globally like in the example below. Using it with an empty collection will achieve the same result so make sure your selector matches at least one element.

		$.fn.unipromo({ new_default : value });

Called with a non-empty collection, it uses each element as the content of the modal and returns the modal collection. Be careful with chaining. If you want to open a newly created box, add 'unipromo-modal' class to it and then call the init method.

Open method

This method takes a sigle boolean parameter, to ignore or not the subscribe condition. Default is to ignore. It skips over delay.

		// open the modal now but check the condition
		$( '#mymodal' ).unipromo( 'open', false )

Close method

This method closes the selected modal or removes it from the stack. An empty collection matches the current opened modal.

		// closes the current modal
		$.fn.unipromo( 'close' );
		// removes #mymodal from the stack or closes it
		$( '#mymodal' ).unipromo( 'close' );

AddButton method

This method is used to add buttons to newly created modals. Can be passed multiple object items or a sigle button declaration. The parameters are in order:

Parameter Default value Description
text an empty string Required. The button text
_href false Optional. false or URL
_class an empty string Optional. A classname for styling, applied to the li element
trigger A void function Optional. Function or a string( representing an event name ) to be called or published
close true Optional. Boolean, if true closes the modal on click
		// creates a new modal
		var modal = $( '#mymodal' ).unipromo({ data-title : 'This modal will have no buttons' })
		// adds a sigle button 
		modal.unipromo( 'addButton', 'Until Now', false );
		// adds another 2 buttons
			{ text: 'First button', _class : 'firstbtn', _href : 'http://randomsite.com' },
			{ text: 'Second Button', close : false }
	<!-- include this within your main element -->
	<ul class='unipromo-buttons'>
		<li><a data-close='0'>Until Now</a></li>
		<li class='firstbtn'><a href='http://randomsite.com'>First button</a></li>
		<li><a data-close='0'>Second button</a></li>


The standard events are namespaced, so if you give a name to your modal you need to subscribe to that namespaced event. See the diagram below.

Event name Parameters Description
modal_open Event, Modal Fired after opening animation started
modal_cancel Event, Modal Fired when user clicks outside the modal
modal_exit Event, Modal Fires when the x button is being pressed
modal_button Event, Button Element, Modal Fired when a button is clicked
The subscribed function always receives the event object as its first parameter.

Advanced examples

While the simple examples are quite powerful, sometimes we need more complex functionality. That's where features like delay and redirect come into play.

The plugin uses a stack to resolve conflicting modals. A conflict appears when a modal should open over another. In this scenario, the latter one will open when the first one closes.

Console and events subscription

All of the modal events are subscribe capable using $.subscribe. For targeting a particular modal, give the main element an id and then the plugin will trigger the particular namespaced event. If the event is modal_exit and the id attributte is 'myfirst' the event modal_exit.myfirst will be triggered.

Beware of how jQuery subcribes to events. An event like event.namespace will subscribe both to event and to event.namespace. Check the returned event object for the proper namespace.

Conditional classes

Social features are a must for todays websites, where efficiency is the primary goal.

Let's say we want to increase our Twitter followers without spamming all the people which are visiting our site. Because Twitter users are pretty rare these days, it's very inneficient to show the campaign to all users. So it could be shown only to those who are logged into Twitter, making your website less spammy.

After all, what's the change that a visitor signs into Twitter just to tweet the link? And if he does that, why is he even in need for a campaign?

Take a look at the conditionals below, they are very easy to remember and use.

Class name Condition
on True if the user is logged in at least one of the social networks
off True if the user is not logged into any of the sites
on_fb True if the user is logged into Facebook
on_tw True if logged into Twitter
on_gp True if logged into Google Plus
off_fb True if the user isn't currently using Facebook
off_tw True if the user isn't logged into Twitter
off_gp True if not logged into Google Plus

Conditional classes are normal classes that can be added to an element to target particular groups of visitors. If all of those clases are true, the element will show. For example let's target a Twitter user by showing him a link into the text.

		<span class='unipromo on_tw'>While all the users might eventually buy 
		something from our site, our Twitter followers showed a remarcable interest 
		for this <a href='#'>product</a></span>

Upgrading modals

The same classes can be applied to modals. Just use the subscribe option with the condition you want and the plugin will do the rest. An empty condition will always be true.

Note that this example uses some CSS.

			width: 100%;
			position: relative;
			display: block;
			text-shadow:0 2px 2px rgba(0,0,0,0.5)		
		<script>(function(d, s, id){var js, fjs = d.getElementsByTagName(s)[0];if(d.getElementById(id)) return;js = d.createElement(s); js.id = id;js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";fjs.parentNode.insertBefore(js, fjs);}(document,'script','facebook-jssdk'));</script>
		<div id='pizza_offer' class='unipromo-modal' data-every='0' data-title='Become a fan' data-width='650' data-scheme='dark' data-background='rgba(0,0,0,0.45)'>
			<div class='unipromo-content' style='padding:0'>
				<div class='pizza_box'>
					<img class='pizza_img' src='res/example_8.jpg'></img>
					<h2 class='pizza_headline' style=''>Like to win a free pizza</h2>
					<div class='pizza_like fb-like' data-href='http://freepizza.com' data-send="false" data-layout="button_count" data-show-faces="false"></div>

The like button in the right corner might not work locally.

Timing functions

The plugin offers the ability to show a modal only once per user. Use the 'every' option set to 0 or to any number of seconds after which it can be showed again to the same user. This requires the element to have an id and uses cookies to remember such data.

The following button will open a modal only once every 10 seconds.

		<div id='timed_example' class='unipromo-modal' data-every='10' data-width='300' data-type='alert' data-background='rgba(0,0,0,0.7)' data-title='Timed modal'>
			<div class='unipromo-content'>You have to wait another 10 seconds before you open me again</div>

The timing functions will prove very useful when you are creating a limited campaign from which an visitor can benefit only once. Setting 'every' to 0 will show the option only once per user.

You can use the delay option to wait a certain amount of time before showing a modal.

Event tracking with Google Analytics

Even if the plugin doesn't offer this option off the box, it is very easy to implement with basic javascript knowledge and offers an easy way to visualize your results.

Note that the pizza example above already has an id and the every attributte set to zero.

	// default facebook initialization
	window.fbAsyncInit = function(){
		// subscribe to the like event
		FB.Event.subscribe( 'edge.create', function( url ) {
			// if it is the right url, log the event and close the modal
			if( url == 'http://freepizza.com' ){
				_gaq.push([ 'trackEvent', 'Campaigns', 'Like', 'Pizza Offer' ])
				$( '#pizza_offer' ).unipromo( 'close' );
	// subscribe to the modal exit and close event to log the non-liking users
	$.subscribe( 'modal_exit.pizza_offer modal_cancel.pizza_offer', function( e ){
		// track the action as Refused
		if( e.namespace == 'pizza_offer' )	
			_gaq.push([ 'trackEvent', 'Campaigns', 'Refused', 'Pizza offer' ]);



Login status

  • Facebook
  • Twitter
  • Google Plus
Log into any of the social networks, refresh the page and see what it happens.