#ModalDialogue

ModalDialogue is a Javascript module that (you guessed it) creates modal dialogues.

ModalDiaogue supports three types of modal dialogue:

• Single dialogue
• Multi-view dialogue
• Wizard dialogue

Each type of dialogue takes a Modal Dialouge Definition (MDD), or a series of MDDs, which allow the specification of a dialogue. The definition of an MDD is defined in Usage.

##Support

ModalDialogue has been tested in IE8+, Chrome, FireFox 3.6+ and Opera.

##Dependencies

Because the ModalDialogue module was written to be a part of a larger application it depends on other common modules of that application. The ModalDialogue depends on the following modules:

• util.js - Provides utility methods for performing cross-browser operations on DOM nodes, arrays, etc.
• UIAnimator - Animation module, only required when an animation is used.
• require.js - An engine for fetching modules.
• ModalDialogue.css - the stylesheet for the dialogues.
• ModalDialogue.mobile.css - stylesheet for mobile devices.

There is a minified standalone version of ModalDialogue that is available, and can be used like so:

<script type="text/javascript" src="ModalDialogue.standalone.min.js"></script>
<link rel="stylesheet" type="text/css" href="ModalDialogue.min.css" />
<!-- Do your own check to insert ModalDialogue.mobile.min.css -->

<script type="text/javascript">
	ModalDialogue.createSingle(<< Insert MDD Here. >>)
</script>

The stylesheet relies on a single image named ModalDialogueError.(png|svg) that is used when errorDialogue is true in the dialogue, so unless you know you're never going to use that property, please ensure the image(s) is in the path.

##Usage

This section will document the three methods for creating dialogues and the Modal Dialouge Definition. It will also document the DOM structure of the dialogue so that it can be themed with custom CSS.

###MDD

The Modal Dialogue Definition (MDD) is an object literal definition of a modal dialogue. The MDD (or MDDs) is passed to the constructor method, which then generates a DOM structure and presents it.

Each heading below refers to a property of the MDD, a minimal MDD only needs a title and body property, if it does not have these properties it is an invalid MDD and the constructor will throw an exception.

Some constructor methods extend the MDD specification, for example, if a multi view dialogue is being constructed a navTitle property can be used, but is otherwise ignored. MDD extensions are documented in the constructor usage specification.

####MDD.title {string}

The title property is a simple string that will be used as a title in the dialogue.

var MDD = {
	'title' : 'Hello World'
}

Note: the above is not a valid MDD as it does not have a body property.

####MDD.body {string|array|Element}

The body property specifies the main text used within the dialogue. The property can be an array of strings or a lone string, these strings can contain HTML.

If the string is not wrapped in an HTML tag it will be automatically wrapped in a <p> tag.

var MDD = {
	'title' : 'Hello World',
	'body' : ['<h2>This is a sub-title.</h2>','This will be wrapped in a paragraph.', '<img src="/path/to/darth-vader.png" alt />']
}

It is also possible to create an HTML node and include it either on its own or in an Array. e.g.

var myNode = document.createElement("a")

myNode.onclick = function() { console.log('Bob!')) }

var MDD = {
	'title' : 'Hello World',
	'body' : ['This is some text.', myNode, '^ That is my node.']
}

####MDD.buttons {object} The buttons property allows dialogue buttons to be defined using the property name as the text in the button, and the value of the property as the calback function.

If the property contains an object then it will be assumed that that object contains a title and callback property for the title of the button and the function executed when the button is pressed respectively.

The callback is called in the context of the ModalDialogue object, enabling you to use properties of the ModalDialogue object such as close and open. This allows you to write a custom close button.

var MDD = {
	'title' : 'Hello World',
	'body' : 'Lorum Ipsum',
	'buttons' : {
		'Close' : function() {
		
			// cleanup stuff.
			
			// actually close the dialogue.
			this.close()
		
		}
	}
}

It is also possible to have the callback executed under a custom context by specifying the button as an object and adding a context property.

var foo = {
	bar : function() { console.log('Custom context FTW!') }
}

var MDD = {
	'title' : 'Hello World',
	'body' : 'Lorum Ipsum',
	'buttons' : {
		'my custom button' : {
			'title' : 'Click.',
			'callback' : function() {
				this.bar()
			}
			'context' : foo
		}
	}
}

####MDD.form {object}

The form property defines a form within the dialogue that will be displayed after the body text. The form object requires the following properties:

• name - {string} the name of the form.
• inputs - {array} input objects. (defined below)
• callback - {function} function called when enter is pressed or the button is clicked.
• buttonTitle - {string} title of the form button. Optional, defaults to 'Submit'.

An input object has the following properties:

• name - identifier for the input.
• type - type of input. Optional, defaults to text.
• options - if the type is 'select', options is an array of choices.
• placeholder - Placeholder text for the input. Optional.

If the form callback is specified then a button will be injected named Apply, unless there is a buttonTitle property, in which case that text will be used as a title.

