Modal windows

The template includes a powerful modal window plugin, with several opening methods and 40+ options to get the exact desired look and behavior.

Opening a modal is as simple as:

$.modal({
	title: 'Modal window',
	content: 'This is an example of standard modal window.'
});

If you plan to open many modals with the same parameters, defining a custom function will save you some time - for instance, this function will only require the content and buttons parameters:

function openModal(content, buttons)
{
	$.modal({
		title: 'Modal window',
		content: content,
		buttons: buttons,
		beforeContent: '<div class="carbon">',
		afterContent: '</div>',
		buttonsAlign: 'center',
		resizable: false
	});
}

Then just call:

openModal('My modal content', {
	'Process': function(modal) { /* Some custom code */ modal.closeModal(); },
	'Cancel': function(modal) { modal.closeModal(); }
});

Methods

$.modal(options)

Opens a new modal window

Parameters

@param object options an object with any of the $.modal.defaults options.

Return

@return object the jQuery object of the new window

$.modal.alert(message, options)

Display an alert message

Parameters

@param string message the message, as text or html
@param object options same as $.modal() (optional)

Return

@return jQuery the new window

$.modal.prompt(message, callback, cancelCallback, options)

Display a prompt

Parameters

@param string message the message, as text or html
@param function callback the function called with the user value: function(value). Can return false to prevent close.
@param function cancelCallback a callback for when the user closes the modal or click on Cancel. Can return false to prevent close.
@param object options same as $.modal() (optional)

Return

@return jQuery the new window

$.modal.confirm(message, confirmCallback, cancelCallback, options)

Display a confirm prompt

Parameters

@param string message the message, as text or html
@param function confirmCallback the function called when hitting confirm
@param function cancelCallback the function called when hitting cancel or closing the modal
@param object options same as $.modal() (optional)

Return

@return jQuery the new window

jQuery methods to run on content

$(selector).modal(options)

Wraps the selected elements content in a new modal window.
Some options can be set using the inline html5 data-modal-options attribute:
<div data-modal-options='{"title":"Modal window title"}'>Modal content</div>

Parameters

@param object options same as $.modal()

Return

@return jQuery the new window

jQuery methods to run on modals

$(selector).getModalContentBlock()

Use this method to retrieve the content div in the modal window

$(selector).getModalWindow()

Use this method to retrieve the modal window from any element within it

$(selector).setModalContent(content, resize)

Set window content (only if not using iframe)

Parameters

@param string|jQuery content the content to put: HTML or a jQuery object
@param boolean resize use true to resize window to fit content (height only)

$(selector).setModalContentSize(width, height)

Set window content-block size

Parameters

@param int|boolean width the width to set, true to keep current or false for fluid width (false only works if not iframe)
@param int|boolean height the height to set, true to keep current or false for fluid height (false only works if not iframe)

$(selector).loadModalContent(url, options)

Load AJAX content

Parameters

@param string url the content url
@param object options (see defaults.ajax for details)

$(selector).setModalTitle(title)

Set modal title
Note: if the option titleBar was set to false on opening, this will have no effect

Parameters

@param string title the new title (may contain HTML), or an empty string to remove the title

$(selector).centerModal(animate)

Center the modal

Parameters

@param boolean animate true to animate the window movement

$(selector).setModalPosition(x, y, animate)

Set the modal postion in screen, and make sure the window does not go out of the viewport

Parameters

@param int x the horizontal position
@param int y the vertical position
@param boolean animate true to animate the window movement

$(selector).putModalOnFront()

Put modal on front

$(selector).closeModal()

Closes the window

Accessors

$.modal.current

Shortcut to the current window, or false if none
Type: jQuery|boolean

$.modal.all

jQuery selection of all opened modal windows
Type: jQuery

Options reference

blocker

Add a blocking layer to prevent interaction with background content
Type: boolean
Default: true

blockerVisible

Color the blocking layer (translucid black)
Type: boolean
Default: true

closeOnBlur

If true, any click on the blocking layer will close the window
Type: boolean
Default: false

classes

CSS classes for the modal
Type: string
Default: ''

beforeContent

HTML before the content
Type: string
Default: ''

afterContent

HTML after the content
Type: string
Default: ''

content

Content of the window: HTML or jQuery object
Type: string|jQuery|boolean
Default: false

contentBg

Add a white background behind content
Type: boolean
Default: true

contentAlign

Alignement of contents ('left', 'center' or 'right') ignored for iframes
Type: string
Default: 'left'

useIframe

Uses an iframe for content instead of a div
Type: boolean
Default: false

url

Url for loading content or iframe src
Type: string|boolean
Default: false

