mBox Documentation

Installation

To get started, all you need is a new version of MooTools and MooTools More/Element.Measure.
Then include mBox.Core.js together with its CSS file and you are set.

A very basic mBox could look like this:

var myMBox = new mBox({
    content: 'This is a very basic mBox. Click anywhere to close.'
});
 
myMBox.open();

Remember to put your JavaScript code into window.addEvent('domready', function() { });.

Attach your mBox to elements

The option attach helps you adding the open and close-events to your elements.
In following example, the element with id myMBox will open and close your mBox:

new mBox({
    content: 'This mBox will open when clicking on an element with id="myBox".',
    attach: 'myMBox'
});

If you want your mBox to open on mouseenter, you can set the option event to mouseenter:

new mBox({
    content: 'This mBox will open on mouseenter and close on mouseleave.',
    attach: 'myMBox1',
    event: 'mouseenter'
});

To attach your mBox to more than one element, you can also use a class-name.

Content

The examples above have a simple string as content, but you often need a bit more content than just plain text.
So when your content gets too big to write in JavaScript, create a hidden element and let the mBox grab it:

<div id="element_id" style="display:none">
<p>This Element will be injected into the mBoxes content area and then displayed.</p>
<p>This way you can load any size of content into your mBox.</p>
</div>
 
new mBox({
    content: 'element_id',
    attach: 'myMBox2'
});

You can also use a class-name to inject more than one element into your mBox.

Size

By default the mBox adjusts its size to its content, but you also can specify its width and/or height:

new mBox({
    content: 'This mBox is 150px wide and 100px high.',
    width: 150,
    height: 100,
    attach: 'myMBox3'
});

Position

The default position of mBox.Core is the center of your browser-window.

With the options position, offset and target you can move the mBox anywhere you want:

new mBox({
    content: 'This mBox will appear beneath element…',
    target: 'myMBox4',
    position: {
        y: ['bottom', 'outside'],
        x: 'right'
    },
    offset: {
        y: 10
    },
    attach: 'myMBox4'
});

You can set any DOM Element as target-element, including the window.
By default the position of mBox.Core is inside the target-element. To place an element to an outside position, you need to supply a second variable in an array, e.g. x: ['left', 'outside']

Style

Styling your mBox is done with CSS. You can either edit the mBoxCore.css file, or write your own theme.
To create a theme, duplicate mBoxCore.css and define your styles for .mBox.Core-YourThemeName:

<style type="text/css">
.mBox.Core-MyTheme {
    font-size: 16px;
}
.mBox.Core-MyTheme .mBoxContainer {
    background-color: #fff;
    border: 5px solid #4a7ea4;
}
.mBox.Core-MyTheme .mBoxContent {
    padding: 20px;
}
</style>
 
new mBox({
    theme: 'MyTheme',
    content: 'This mBox has its own theme.',
    attach: 'myMBox5'
});

If you need to define styles for a specific mBox, you can do so with the options setStyles or addClass.
Refer to section options for more info.

Overlay

To add an overlay, simply set the option overlay to true:

new mBox({
    content: 'This mBox has an overlay.',
    overlay: true,
    attach: 'myMBox6'
});

You can also specify the overlays color, opacity and its fade-duration:

new mBox({
    content: 'This mBox has a white overlay.',
    overlay: true,
    overlayStyles: {
        color: 'white',
        opacity: 0.8
    },
    overlayFadeDuration: 50,
    attach: 'myMBox7'
});

Fading

By default the mBox will fade on open and on close. This can be changed with the option fade:

new mBox({
    content: 'This mBox wont fade on open and will fade slowly on close.',
    fade: {
        open: false,
        close: true
    },
    fadeDuration: 1500,
    attach: 'myMBox8'
});

You also can set the option fade to false to disable fading altogether.
To specify different fade durations, use an object: fadeDuration: { open: 200, close: 300 }

Open and close

To open or close an mBox manually, use myMBox.open([options]) or myMBox.close([options]).
Refer to following example so see what options you can use:

var myMBox = new mBox({
    content: 'This mBox is opened manually.',
    closeOnBodyClick: false // Make sure you have to click the link to close
});
 
myMBox.open({
    instant: true,
    target: 'myMBox9',
    position: {
        x: ['left', 'outside']
    },
    offset: {
        x: 20
    }
});
 
myMBox.close({
    instant: true
});

You can delay opening and closing with the options delayOpen and delayClose:

new mBox({
    content: 'This mBox will open after 0.5 seconds and close after 2 seconds.',
    delayOpen: 500,
    delayClose: 2000,
    attach: 'myMBox10',
    event: 'mouseover'
});

There are many options (like closeOnBodyClick), which allow you to control which action should close the mBox, e.g. pressing esc or clicking on the mBox itself. Refer to section options for more info.

Events

You can set following events to your mBox:

onInitFires when the mBox is initialized
onBoxReadyFires when the mBox is created
onOpenFires when the mBox starts opening
onOpenCompleteFires when the mBox finished opening
onCloseFires when the mBox starts closing
onCloseCompleteFires when the mBox finished closing
new mBox({
    onBoxReady: function() {
        $('myMBox11_content').setStyle('color', 'green');
    },
    onOpen: function() {
        $('myMBox11_content').set('html', 'Opening…');
    },
    onOpenComplete: function() {
        $('myMBox11_content').set('html', 'I am open now.');
    },
    onClose: function() {
        $('myMBox11_content').set('html', 'Closing…');
    },
    onCloseComplete: function() {
        $('myMBox11_content').setStyle('color', 'blue');
    },
    content: '<span id="myMBox11_content"></span>',
    attach: 'myMBox11',
    fadeDuration: 3000
});