When the callback is executed it is passed an object containing the current values of the input as well as the placeholder text if it's specified.

Below is an example usage of the callback:

var MDD = {
	'title' : 'Hello World',
	'body' : 'Lorum Ipsum',
	'form' : {
		'name' : 'lala',
		'callback' : function(inputs) {
		
			// use inputs...
		
		},
		'buttonTitle' : 'Save',
		'inputs' : [
			{
				'name' : 'host',
				'placeholder' : 'localhost'
			},
			{
				'name' : 'port',
				'type' : 'number',
				'placeholder' : 6232
			}
		]
	}
}

The callback is also executed when the enter key is pressed whilst a form input is in focus.

####MDD.alignment

The alignment property can have any of the following values:

• right - align the text to the right
• left - align the text to the left
• center - align the text to the center
• justify - justify the text alignment

The default alignment is left.

####MDD.errorDialogue

If the errorDialogue property is true an error background will be set on the dialogue.

####MDD.customClass

If the customClass property is set then the specified class(es) will be set on the dialogue.

####MDD.animate

The animate property is an object with two properties:

• animateIn - the animation used when opening the dialogue.
• animateOut - the animation used when closing the dialogue.

The out property can have any of the following properties:

• fadeOut - fades the dialogue out using a disolve.
• slideOutTop - slides the dialogue out to the top of the page.
• slideOutBottom - slides the dialogue out to the bottom of the page.
• slideOutLeft - slides the dialogue out to the left of the page.
• slideOutRight - slides the dialogue out to the right of the page.

The in property can have any of the following properties:

• fadeIn - fades the dialogue in using a disolve.
• slideInTop - slides the dialogue in from the top of the page.
• slideInBottom - slides the dialogue in from the bottom of the page.
• slideInLeft - slides the dialogue in from the left of the page.
• slideInRight - slides the dialogue in from the right of the page.

For example:

var MDD = {
	'title' : 'Hello World',
	'body' : 'Lorum Ipsum',
	'animate' : {
		'animateIn' : 'fadeIn',
		'animateOut' : 'slideOutBottom'
	}
}

If the animate property is undefined then no animation will be used, and the animation module will not be required.

Note: Animation is only supported in CSS3-compliant browsers.

###Dialogue Constructors

The dialogue constructor methods are used to create different kinds of dialogue. The three constructors are:

• createSingle
• createMultiView
• createWizard

###ModalDialogue.createSingle

The createSingle method takes a single MDD as a parameter and will construct and display that dialogue. createSingle is the simples constructor method as it simply uses an MDD.

###ModalDialogue.createMultiView

The createMultiView constructor method allows a complex view-based dialogue to be created that allows switching between views using a navigation panel.

To acommodate this new structure this constructor takes an Multi-View Definition (MVD) object as a definition for the dialogue. The MVD is defined as follows:

• views - {array} MDDs representing the individual views.
• title - {string} title that appears above the navigation pane.
• buttons - {object} this property follows the same specification as MDD.buttons.
• animation - {object} this property follows the same specification as MDD.animation.

Changes to the MDD:

MDDs within a Multi-View Dialogue are changed slightly to accomodate the new structure, they have the following differences:

• The button property is ignored completely within individual MDDs. Instead, define buttons in the MVD.
• The animate property is ignored within the individual MDDs. Instead, define the animate property on the MVD.
• The navTitle property is added to the view as a shorter version of MDD.title displayed in the navigation sidebar. If unspecified, defaults to the title specification.

Below is an example of an MVD:

var MVD = {
	'title' : "Hello World",
	'views' : [MDD1, MDD2, MDD3, ...],
	'buttons' : {close:true},
	'animate' : {
		'in' : "fadeIn",
		'out' : "slideOutBottom"
	}
}

###ModalDialogue.createWizard

The createWizard constructor method creates a dialogue that allows switching between multiple dialogues using previous and next buttons.

The method accepts two parameters:

• MDDs - {array} list of dialogues.
• animate {object} animation property defined in MDD.animate.

MDD changes:

• Template functions for MDD.buttons.next and MDD.buttons.prev allowing automatic switching to the next and previous dialogues by specifying the property to be true.
• animate property is ignored in individual MDDs, instead use the second parameter.
• Each MDD can use a prev and next button template that will be replaced by createWizard to allow switching between dialogues.

Below is an example of the prev and next button templates.

var MDD1 = {
	'title' : 'Dialogue 1',
	'body' : 'This is the first dialogue and has a next button.',
	'buttons' : { next : true }
}

var MDD2 = {
	'title' : 'Dialogue 2',
	'body' : 'This is the second dialogue and has next and previous buttons.',
	'buttons' : { prev : true, next : true }
}

var MDD3 = {
	'title' : 'Dialogue 3',
	'body' : 'This is the final dialogue and has a previous and close button.',
	'buttons' : { prev : true, close : true }
}

ModalDialogue.createWizard(MDD1, MDD2, MDD3)