jQuery Impromptu

About

jQuery Impromptu is an extension to help provide a more pleasant way to spontaneously prompt a user for input. More or less this is a great replacement for an alert, prompt, and confirm. Not only does it replace these but it also allows for creating forms within these controls. This is not intended to be a modal replacement, just a quick tool to prompt user input in a fashionable way.

Get Started

Highly Recommended

Subscribe to my newsletter and follow me @practicalweb.

Get the ebook Impromptu From I to U. Learn about advanced functionality of Impromptu including states, forms, tours, theming, and more!

buy PDF + Code

buy PDF Only

Donation

Try my new app to keep you informed of your car's financing status and value.

Has Impromptu been helpful to you?

Download

Version

Version 4.2

Last updated on 01/25/2013

jQuery Impromptu is currently available for use in all personal or commercial projects under both MIT and GPL licenses. This means that you can choose the license that best suits your project, and use it accordingly.

Options

$.prompt( msg , options )

msg

The message can either be an html string, or an object of "states". Each state has the following properties:

html: A string of html or text for the content
buttons: An object containing the text and values of each button the user may click. Default: { Ok : true }
focus: Index of the button to focus(0,1,2..). Default: 0
submit: A function to be called when the prompt is submitted. Default: function(event, value, message, formVals){} Return false or event.preventDefault() to keep the prompt open. Event object also has properties event.state and event.stateName.

var temp = {
	state0: {
		html:'test 1...',
		buttons: { Cancel: false, Next: true },
		focus: 1,
		position: { container: '#elId', x: -300, y: -45, width: 250, arrow: 'rm' },
		submit:function(e,v,m,f){ }
	},
	state1: {
		html:'test 2..',
		buttons: { Back: -1, Exit: 0, Next: 1 },
		focus: 2,
		submit:function(e,v,m,f){ }
	}
};

If a string is passed as the message in place of a state, buttons, focus, and submit will be substituted from the options below.

options