titleBar

Show the title bar (use null to auto-detect when title is not empty)
Type: boolean|null
Default: null

title

Title of the window, or false for none
Type: string|boolean
Default: false

draggable

Enable window moving
Type: boolean
Default: true

resizable

Enable window resizing
Type: boolean
Default: true

scrolling

If true, enable content vertical scrollbar if content is higher than 'height' (or 'maxHeight' if 'height' is undefined)
Type: boolean
Default: true

horizontalScrolling

If true, enable horizontal scrolling when using the custom scroll plugin
Type: boolean
Default: false

actions

Actions leds on top left corner, with text as key and function on click or config object as value
Ex:
{
    'Close' : function(modal) { modal.closeModal(); }
}
Or:
{
    'Close' : {
        color: 'red',
        click: function(modal) { modal.closeModal(); }
    }
}

Type: boolean
Default: {
    'Close' : {
        color: 'red',
        click: function(modal) { modal.closeModal(); }
    }
}

actionsTooltips

Configuration for action tooltips
Type: object
Default: {
    spacing: 5,
    classes: ['black-gradient'],
    animateMove: 5
}

buttons

Map of bottom buttons, with text as key and function on click or config object as value
Ex:
{
    'Close' : function(modal) { modal.closeModal(); }
}
Or:
{
    'Close' : {
        classes: 'blue-gradient glossy huge full-width',
        click: function(modal) { modal.closeModal(); }
    }
}
Type: object
Default: {
    'Close': {
        classes: 'blue-gradient glossy big full-width',
        click: function(modal) { modal.closeModal(); }
    }
}

buttonsAlign

Alignement of buttons ('left', 'center' or 'right')
Type: string
Default: 'right'

buttonsLowPadding

Use low padding for buttons block
Type: boolean
Default: false

onOpen

Function called when opening window
Scope: the modal window
Type: function
Default: false

onClose

Function called when closing window.
Note: the function may return false to prevent close.
Scope: the modal window
Type: function
Default: false

maxSizeMargin

Minimum margin to viewport border around window when the max-size is reached
Type: int
Default: 10

minHeight

Minimum content height
Type: int
Default: 16

minWidth

Minimum content width
Type: int
Default: 200

maxHeight

Maximum content width, or false for no limit
Type: int|boolean
Default: false

maxWidth

Maximum content height, or false for no limit
Type: int|boolean
Default: false

height

Initial content height, or false for fluid size
Type: int|boolean
Default: false

width

Initial content width, or false for fluid size
Type: int|boolean
Default: false

resizeToFit

When setting a window's size, detect if the content is too high and force a resize to fit
Type: boolean
Default: true

alertOptions

Default options for alert() method
Type: object
Default: {
    contentBg: false,
    contentAlign: 'center',
    minWidth: 120,
    width: false,
    maxWidth: 260,
    resizable: false,
    actions: {},
    buttons: {
        'Close' : {
            classes: 'blue-gradient glossy big full-width',
            click: function(modal) { modal.closeModal(); }
        }
    },
    buttonsAlign: 'center',
    buttonsLowPadding: true
}

promptOptions

Default options for prompt() method
Type: object
Default: {
    width: false,
    maxWidth: 260,
    resizable: false,
    actions: {},
    textCancel: 'Cancel',
    textSubmit: 'Submit'
}

confirmOptions

Default options for confirm() method
Type: object
Default: {
    contentAlign: 'center',
    minWidth: 120,
    width: false,
    maxWidth: 260,
    buttonsAlign: 'center',
    textCancel: 'Cancel',
    textConfirm: 'Confirm'
}

Options for ajax loading

When the modal window has an url to load, it uses the jQuery $.ajax method. You may use the ajax option to pass an object to this method with any available option, for instance:

$.modal({
	title: 'Modal window',
	content: 'This is an example of standard modal window.',
	ajax: {
		type: 'GET',
		data: 'answer=42',
		resizeOnLoad: true
	}
});

The plugin also provides a few extra options:

loadingMessage

Any message to display while loading, or leave empty to keep current content
Type: string|jQuery
Default: null

errorMessage

The message to display if a loading error happened. May be a function: function(jqXHR, textStatus, errorThrown)
Ignored if error callback is set
Type: string|jQuery
Default: 'Error while loading content. Please try again.'

resize

Use true to resize window on loading message and when content is loaded. To define separately, use options below:
Type: boolean
Default: false

resizeOnMessage

Use true to resize window on loading message
Type: boolean
Default: false

resizeOnLoad

Use true to resize window when content is loaded
Type: boolean
Default: false