Documentation

Overview

There are 2 ways you can use the plugin, either through (Method 1) JavaScript calls, or (Method 2) using HTML attributes. When you use HTML attributes, those attributes and their values are translated into JavaScript objects which are then passed to the plugin as in Method 1. This means that anything you can achieve using Method 2 can also be achieved using Method 1. The opposite, however, is not true. You can only specify options which require static values e.g. strings, numbers etc. It is not possible to pass an anonymous function f.e. using HTML attributes, but in the general case you won't need to.

All examples shown in this manual are achieved using Method 2 for clarity, but there is also a source code for each of them, showing the same example using JavaScript.

JavaScript (Method 1)

As most jQuery plugins, MultiBackground can be called directly on a jQuery object or a collection of elements:

$('#element').multiBackground(); // Applied to element with id="element"
$('.element').multiBackground(); // Applied to all elements with class="element"

Once executed, the plugin returns a reference to the same jQuery object, which means you can chain whatever you want after it:

$('#element').multiBackground().css("background", "#fff");

The plugin accepts 2 input parameters.

• The first argument: options must be an object of options to specify what should the plugin do, or an array of such objects. If an array is supplied, each element of the array is passed as a separate call as if you are chaining calls to the plugin on the same jQuery object.

  // The following two lines do the same thing
  $("#element").multiBackground([{"a": "b"}, {"c": "d"}]);
  $("#element").multiBackground({"a": "b"}).multiBackground({"c": "d"});

  As the default operation of the plugin is to add a background layer, the first approach is used to simultaneously create multiple background layers in a single call.

• The second argument: silent must be of type boolean and specify if the plugin should be silent about any fatal errors and just fail silently. If this parameter is set to true and a fatal errors occures it will be logged in the console and the script will stop. If the parameter is set to false the error will also be passed to the function alert and displayed in the browser.

  This argument is not required and is set to false by default.

HTML attributes (Method 2)

The plugin has an ability to automatically parse HTML attributes and make the corresponding plugin calls for certain elements. This happens on jQuery's event $(document).ready();.

To benefit from this ability you must mark your elements and add the appropriate attributes for the plugin to use. First step is to mark an element as a MultiBackground element. This is done by adding the attribute data-multibackground to the element like this:

<div data-multibackground></div>

Generally you don't need to specify a value for this attribute, but you can use anything you want. If, however, you set the value to debug, then the plugin will be run with silent = false as second argument, e.g. NOT in the default silent mode. Look at the example below to better understand the difference.

<div data-multibackground></div>
<div data-multibackground="debug"></div>

$(...).multiBackground({}, true);
$(...).multiBackground({}, false);

The first argument of the plugin, or the options, is parsed and extracted from the element arguments using a strict scheme of rules:

1. Each value of the options object, no matter how deep, is represented by a single HTML attribute. The attribute name determines the key in the options object and the value of the attributes is used as the value for that key.
2. Each attribute must be prefixed by data-multibackground-layer-[layer index]- where [layer index] is the index of the background layer for which this attribute applies. The count starts from 0.
3. The prefix is followed by 1 or more character combinations (usually small letters and numbers) divided by -. Each of these combinations represent an object key. If there is more than one such key, then the resulting value will be another object with the next key, achieving deep object structure.
4. Each value is parsed as string without any validation, but is then re-parsed and validated when used by the plugin (which is also true for the JavaScript method).
5. When all attributes are parsed, if there is an object, all of which' keys are consecutive numbers starting from 0, the object is converted to an array.

Here are a few examples that illustrate the above rules (on the left is the HTML structure and on the right is the parsed options object):

<div data-multibackground
    data-multibackground-layer-0-type="solid"
    data-multibackground-layer-0-color="#f98">
    Content
</div>

$(...).multiBackground({"type": "solid", "color": "#f98"});

<div data-multibackground
    data-multibackground-layer-0-type="solid"
    data-multibackground-layer-0-color="#fff9"
    data-multibackground-layer-1-type="solid"
    data-multibackground-layer-1-color="#0009">
    Content