buttons: An object containing the text and values of each button the user may click. Default: { Ok : true }
classes: Add class names to the outer Impromptu shell (parent of the fade and prompt) Default: ''
close: A function to be called when the prompt is closed and just before being removed from the DOM. Default: function(event[, value, message, formVals]){} Last three paremeters available only when button was clicked.
focus: Index of the button to focus(0,1,2..). Default: 0
loaded: A function to be called when the prompt is fully loaded Default: function(event){}
opacity: The prefered opacity of the transparent layer placed over the container. Default: 0.6
overlayspeed: The prefered speed of the fadeIn and fadeOut of the overlay ("slow", "fast", number) Default: "slow"
persistent: If the prompt should close when the fade is clicked (true doesn't close). Default: true
prefix: A prefix to be used for all css classes and html object id's. Default: 'jqi'
promptspeed: The prefered opacity of the showing of the prompt ("slow", "fast", number). Default: "fast"
show: Name of the jQuery method to animate the entrance of the prompt ("show","fadeIn","slideDown"). Default: "fadeIn"
statechanging: A function to be called when a state is about to change. Default: function(event, fromStatename, toStateName){} Return false or event.preventDefault() to prevent the state change.
statechanged: A function to be called when a state has changed. Default: function(event, toStateName){}
submit: See state submit event above.
timeout: The number of milliseconds until the prompt automatically closes. Default: 0
top: Distance from the top of the screen the prompt will be Default: 15%
useiframe: Will use an iframe for the overlay in IE6 to cover up <select>. Default: false
zIndex: zIndex to apply to the prompt. Default: 999

Methods

jQuery.prompt.setDefaults(options)

Sets the defaults for prompts.

jQuery.prompt.setDefaults({
	prefix: 'myPrompt',
	show: 'slideDown'
});

jQuery.prompt.setStateDefaults(options)

Sets the defaults for states.

jQuery.prompt.setStateDefaults({
	buttons: { Ok:true, Cancel:false },
	focus: 1
});

jQuery.prompt.getCurrentState()

Returns a jquery object of the current visible state.

jQuery.prompt.getCurrentStateName()

Returns a string current visible state's name.

jQuery.prompt.getStateContent(stateName)

Returns a jquery object of the state, so you can update the content within it.

jQuery.prompt.goToState(stateName, callback)

Transitions to the specified state. Callback represents a statechanged event.

jQuery.prompt.nextState(callback)

Transitions to the next state. Callback represents a statechanged event.

jQuery.prompt.prevState(callback)

Transitions to the previous state. Callback represents a statechanged event.

jQuery.prompt.close()

Closes the prompt.

Events

If you like to bind events manually you can do so with the following:

promptloaded

Same as loaded option. Scope is the entire prompt and fade container.

var myPrompt = jQuery.prompt(/*...*/);
myPrompt.bind('promptloaded', function(e){});

promptsubmit

Same as submit option. Scope is the state element. These events are per state, so you must attach it directly to a state.

var myPrompt = jQuery.prompt(/*...*/);
$.prompt.getStateContent('state2')
	.bind('promptsubmit', function(e,v,m,f){});

promptclose

Same as close option. Scope is entire prompt and fade container

promptstatechanging

Same as statechangin option. Scope is the entire prompt and fade container. This fires before the state changes, so you may return false or use e.preventDefault() prevent the state change.

promptstatechanged

Same as statechanged option. Scope is the entire prompt and fade container. This fires after the state has successfully changed.

Examples

Basics

A prompt in the simplest of fashion.

$.prompt("Hello World!");

Lets add some buttons and a title.

$.prompt("Proceeding may be good for your site..", {
	title: "Are you Ready?",
	buttons: { "Yes, I'm Ready": true, "No, Lets Wait": false }
});

Use the submit function to get the answer.

$.prompt("Open your javascript console to see the answer.", {
	title: "Are you Ready?",
	buttons: { "Yes, I'm Ready": true, "No, Lets Wait": false },
	submit: function(e,v,m,f){
		// use e.preventDefault() to prevent closing when needed or return false. 
		// e.preventDefault(); 

		console.log("Value clicked was: "+ v);
	}
});

States

To use states pass in a collection (array or object) of objects with common properties (html, buttons, focus, submit, position..).

var statesdemo = {
	state0: {
		html:'test 1.<br />test 1..<br />test 1...',
		buttons: { Cancel: false, Next: true },
		focus: 1,
		submit:function(e,v,m,f){ 
			if(v){
				e.preventDefault();
				$.prompt.goToState('state1');
			}
			return false; 
		}
	},
	state1: {
		html:'test 2',
		buttons: { Back: -1, Exit: 0 },
		focus: 1,
		submit:function(e,v,m,f){ 
			if(v==0) $.prompt.close()
			else if(v==-1)
				$.prompt.goToState('state0');
			e.preventDefault();
		}
	}
};

$.prompt(statesdemo);

To use states pass in a collection (array or object) of objects with common properties (html, buttons, focus, submit, position..).

var tourSubmitFunc = function(e,v,m,f){
			if(v === -1){
				$.prompt.prevState();
				return false;
			}
			else if(v === 1){
				$.prompt.nextState();
				return false;
			}
},
tourStates = [
	{
		title: 'Welcome',
		html: 'Ready to take a quick tour of jQuery Impromptu?',
		buttons: { Next: 1 },
		focus: 1,
		position: { container: 'h1', x: 200, y: 60, width: 200, arrow: 'tc' },
		submit: tourSubmitFunc
	},
	{
		title: 'Download',
		html: 'When you get ready to use Impromptu, you can get it here.',
		buttons: { Prev: -1, Next: 1 },
		focus: 1,
		position: { container: '#Download', x: 170, y: 0, width: 300, arrow: 'lt' },
		submit: tourSubmitFunc
	},
	{
		title: "You've Got Options",
		html: 'A description of the options are can be found here.',
		buttons: { Prev: -1, Next: 1 },
		focus: 1,
		position: { container: '#Options', x: -10, y: -145, width: 200, arrow: 'bl' },
		submit: tourSubmitFunc
	},
	{
		title: 'Examples..',
		html: 'You will find plenty of examples to get you going..',
		buttons: { Prev: -1, Next: 1 },
		focus: 1,
		position: { container: '#Examples', x: 80, y: 10, width: 500, arrow: 'lt' },
		submit: tourSubmitFunc
	},
	{
		title: 'The Tour Code',
		html: 'Including this tour... See, creating a tour is easy!',
		buttons: { Prev: -1, Next: 1 },
		focus: 1,
		position: { container: '#TourCode', x: 180, y: -130, width: 400, arrow: 'br' },
		submit: tourSubmitFunc
	},
	{
		title: 'Learn More',
		html: 'If you would like to learn more please consider purchasing a copy of Impromptu From I to U. If you found Impromptu helpful, please see the links to the left. If not, thanks for stopping by!',
		buttons: { Done: 2 },
		focus: 1,
		position: { container: '.donation', x: 120, y: -70, width: 400, arrow: 'tl lb' },
		submit: tourSubmitFunc
	}
];
$.prompt(tourStates);

Forms

The bread and butter of Impromptu is forms. By simply including form fields in the html all form values are gathered and sent via the "f" (aka "form") parameter. The "m" (aka "message") parameter is a jQuery object of the message itself incase you need to modify the dom. Open your javascript console to view the object sent on submit.

var statesdemo = {
	state0: {
		title: 'Name',
		html:'<label>First <input type="text" name="fname" value=""></label><br />'+
			'<label>Last <input type="text" name="lname" value=""></label><br />',
		buttons: { Next: 1 },
		focus: 1,
		submit:function(e,v,m,f){ 
			console.log(f);

			e.preventDefault();
			$.prompt.goToState('state1');
		}
	},
	state1: {
		title: 'Gender',
		html:'<label><input type="radio" name="gender" value="Male"> Male</label><br />'+
			'<label><input type="radio" name="gender" value="Female"> Female</label>',
		buttons: { Back: -1, Next: 1 },
		focus: 1,
		submit:function(e,v,m,f){ 
			console.log(f);

			if(v==1) $.prompt.goToState('state2')
			if(v==-1) $.prompt.goToState('state0');
			e.preventDefault();
		}
	},
	state2: {
		title: 'Transportation',
		html:'<label>Travels By <select name="travel" multiple>'+
				'<option value="Car" selected>Car</option>'+
				'<option value="Bus">Bus</option>'+
				'<option value="Plane" selected>Plane</option>'+
				'<option value="Train">Train</option>'+
			'</select></label>',
		buttons: { Back: -1, Done: 1 },
		focus: 1,
		submit:function(e,v,m,f){ 
			console.log(f);

			e.preventDefault();
			if(v==1) $.prompt.close();
			if(v==-1) $.prompt.goToState('state1');
		}
	},
};

$.prompt(statesdemo);

Advanced

The following are example demonstrations of various useful utilities with Impromptu.