Reinitialize an mBox

When an mBox is being initialized, it attaches the events to all currently available elements. When you load new content (e.g. with Ajax), or create new elements, and want to attach an mBox to it, you need to reinitialize your mBox.
Use the function reInit() to reattach your mBoxes to the new elements:

var myMBox = new mBox({
    // options…
});
 
myMBox.reInit();

Options

This is the complete list of options you can set for mBox.Core:

id: '',
The id of your mBox, defaults to mBox_1, mBox_2, mBox_3…
theme: '',
Name of your mBoxes theme.
addClass: {
    wrapper: '',
    container: '',
    content: '',
    title: '',
    footer: ''
},
Add additional classes to the wrapper, container, content, title or footer.
To add a class only to the wrapper, provide a string, e.g. addClass: 'myClass'.
setStyles: {
    wrapper: {},
    container: {},
    content: {},
    title: {},
    footer: {}
},
Set specific styles to the wrapper, container, content, title or footer.
To set styles only to the wrapper, provide a style object, e.g. setStyles: { color: 'red' }.
target: $(window),
The target element where your mBox will be positioned at. You can use an element id, element reference, the $(window) object or 'mouse' to stick the mBox to your pointer.
attach: null,
The elements which will open / close the mBox.
Use an element id, element reference or an elements class name.
event: 'click',
The event which will open / close the mBox. You can use 'click' or 'mousenter'.
preventDefault: false,
Prevents the default event to fire when clicking on an attached element. E.g. Prevents a link to follow the href, when the mBox is attached to a link.
width: 'auto',
height: 'auto',
The width and height of the content area.
zIndex: 8000,
The z-index of your mBox.
content: null,
The content of your mBox.
You can use a string, an element id, an element reference or a class-name. Those elements will be grabbed by the mBox and their style display: none will be set to display: ''
setContent:
    'data-setContent',
If the element, which opens your mBox, has the attribute data-setContent, this attributes value is the new content:
data-setContent="New content" will set the content of your mBox to 'New content'
data-setContent="elementID" will hide all elements in the content area, then inject and display the element with id="elementID"
title: null,
Adds a title to your mBox.
You can use a string, an element id or an element reference.
footer: null,
Adds a footer to your mBox.
You can use a string, an element id or an element reference.
draggable: false,
Set to true, to make your mBox dragabble when clicking on title.
position: {
    x: 'center',
    y: 'center'
},
Defines the position of your mBox in relation to the target element.
x defnes the horizontal position, y the vertical.
If you want to set the position outside or inside the target element you need to use an array:
E.g. x: ['right', 'outside'] or y: ['top', 'inside']
Sometimes you need to tell the mBox which attribute to use (left or right, top or bottom). To do so use a third variable in your position array:
E.g. x: ['left', 'inside', 'right'] or y: ['top', 'outside', 'bottom']
offset: {
    x: 0,
    y: 0
},
The horizontal or vertical offset to add or substract.
fixed: true,
The position of your mBox adjusts when scrolling or when you resize the window.
pointer: false,
If at least one of the positions is "outside", you can add a pointer to your mBox.
To adjust the pointers position, use 'right', 'left', 'top', 'bottom' or 'center'.
To add an offset you need to use a second variable in an array, e.g. ['left', 10].
fade: {
    open: true,
    close: true
},
Set to false to open / close the mBox instantly without fading.
To disable fading altogether, you can also set fade: false
fadeDuration: {
    open: 200,
    close: 300
},
The fade duration.
You can also set fadeDuration: 200 to use this value for opening and closing.
overlay: false
Set to true to add an overlay.
overlayStyles: {
    color: 'black',
    opacity: 0.75
},
Sets the color and opacity of your overlay.
overlayFadeDuration: 100,
The overlays fade duration.
transition: {
    open: null,
    close: null
},
Adds a transition when your mBox opens or closes.
Following shortcuts are availible: 'flyin', 'flyout', 'flyinout', 'flyoutin', 'bounce', 'bouncefly'
You can also define your own transitions:
E.g. {open: {transition: 'bounce:in', property: 'top', duration: 400, difference_start: 50, difference_end: 0}
closeOnEsc: true,
Closes your mBox when pressing esc.
closeOnClick: false,
Closes your mBox when clicking anywhere.
closeOnBoxClick: false,
Closes your mBox when clicking on the mBox itself.
closeOnWrapperClick: false,
Closes your mBox when clicking on the wrapper (but won't close when clicking on any child)
closeOnBodyClick: true,
Closes your mBox when clicking anywhere except on the mBox itself.
closeOnMouseleave: true,
Closes your mBox when the mouse leaves the mBox area.
closeInTitle: false,
Adds a close button into the title area if there is one.
delayOpen: 0,
Delay opening your mBox in ms.
delayClose: 0,
Delay closing your mBox in ms.
delayOpenOnce: true,
delayOpen will be ignored if your mBox isn't completely closed.
constructOnInit: true,
When set to false your mBox will be constructed onOpen rather then when it's being initialised. Might add some performance when working with a lot of mBoxes.
openOnInit: false
Open your mBox automatically once it's initialized.