</div>

$(...).multiBackground([{"type": "solid", "color": "#fff9"}, {"type": "solid", "color": "#0009"}]);

<div data-multibackground
    data-multibackground-layer-0-now-this-is-some-deep-value="yep">
    Content
</div>

$(...).multiBackground({"now": {"this": {"is": {"some": {"deep": {"value": "yep"}}}}}});

<div data-multibackground
    data-multibackground-layer-0-an-array-0-itis="a"
    data-multibackground-layer-0-an-array-1-indeed="b"
    data-multibackground-layer-0-an-object="c">
    Content
</div>

$(...).multiBackground({"an": {"array": [{"itis": "a", "indeed": "b"}], "object": "c"}});

The options object

This is the object that carries all information used by the plugin.

When constructing this object you can pass a string value to the key action to specify an action to be performed. By default this option is omitted and the value append is used as default.

The next most important option key is type, which is used to specify the type of the background layer you want to prepend or append. Here is a list of all supported background types and their specifications:

Background type: Solid "type": "solid"

Overview

This is a simple background type, which uses a solid color as a background. The color must be in short HEX, full HEX, RGB or RGBA format: #fff, #fff9, #ffffff, #ffffff99, rgb(255, 255, 255), rgb(255, 255, 255, 153).

Options

Background type: Gradient "type": "gradient"

Overview

This is a simple background type, which uses a collection of points for which you specify position and color to achieve a gradient effect. All colors must be in short HEX, full HEX, RGB or RGBA format: #fff, #fff9, #ffffff, #ffffff99, rgb(255, 255, 255), rgb(255, 255, 255, 153).

Options

Structure of "points": [{...} ... ]

Background type: Movable

Overview

This is a special type of background, which is used as an extension of types like image, pattern or video. It supplies those background types with the ability to be sized and positioned differently according to the parent element size, window scroll position and the type of relation to those environment properties. All background types that extend this one are marked as Movable in this documentation and inherit all Movable properties and features.

The main property of this type allows the element being used as a background layer to be centered horizontally and vertically relative to the container element. It is also resized in a way that will always keep the aspect ratio of the element, and will fill the entire visible space of the containing element (the containing element is assigned overflow: hidden; to hide the extra parts of the background element).

Options

Background type: Image (is Movable) "type": "image"

Overview

This is a background type which displays an image. It is sized and positioned according to the size of the container, so that it will always fill the entire background space. The image is centered both horizontally and vertically.

Options

Background type: Pattern (is Movable) "type": "pattern"

Overview

This is a background type which displays a pattern (a single image repeated both horizontally and vertically until it fills the entire element). It is positioned according to the size of the container, so that it will always fill the entire background space.

Options

Background type: Video (is Movable)

Overview

Just like Movable this is a special type of background, which is used as an extension of types like youtube or vimeo. It defines those background types as video objects and supplies several standardized methods and features.

Each background type which is defined as Video type also supplies an API for controlling the created video object after the initialization of the plugin has finished. The API is rather simple and supplies methods able to play, pause, stop, mute, unmute etc. the video objects. Once a video object is created on a layer of a certain element, just call .multiBackground({...}); on that element, and supply the action you would like to perform on the video in the "action" key. The possible calls and required parameters were already covered in this documentation in the section: The options object.

Each background type which is defined as Video also inherits all features of the Movable type.

Options

Structure of "video": {...}

Background type: HTML5 Video (is Video) "type": "video"

Overview

This is a background type which displays an HTML5 Video. It is sized and positioned according to the size of the container, so that it will always fill the entire background space.

Options

Structure of "url": {...}

Background type: YouTube Video (is Video) "type": "youtube"

Overview

This is a background type which displays a YouTube Video. It is sized and positioned according to the size of the container, so that it will always fill the entire background space.

Options

Background type: Vimeo Video (is Video) "type": "vimeo"

Overview

This is a background type which displays a Vimeo Video. It is sized and positioned according to the size of the container, so that it will always fill the entire background space.

Options

Background type: iFrame "type": "iframe"

Overview

This is a background type which displays a page inside a custom iFrame. It is always 100% the width and height of the container element.

Options

Background type: Google Map "type": "gmap"

Overview

This is a background type which displays a Google Map. It is always 100% the width and height of the container element.

Options

Structure of "gmap": {...}

Slideshow

Overview

You can turn any MultiBackground element into a slideshow slider, where each layer (type doesn't matter) will be used as a slide.

To turn a MultiBackground element into a slideshow you must add a data-multibackground-slideshow-direction attribute (or respectively a [slideshow][direction] option) specifying the direction of the slideshow. Further, each slideshow option is set under the slideshow key for each layer, e.g.: data-multibackground-layer-0-slideshow-transition="linear,500"

Possible direction values

forward

Specifies a forwards auto-playing slideshow, where layers will be played in the order they are added to the MultiBackground element.

backward

Specifies a backwards auto-playing slideshow, where layers will be played in reverse of the order they are added to the MultiBackground element.

random

Specifies a random auto-playing slideshow order.

manual

Specifies a manual slideshow. No layer / slide will be auto-played. You must control the slideshow via the API.

Options

API

You can control the slideshow (preferably slideshows in manual mode) using several available API calls. Please refer to The options object section.

Alignment

Horizontal

As of 1.1.7 you can specify horizontal alignment of any layer of the type movable (image, pattern, video etc.). The alignment option is only applicable for the fixed attachment type and the possible values are: left, center (default) and right.

To specify the horizontal alignment set a data-multibackground-alignment-horizontal attribute.

Vertical

As of 1.1.7 you can specify vertical alignment of any layer of the type movable (image, pattern, video etc.). The alignment option is only applicable for the fixed attachment type and the possible values are: top, middle (default) and bottom.

To specify the vertical alignment set a data-multibackground-alignment-vertical attribute.

Advanced options

Transition

Showing or hiding elements or layers often uses some kind of a transition effect. Options which require Transition type of values must comply to the following structure.

A Transition can be a custom anonymous function or a string.

If a function is passed it must accept the jQuery object of the element being animated as first argument, and the target opacity of the animation as second argument.

If a string is passed it should look like this: linear,500, where linear is a easing name and 500 is the desired duration of your animation in milliseconds.

By default GPU acceleration is used for the transition specified by string on browsers that support it (almost any modern browser except IE9), so make sure the easing you have passed is a valid CSS3 easing name. Browsers with no GPU acceleration will fallback to a jQuery.animate() alternative, so in this case you must make sure the easing is a valid jQuery easing name.

Please note, that the minimum required version of jQuery is 1.8.3, which only includes 2 easing types: linear and swing. If you want to use more you need to either use a newer jQuery version, or load the jQuery Easing Plugin.

Please also note, that most browsers do not support large duration values, so keep the transition duration under 30 seconds (30000 ms).

transitionloaded (value must be a valid Transition)

This is the transition used to show (animate opacity from 0 to 1) MultiBackground layers, once their content is ready.

data-multibackground-integrator

There is a third way of initializing the plugin, that was developed for the WordPress version of the plugin. It combines an HTML attribute approach using JSON structure being passed directly to the JavaScript plugin.

To initialize the plugin using this "integrator" approach simply create a new hidden element like so: <div style="display:none;"></div> in the document and set 3 attributes: data-multibackground-integrator, data-multibackground-integrator-selector and data-multibackground-integrator-options

The first one just marks the element as an integrator element and does not require a value. You can optionally set the value to debug to enable the debug mode of the plugin.

The second must contain a valid jQuery selector of the element(s) in the DOM, on which you want to apply the plugin.

The third must contain a serialized JSON string with all the options, that will be passed to the MultiBackground plugin.