1859 lines
41 KiB
Markdown
1859 lines
41 KiB
Markdown
# mixitup.Config
|
||
|
||
## Overview
|
||
|
||
`mixitup.Config` is an interface used for customising the functionality of a
|
||
mixer instance. It is organised into several semantically distinct sub-objects,
|
||
each one pertaining to a particular aspect of MixItUp functionality.
|
||
|
||
An object literal containing any or all of the available properies,
|
||
known as the "configuration object", can be passed as the second parameter to
|
||
the `mixitup` factory function when creating a mixer instance to customise its
|
||
functionality as needed.
|
||
|
||
If no configuration object is passed, the mixer instance will take on the default
|
||
configuration values detailed below.
|
||
|
||
### Contents
|
||
|
||
- [animation](#animation)
|
||
- [behavior](#behavior)
|
||
- [callbacks](#callbacks)
|
||
- [controls](#controls)
|
||
- [classNames](#classNames)
|
||
- [data](#data)
|
||
- [debug](#debug)
|
||
- [layout](#layout)
|
||
- [load](#load)
|
||
- [selectors](#selectors)
|
||
- [render](#render)
|
||
|
||
|
||
<h2 id="animation">animation</h2>
|
||
|
||
A group of properties defining the mixer's animation and effects settings.
|
||
|
||
### enable
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not animation should be enabled for the MixItUp instance.
|
||
If `false`, all operations will occur instantly and syncronously, although callback
|
||
functions and any returned promises will still be fulfilled.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Create a mixer with all animations disabled
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
enable: false
|
||
}
|
||
});
|
||
```
|
||
### effects
|
||
|
||
|
||
|
||
|
||
A string of one or more space-seperated properties to which transitions will be
|
||
applied for all filtering animations.
|
||
|
||
Properties can be listed any order or combination, although they will be applied in a specific
|
||
predefined order to produce consistent results.
|
||
|
||
To learn more about available effects, experiment with our <a href="https://www.kunkalabs.com/mixitup/">
|
||
sandbox demo</a> and try out the "Export config" button in the Animation options drop down.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'fade scale'`
|
||
|
||
###### Example: Apply "fade" and "translateZ" effects to all animations
|
||
|
||
```js
|
||
// As targets are filtered in and out, they will fade between
|
||
// opacity 1 and 0 and transform between translateZ(-100px) and
|
||
// translateZ(0).
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'fade translateZ(-100px)'
|
||
}
|
||
});
|
||
```
|
||
### effectsIn
|
||
|
||
|
||
|
||
|
||
A string of one or more space-seperated effects to be applied only to filter-in
|
||
animations, overriding `config.animation.effects` if set.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `''`
|
||
|
||
###### Example: Apply downwards vertical translate to targets being filtered in
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effectsIn: 'fade translateY(-100%)'
|
||
}
|
||
});
|
||
```
|
||
### effectsOut
|
||
|
||
|
||
|
||
|
||
A string of one or more space-seperated effects to be applied only to filter-out
|
||
animations, overriding `config.animation.effects` if set.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `''`
|
||
|
||
###### Example: Apply upwards vertical translate to targets being filtered out
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effectsOut: 'fade translateY(-100%)'
|
||
}
|
||
});
|
||
```
|
||
### duration
|
||
|
||
|
||
|
||
|
||
An integer dictating the duration of all MixItUp animations in milliseconds, not
|
||
including any additional delay apllied via the `'stagger'` effect.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`number`| `600`
|
||
|
||
###### Example: Apply an animation duration of 200ms to all mixitup animations
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
duration: 200
|
||
}
|
||
});
|
||
```
|
||
### easing
|
||
|
||
|
||
|
||
|
||
A valid CSS3 transition-timing function or shorthand. For a full list of accepted
|
||
values, visit <a href="http://easings.net" target="_blank">easings.net</a>.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'ease'`
|
||
|
||
###### Example 1: Apply "ease-in-out" easing to all animations
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
easing: 'ease-in-out'
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Apply a custom "cubic-bezier" easing function to all animations
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
easing: 'cubic-bezier(0.645, 0.045, 0.355, 1)'
|
||
}
|
||
});
|
||
```
|
||
### applyPerspective
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to apply perspective to the MixItUp container
|
||
during animations. By default, perspective is always applied and creates the
|
||
illusion of three-dimensional space for effects such as `translateZ`, `rotateX`,
|
||
and `rotateY`.
|
||
|
||
You may wish to disable this and define your own perspective settings via CSS.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`bolean`| `true`
|
||
|
||
###### Example: Prevent perspective from being applied to any 3D transforms
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
applyPerspective: false
|
||
}
|
||
});
|
||
```
|
||
### perspectiveDistance
|
||
|
||
|
||
|
||
|
||
The perspective distance value to be applied to the container during animations,
|
||
affecting any 3D-transform-based effects.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'3000px'`
|
||
|
||
###### Example: Set a perspective distance of 2000px
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'rotateY(-25deg)',
|
||
perspectiveDistance: '2000px'
|
||
}
|
||
});
|
||
```
|
||
### perspectiveOrigin
|
||
|
||
|
||
|
||
|
||
The perspective-origin value to be applied to the container during animations,
|
||
affecting any 3D-transform-based effects.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'50% 50%'`
|
||
|
||
###### Example: Set a perspective origin in the top-right of the container
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'transateZ(-200px)',
|
||
perspectiveOrigin: '100% 0'
|
||
}
|
||
});
|
||
```
|
||
### queue
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to enable the queuing of operations.
|
||
|
||
If `true` (default), and a control is clicked or an API call is made while another
|
||
operation is progress, the operation will go into the queue and will be automatically exectuted
|
||
when the previous operaitons is finished.
|
||
|
||
If `false`, any requested operations will be ignored, and the `onMixBusy` callback and `mixBusy`
|
||
event will be fired. If `debug.showWarnings` is enabled, a console warning will also occur.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Disable queuing
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
queue: false
|
||
}
|
||
});
|
||
```
|
||
### queueLimit
|
||
|
||
|
||
|
||
|
||
An integer dictacting the maximum number of operations allowed in the queue at
|
||
any time, when queuing is enabled.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`number`| `3`
|
||
|
||
###### Example: Allow a maximum of 5 operations in the queue at any time
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
queueLimit: 5
|
||
}
|
||
});
|
||
```
|
||
### animateResizeContainer
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to transition the height and width of the
|
||
container as elements are filtered in and out. If disabled, the container height
|
||
will change abruptly.
|
||
|
||
It may be desirable to disable this on mobile devices as the CSS `height` and
|
||
`width` properties do not receive GPU-acceleration and can therefore cause stuttering.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example 1: Disable the transitioning of the container height and/or width
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
animateResizeContainer: false
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Disable the transitioning of the container height and/or width for mobile devices only
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
animateResizeContainer: myFeatureTests.isMobile ? false : true
|
||
}
|
||
});
|
||
```
|
||
### animateResizeTargets
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to transition the height and width of target
|
||
elements as they change throughout the course of an animation.
|
||
|
||
This is often a must for flex-box grid layouts where the size of target elements may change
|
||
depending on final their position in relation to their siblings, or for `.changeLayout()`
|
||
operations where the size of targets change between layouts.
|
||
|
||
NB: This feature requires additional calculations and manipulation to non-hardware-accelerated
|
||
properties which may adversely affect performance on slower devices, and is therefore
|
||
disabled by default.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `false`
|
||
|
||
###### Example: Enable the transitioning of target widths and heights
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
animateResizeTargets: true
|
||
}
|
||
});
|
||
```
|
||
### staggerSequence
|
||
|
||
|
||
|
||
|
||
A custom function used to manipulate the order in which the stagger delay is
|
||
incremented when using the ‘stagger’ effect.
|
||
|
||
When using the 'stagger' effect, the delay applied to each target element is incremented
|
||
based on its index. You may create a custom function to manipulate the order in which the
|
||
delay is incremented and create engaging non-linear stagger effects.
|
||
|
||
The function receives the index of the target element as a parameter, and must
|
||
return an integer which serves as the multiplier for the stagger delay.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example 1: Stagger target elements by column in a 3-column grid
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'fade stagger(100ms)',
|
||
staggerSequence: function(i) {
|
||
return i % 3;
|
||
}
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Using an algorithm to produce a more complex sequence
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'fade stagger(100ms)',
|
||
staggerSequence: function(i) {
|
||
return (2*i) - (5*((i/3) - ((1/3) * (i%3))));
|
||
}
|
||
}
|
||
});
|
||
```
|
||
### reverseOut
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to reverse the direction of `translate`
|
||
and `rotate` transforms for elements being filtered out.
|
||
|
||
It can be used to create carousel-like animations where elements enter and exit
|
||
from opposite directions. If enabled, the effect `translateX(-100%)` for elements
|
||
being filtered in would become `translateX(100%)` for targets being filtered out.
|
||
|
||
This functionality can also be achieved by providing seperate effects
|
||
strings for `config.animation.effectsIn` and `config.animation.effectsOut`.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `false`
|
||
|
||
###### Example: Reverse the desired direction on any translate/rotate effect for targets being filtered out
|
||
|
||
```js
|
||
// Elements being filtered in will be translated from '100%' to '0' while
|
||
// elements being filtered out will be translated from 0 to '-100%'
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
effects: 'fade translateX(100%)',
|
||
reverseOut: true,
|
||
nudge: false // Disable nudging to create a carousel-like effect
|
||
}
|
||
});
|
||
```
|
||
### nudge
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to "nudge" the animation path of targets
|
||
when they are being filtered in and out simulatenously.
|
||
|
||
This has been the default behavior of MixItUp since version 1, but it
|
||
may be desirable to disable this effect when filtering directly from
|
||
one exclusive set of targets to a different exclusive set of targets,
|
||
to create a carousel-like effect, or a generally more subtle animation.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Disable the "nudging" of targets being filtered in and out simulatenously
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
nudge: false
|
||
}
|
||
});
|
||
```
|
||
### clampHeight
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to clamp the height of the container while MixItUp's
|
||
geometry tests are carried out before an operation.
|
||
|
||
To prevent scroll-bar flicker, clamping is turned on by default. But in the case where the
|
||
height of the container might affect its vertical positioning in the viewport
|
||
(e.g. a vertically-centered container), this should be turned off to ensure accurate
|
||
test results and a smooth animation.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Disable container height-clamping
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
clampHeight: false
|
||
}
|
||
});
|
||
```
|
||
### clampWidth
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to clamp the width of the container while MixItUp's
|
||
geometry tests are carried out before an operation.
|
||
|
||
To prevent scroll-bar flicker, clamping is turned on by default. But in the case where the
|
||
width of the container might affect its horitzontal positioning in the viewport
|
||
(e.g. a horizontall-centered container), this should be turned off to ensure accurate
|
||
test results and a smooth animation.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Disable container width-clamping
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
animation: {
|
||
clampWidth: false
|
||
}
|
||
});
|
||
```
|
||
|
||
<h2 id="behavior">behavior</h2>
|
||
|
||
A group of properties relating to the behavior of the Mixer.
|
||
|
||
### liveSort
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether to allow "live" sorting of the mixer.
|
||
|
||
Because of the expensive nature of sorting, MixItUp makes use of several
|
||
internal optimizations to skip redundant sorting operations, such as when
|
||
the newly requested sort command is the same as the active one. The caveat
|
||
to this optimization is that "live" edits to the value of a target's sorting
|
||
attribute will be ignored when requesting a re-sort by the same attribute.
|
||
|
||
By setting to `behavior.liveSort` to `true`, the mixer will always re-sort
|
||
regardless of whether or not the sorting attribute and order have changed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `false`
|
||
|
||
###### Example: Enabling `liveSort` to allow for re-sorting
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
behavior: {
|
||
liveSort: true
|
||
},
|
||
load: {
|
||
sort: 'edited:desc'
|
||
}
|
||
});
|
||
|
||
var target = containerEl.children[3];
|
||
|
||
console.log(target.getAttribute('data-edited')); // '2015-04-24'
|
||
|
||
target.setAttribute('data-edited', '2017-08-10'); // Update the target's edited date
|
||
|
||
mixer.sort('edited:desc')
|
||
.then(function(state) {
|
||
// The target is now at the top of the list
|
||
|
||
console.log(state.targets[0] === target); // true
|
||
});
|
||
```
|
||
|
||
<h2 id="callbacks">callbacks</h2>
|
||
|
||
A group of optional callback functions to be invoked at various
|
||
points within the lifecycle of a mixer operation.
|
||
|
||
Each function is analogous to an event of the same name triggered from the
|
||
container element, and is invoked immediately after it.
|
||
|
||
All callback functions receive the current `state` object as their first
|
||
argument, as well as other more specific arguments described below.
|
||
|
||
### onMixStart
|
||
|
||
|
||
|
||
|
||
A callback function invoked immediately after any MixItUp operation is requested
|
||
and before animations have begun.
|
||
|
||
A second `futureState` argument is passed to the function which represents the final
|
||
state of the mixer once the requested operation has completed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example: Adding an `onMixStart` callback function
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixStart: function(state, futureState) {
|
||
console.log('Starting operation...');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
### onMixBusy
|
||
|
||
|
||
|
||
|
||
A callback function invoked when a MixItUp operation is requested while another
|
||
operation is in progress, and the animation queue is full, or queueing
|
||
is disabled.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example: Adding an `onMixBusy` callback function
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixBusy: function(state) {
|
||
console.log('Mixer busy');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
### onMixEnd
|
||
|
||
|
||
|
||
|
||
A callback function invoked after any MixItUp operation has completed, and the
|
||
state has been updated.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example: Adding an `onMixEnd` callback function
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixEnd: function(state) {
|
||
console.log('Operation complete');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
### onMixFail
|
||
|
||
|
||
|
||
|
||
A callback function invoked whenever an operation "fails", i.e. no targets
|
||
could be found matching the requested filter.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example: Adding an `onMixFail` callback function
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixFail: function(state) {
|
||
console.log('No items could be found matching the requested filter');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
### onMixClick
|
||
|
||
|
||
|
||
|
||
A callback function invoked whenever a MixItUp control is clicked, and before its
|
||
respective operation is requested.
|
||
|
||
The clicked element is assigned to the `this` keyword within the function. The original
|
||
click event is passed to the function as the second argument, which can be useful if
|
||
using `<a>` tags as controls where the default behavior needs to be prevented.
|
||
|
||
Returning `false` from the callback will prevent the control click from triggering
|
||
an operation.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `null`
|
||
|
||
###### Example 1: Adding an `onMixClick` callback function
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixClick: function(state, originalEvent) {
|
||
console.log('The control "' + this.innerText + '" was clicked');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Using `onMixClick` to manipulate the original click event
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixClick: function(state, originalEvent) {
|
||
// Prevent original click event from bubbling up:
|
||
originalEvent.stopPropagation();
|
||
|
||
// Prevent default behavior of clicked element:
|
||
originalEvent.preventDefault();
|
||
}
|
||
}
|
||
});
|
||
```
|
||
###### Example 3: Using `onMixClick` to conditionally cancel operations
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
callbacks: {
|
||
onMixClick: function(state, originalEvent) {
|
||
// Perform some conditional check:
|
||
|
||
if (myApp.isLoading) {
|
||
// By returning false, we can prevent the control click from triggering an operation.
|
||
|
||
return false;
|
||
}
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
<h2 id="controls">controls</h2>
|
||
|
||
A group of properties relating to clickable control elements.
|
||
|
||
### enable
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not controls should be enabled for the mixer instance.
|
||
|
||
If `true` (default behavior), MixItUp will search the DOM for any clickable elements with
|
||
`data-filter`, `data-sort` or `data-toggle` attributes, and bind them for click events.
|
||
|
||
If `false`, no click handlers will be bound, and all functionality must therefore be performed
|
||
via the mixer's API methods.
|
||
|
||
If you do not intend to use the default controls, setting this property to `false` will
|
||
marginally improve the startup time of your mixer instance, and will also prevent any other active
|
||
mixer instances in the DOM which are bound to controls from controlling the instance.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Disabling controls
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
controls: {
|
||
enable: false
|
||
}
|
||
});
|
||
|
||
// With the default controls disabled, we can only control
|
||
// the mixer via its API methods, e.g.:
|
||
|
||
mixer.filter('.cat-1');
|
||
```
|
||
### live
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not to use event delegation when binding click events
|
||
to the default controls.
|
||
|
||
If `false` (default behavior), each control button in the DOM will be found and
|
||
individually bound when a mixer is instantiated, with their corresponding actions
|
||
cached for performance.
|
||
|
||
If `true`, a single click handler will be applied to the `window` (or container element - see
|
||
`config.controls.scope`), and any click events triggered by elements with `data-filter`,
|
||
`data-sort` or `data-toggle` attributes present will be handled as they propagate upwards.
|
||
|
||
If you require a user interface where control buttons may be added, removed, or changed during the
|
||
lifetime of a mixer, `controls.live` should be set to `true`. There is a marginal but unavoidable
|
||
performance deficit when using live controls, as the value of each control button must be read
|
||
from the DOM in real time once the click event has propagated.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Setting live controls
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
controls: {
|
||
live: true
|
||
}
|
||
});
|
||
|
||
// Control buttons can now be added, remove and changed without breaking
|
||
// the mixer's UI
|
||
```
|
||
### scope
|
||
|
||
|
||
|
||
|
||
A string dictating the "scope" to use when binding or querying the default controls. The available
|
||
values are `'global'` or `'local'`.
|
||
|
||
When set to `'global'` (default behavior), MixItUp will query the entire document for control buttons
|
||
to bind, or delegate click events from (see `config.controls.live`).
|
||
|
||
When set to `'local'`, MixItUp will only query (or bind click events to) its own container element.
|
||
This may be desireable if you require multiple active mixer instances within the same document, with
|
||
controls that would otherwise intefere with each other if scoped globally.
|
||
|
||
Conversely, if you wish to control multiple instances with a single UI, you would create one
|
||
set of controls and keep the controls scope of each mixer set to `global`.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'global'`
|
||
|
||
###### Example: Setting 'local' scoped controls
|
||
|
||
```js
|
||
var mixerOne = mixitup(containerOne, {
|
||
controls: {
|
||
scope: 'local'
|
||
}
|
||
});
|
||
|
||
var mixerTwo = mixitup(containerTwo, {
|
||
controls: {
|
||
scope: 'local'
|
||
}
|
||
});
|
||
|
||
// Both mixers can now exist within the same document with
|
||
// isolated controls placed within their container elements.
|
||
```
|
||
### toggleLogic
|
||
|
||
|
||
|
||
|
||
A string dictating the type of logic to apply when concatenating the filter selectors of
|
||
active toggle buttons (i.e. any clickable element with a `data-toggle` attribute).
|
||
|
||
If set to `'or'` (default behavior), selectors will be concatenated together as
|
||
a comma-seperated list. For example:
|
||
|
||
`'.cat-1, .cat-2'` (shows any elements matching `'.cat-1'` OR `'.cat-2'`)
|
||
|
||
If set to `'and'`, selectors will be directly concatenated together. For example:
|
||
|
||
`'.cat-1.cat-2'` (shows any elements which match both `'.cat-1'` AND `'.cat-2'`)
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'or'`
|
||
|
||
###### Example: Setting "and" toggle logic
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
controls: {
|
||
toggleLogic: 'and'
|
||
}
|
||
});
|
||
```
|
||
### toggleDefault
|
||
|
||
|
||
|
||
|
||
A string dictating the filter behavior when all toggles are inactive.
|
||
|
||
When set to `'all'` (default behavior), *all* targets will be shown by default
|
||
when no toggles are active, or at the moment all active toggles are toggled off.
|
||
|
||
When set to `'none'`, no targets will be shown by default when no toggles are
|
||
active, or at the moment all active toggles are toggled off.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'all'`
|
||
|
||
###### Example 1: Setting the default toggle behavior to `'all'`
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
controls: {
|
||
toggleDefault: 'all'
|
||
}
|
||
});
|
||
|
||
mixer.toggleOn('.cat-2')
|
||
.then(function() {
|
||
// Deactivate all active toggles
|
||
|
||
return mixer.toggleOff('.cat-2')
|
||
})
|
||
.then(function(state) {
|
||
console.log(state.activeFilter.selector); // 'all'
|
||
console.log(state.totalShow); // 12
|
||
});
|
||
```
|
||
###### Example 2: Setting the default toggle behavior to `'none'`
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
controls: {
|
||
toggleDefault: 'none'
|
||
}
|
||
});
|
||
|
||
mixer.toggleOn('.cat-2')
|
||
.then(function() {
|
||
// Deactivate all active toggles
|
||
|
||
return mixer.toggleOff('.cat-2')
|
||
})
|
||
.then(function(state) {
|
||
console.log(state.activeFilter.selector); // 'none'
|
||
console.log(state.totalShow); // 0
|
||
});
|
||
```
|
||
|
||
<h2 id="classNames">classNames</h2>
|
||
|
||
A group of properties defining the output and structure of class names programmatically
|
||
added to controls and containers to reflect the state of the mixer.
|
||
|
||
Most commonly, class names are added to controls by MixItUp to indicate that
|
||
the control is active so that it can be styled accordingly - `'mixitup-control-active'` by default.
|
||
|
||
Using a "BEM" like structure, each classname is broken into the three parts:
|
||
a block namespace (`'mixitup'`), an element name (e.g. `'control'`), and an optional modifier
|
||
name (e.g. `'active'`) reflecting the state of the element.
|
||
|
||
By default, each part of the classname is concatenated together using single hyphens as
|
||
delineators, but this can be easily customised to match the naming convention and style of
|
||
your project.
|
||
|
||
### block
|
||
|
||
|
||
|
||
|
||
The "block" portion, or top-level namespace added to the start of any class names created by MixItUp.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'mixitup'`
|
||
|
||
###### Example 1: changing the `config.classNames.block` value
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: 'portfolio'
|
||
}
|
||
});
|
||
|
||
// Active control output: "portfolio-control-active"
|
||
```
|
||
###### Example 2: Removing `config.classNames.block`
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: ''
|
||
}
|
||
});
|
||
|
||
// Active control output: "control-active"
|
||
```
|
||
### elementContainer
|
||
|
||
|
||
|
||
|
||
The "element" portion of the class name added to container.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'container'`
|
||
|
||
### elementFilter
|
||
|
||
|
||
|
||
|
||
The "element" portion of the class name added to filter controls.
|
||
|
||
By default, all filter, sort, multimix and toggle controls take the same element value of `'control'`, but
|
||
each type's element value can be individually overwritten to match the unique classNames of your controls as needed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'control'`
|
||
|
||
###### Example 1: changing the `config.classNames.elementFilter` value
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
elementFilter: 'filter'
|
||
}
|
||
});
|
||
|
||
// Active filter output: "mixitup-filter-active"
|
||
```
|
||
###### Example 2: changing the `config.classNames.block` and `config.classNames.elementFilter` values
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: 'portfolio',
|
||
elementFilter: 'filter'
|
||
}
|
||
});
|
||
|
||
// Active filter output: "portfolio-filter-active"
|
||
```
|
||
### elementSort
|
||
|
||
|
||
|
||
|
||
The "element" portion of the class name added to sort controls.
|
||
|
||
By default, all filter, sort, multimix and toggle controls take the same element value of `'control'`, but
|
||
each type's element value can be individually overwritten to match the unique classNames of your controls as needed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'control'`
|
||
|
||
###### Example 1: changing the `config.classNames.elementSort` value
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
elementSort: 'sort'
|
||
}
|
||
});
|
||
|
||
// Active sort output: "mixitup-sort-active"
|
||
```
|
||
###### Example 2: changing the `config.classNames.block` and `config.classNames.elementSort` values
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: 'portfolio',
|
||
elementSort: 'sort'
|
||
}
|
||
});
|
||
|
||
// Active sort output: "portfolio-sort-active"
|
||
```
|
||
### elementMultimix
|
||
|
||
|
||
|
||
|
||
The "element" portion of the class name added to multimix controls.
|
||
|
||
By default, all filter, sort, multimix and toggle controls take the same element value of `'control'`, but
|
||
each type's element value can be individually overwritten to match the unique classNames of your controls as needed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'control'`
|
||
|
||
###### Example 1: changing the `config.classNames.elementMultimix` value
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
elementMultimix: 'multimix'
|
||
}
|
||
});
|
||
|
||
// Active multimix output: "mixitup-multimix-active"
|
||
```
|
||
###### Example 2: changing the `config.classNames.block` and `config.classNames.elementMultimix` values
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: 'portfolio',
|
||
elementSort: 'multimix'
|
||
}
|
||
});
|
||
|
||
// Active multimix output: "portfolio-multimix-active"
|
||
```
|
||
### elementToggle
|
||
|
||
|
||
|
||
|
||
The "element" portion of the class name added to toggle controls.
|
||
|
||
By default, all filter, sort, multimix and toggle controls take the same element value of `'control'`, but
|
||
each type's element value can be individually overwritten to match the unique classNames of your controls as needed.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'control'`
|
||
|
||
###### Example 1: changing the `config.classNames.elementToggle` value
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
elementToggle: 'toggle'
|
||
}
|
||
});
|
||
|
||
// Active toggle output: "mixitup-toggle-active"
|
||
```
|
||
###### Example 2: changing the `config.classNames.block` and `config.classNames.elementToggle` values
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
block: 'portfolio',
|
||
elementToggle: 'toggle'
|
||
}
|
||
});
|
||
|
||
// Active toggle output: "portfolio-toggle-active"
|
||
```
|
||
### modifierActive
|
||
|
||
|
||
|
||
|
||
The "modifier" portion of the class name added to active controls.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'active'`
|
||
|
||
### modifierDisabled
|
||
|
||
|
||
|
||
|
||
The "modifier" portion of the class name added to disabled controls.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'disabled'`
|
||
|
||
### modifierFailed
|
||
|
||
|
||
|
||
|
||
The "modifier" portion of the class name added to the container when in a "failed" state.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'failed'`
|
||
|
||
### delineatorElement
|
||
|
||
|
||
|
||
|
||
The delineator used between the "block" and "element" portions of any class name added by MixItUp.
|
||
|
||
If the block portion is ommited by setting it to an empty string, no delineator will be added.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'-'`
|
||
|
||
###### Example: changing the delineator to match BEM convention
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
delineatorElement: '__'
|
||
}
|
||
});
|
||
|
||
// example active control output: "mixitup__control-active"
|
||
```
|
||
### delineatorModifier
|
||
|
||
|
||
|
||
|
||
The delineator used between the "element" and "modifier" portions of any class name added by MixItUp.
|
||
|
||
If the element portion is ommited by setting it to an empty string, no delineator will be added.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'-'`
|
||
|
||
###### Example: changing both delineators to match BEM convention
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
classNames: {
|
||
delineatorElement: '__'
|
||
delineatorModifier: '--'
|
||
}
|
||
});
|
||
|
||
// Active control output: "mixitup__control--active"
|
||
```
|
||
|
||
<h2 id="data">data</h2>
|
||
|
||
A group of properties relating to MixItUp's dataset API.
|
||
|
||
### uidKey
|
||
|
||
|
||
|
||
|
||
A string specifying the name of the key containing your data model's unique
|
||
identifier (UID). To use the dataset API, a UID key must be specified and
|
||
be present and unique on all objects in the dataset you provide to MixItUp.
|
||
|
||
For example, if your dataset is made up of MongoDB documents, the UID
|
||
key would be `'id'` or `'_id'`.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `''`
|
||
|
||
###### Example: Setting the UID to `'id'`
|
||
|
||
```js
|
||
var mixer = mixitup(containerEl, {
|
||
data: {
|
||
uidKey: 'id'
|
||
}
|
||
});
|
||
```
|
||
### dirtyCheck
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not MixItUp should "dirty check" each object in
|
||
your dataset for changes whenever `.dataset()` is called, and re-render any targets
|
||
for which a change is found.
|
||
|
||
Depending on the complexity of your data model, dirty checking can be expensive
|
||
and is therefore disabled by default.
|
||
|
||
NB: For changes to be detected, a new immutable instance of the edited model must be
|
||
provided to mixitup, rather than manipulating properties on the existing instance.
|
||
If your changes are a result of a DB write and read, you will most likely be calling
|
||
`.dataset()` with a clean set of objects each time, so this will not be an issue.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `false`
|
||
|
||
###### Example: Enabling dirty checking
|
||
|
||
```js
|
||
|
||
var myDataset = [
|
||
{
|
||
id: 0,
|
||
title: "Blog Post Title 0"
|
||
...
|
||
},
|
||
{
|
||
id: 1,
|
||
title: "Blog Post Title 1"
|
||
...
|
||
}
|
||
];
|
||
|
||
// Instantiate a mixer with a pre-loaded dataset, and a target renderer
|
||
// function defined
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
data: {
|
||
uidKey: 'id',
|
||
dirtyCheck: true
|
||
},
|
||
load: {
|
||
dataset: myDataset
|
||
},
|
||
render: {
|
||
target: function() { ... }
|
||
}
|
||
});
|
||
|
||
// For illustration, we will clone and edit the second object in the dataset.
|
||
// NB: this would typically be done server-side in response to a DB update,
|
||
and then re-queried via an API.
|
||
|
||
myDataset[1] = Object.assign({}, myDataset[1]);
|
||
|
||
myDataset[1].title = 'Blog Post Title 11';
|
||
|
||
mixer.dataset(myDataset)
|
||
.then(function() {
|
||
// the target with ID "1", will be re-rendered reflecting its new title
|
||
});
|
||
```
|
||
|
||
<h2 id="debug">debug</h2>
|
||
|
||
A group of properties allowing the toggling of various debug features.
|
||
|
||
### enable
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not the mixer instance returned by the
|
||
`mixitup()` factory function should expose private properties and methods.
|
||
|
||
By default, mixer instances only expose their public API, but enabling
|
||
debug mode will give you access to various mixer internals which may aid
|
||
in debugging, or the authoring of extensions.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `false`
|
||
|
||
###### Example: Enabling debug mode
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
debug: {
|
||
enable: true
|
||
}
|
||
});
|
||
|
||
// Private properties and methods will now be visible on the mixer instance:
|
||
|
||
console.log(mixer);
|
||
```
|
||
### showWarnings
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not warnings should be shown when various
|
||
common gotchas occur.
|
||
|
||
Warnings are intended to provide insights during development when something
|
||
occurs that is not a fatal, but may indicate an issue with your integration,
|
||
and are therefore turned on by default. However, you may wish to disable
|
||
them in production.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example 1: Disabling warnings
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
debug: {
|
||
showWarnings: false
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Disabling warnings based on environment
|
||
|
||
```js
|
||
|
||
var showWarnings = myAppConfig.environment === 'development' ? true : false;
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
debug: {
|
||
showWarnings: showWarnings
|
||
}
|
||
});
|
||
```
|
||
|
||
<h2 id="layout">layout</h2>
|
||
|
||
A group of properties relating to the layout of the container.
|
||
|
||
### allowNestedTargets
|
||
|
||
|
||
|
||
|
||
A boolean dictating whether or not mixitup should query all descendants
|
||
of the container for targets, or only immediate children.
|
||
|
||
By default, mixitup will query all descendants matching the
|
||
`selectors.target` selector when indexing targets upon instantiation.
|
||
This allows for targets to be nested inside a sub-container which is
|
||
useful when ring-fencing targets from locally scoped controls in your
|
||
markup (see `controls.scope`).
|
||
|
||
However, if you are building a more complex UI requiring the nesting
|
||
of mixers within mixers, you will most likely want to limit targets to
|
||
immediate children of the container by setting this property to `false`.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`boolean`| `true`
|
||
|
||
###### Example: Restricting targets to immediate children
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
layout: {
|
||
allowNestedTargets: false
|
||
}
|
||
});
|
||
```
|
||
### containerClassName
|
||
|
||
|
||
|
||
|
||
A string specifying an optional class name to apply to the container when in
|
||
its default state.
|
||
|
||
By changing this class name or adding a class name to the container via the
|
||
`.changeLayout()` API method, the CSS layout of the container can be changed,
|
||
and MixItUp will attemp to gracefully animate the container and its targets
|
||
between states.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `''`
|
||
|
||
###### Example 1: Specifying a container class name
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
layout: {
|
||
containerClassName: 'grid'
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Changing the default class name with `.changeLayout()`
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
layout: {
|
||
containerClassName: 'grid'
|
||
}
|
||
});
|
||
|
||
mixer.changeLayout('list')
|
||
.then(function(state) {
|
||
console.log(state.activeContainerClass); // "list"
|
||
});
|
||
```
|
||
### siblingBefore
|
||
|
||
|
||
|
||
|
||
A reference to a non-target sibling element after which to insert targets
|
||
when there are no targets in the container.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`HTMLElement`| `null`
|
||
|
||
###### Example: Setting a `siblingBefore` reference element
|
||
|
||
```js
|
||
|
||
var addButton = containerEl.querySelector('button');
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
layout: {
|
||
siblingBefore: addButton
|
||
}
|
||
});
|
||
```
|
||
### siblingAfter
|
||
|
||
|
||
|
||
|
||
A reference to a non-target sibling element before which to insert targets
|
||
when there are no targets in the container.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`HTMLElement`| `null`
|
||
|
||
###### Example: Setting an `siblingAfter` reference element
|
||
|
||
```js
|
||
|
||
var gap = containerEl.querySelector('.gap');
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
layout: {
|
||
siblingAfter: gap
|
||
}
|
||
});
|
||
```
|
||
|
||
<h2 id="load">load</h2>
|
||
|
||
A group of properties defining the initial state of the mixer on load (instantiation).
|
||
|
||
### filter
|
||
|
||
|
||
|
||
|
||
A string defining any filtering to be statically applied to the mixer on load.
|
||
As per the `.filter()` API, this can be any valid selector string, or the
|
||
values `'all'` or `'none'`.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'all'`
|
||
|
||
###### Example 1: Defining an initial filter selector to be applied on load
|
||
|
||
```js
|
||
|
||
// The mixer will show only those targets matching '.category-a' on load.
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
load: {
|
||
filter: '.category-a'
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Hiding all targets on load
|
||
|
||
```js
|
||
|
||
// The mixer will show hide all targets on load.
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
load: {
|
||
filter: 'none'
|
||
}
|
||
});
|
||
```
|
||
### sort
|
||
|
||
|
||
|
||
|
||
A string defining any sorting to be statically applied to the mixer on load.
|
||
As per the `.sort()` API, this should be a valid "sort string" made up of
|
||
an attribute to sort by (or `'default'`) followed by an optional sorting
|
||
order, or the value `'random'`;
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'default:asc'`
|
||
|
||
###### Example: Defining sorting to be applied on load
|
||
|
||
```js
|
||
|
||
// The mixer will sort the container by the value of the `data-published-date`
|
||
// attribute, in descending order.
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
load: {
|
||
sort: 'published-date:desc'
|
||
}
|
||
});
|
||
```
|
||
### dataset
|
||
|
||
|
||
|
||
|
||
An array of objects representing the underlying data of any pre-rendered targets,
|
||
when using the `.dataset()` API.
|
||
|
||
NB: If targets are pre-rendered when the mixer is instantiated, this must be set.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`Array.<object>`| `null`
|
||
|
||
###### Example: Defining the initial underyling dataset
|
||
|
||
```js
|
||
|
||
var myDataset = [
|
||
{
|
||
id: 0,
|
||
title: "Blog Post Title 0",
|
||
...
|
||
},
|
||
{
|
||
id: 1,
|
||
title: "Blog Post Title 1",
|
||
...
|
||
}
|
||
];
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
data: {
|
||
uidKey: 'id'
|
||
},
|
||
load: {
|
||
dataset: myDataset
|
||
}
|
||
});
|
||
```
|
||
|
||
<h2 id="selectors">selectors</h2>
|
||
|
||
A group of properties defining the selectors used to query elements within a mixitup container.
|
||
|
||
### target
|
||
|
||
|
||
|
||
|
||
A selector string used to query and index target elements within the container.
|
||
|
||
By default, the class selector `'.mix'` is used, but this can be changed to an
|
||
attribute or element selector to match the style of your project.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `'.mix'`
|
||
|
||
###### Example 1: Changing the target selector
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
selectors: {
|
||
target: '.portfolio-item'
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Using an attribute selector as a target selector
|
||
|
||
```js
|
||
|
||
// The mixer will search for any children with the attribute `data-ref="mix"`
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
selectors: {
|
||
target: '[data-ref="mix"]'
|
||
}
|
||
});
|
||
```
|
||
### control
|
||
|
||
|
||
|
||
|
||
A optional selector string used to add further specificity to the querying of control elements,
|
||
in addition to their mandatory data attribute (e.g. `data-filter`, `data-toggle`, `data-sort`).
|
||
|
||
This can be used if other elements in your document must contain the above attributes
|
||
(e.g. for use in third-party scripts), and would otherwise interfere with MixItUp. Adding
|
||
an additional `control` selector of your choice allows MixItUp to restrict event handling
|
||
to only those elements matching the defined selector.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`string`| `''`
|
||
|
||
###### Example 1: Adding a `selectors.control` selector
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
selectors: {
|
||
control: '.mixitup-control'
|
||
}
|
||
});
|
||
|
||
// Will not be handled:
|
||
// <button data-filter=".category-a"></button>
|
||
|
||
// Will be handled:
|
||
// <button class="mixitup-control" data-filter=".category-a"></button>
|
||
```
|
||
|
||
<h2 id="render">render</h2>
|
||
|
||
A group of optional render functions for creating and updating elements.
|
||
|
||
All render functions receive a data object, and should return a valid HTML string.
|
||
|
||
### target
|
||
|
||
|
||
|
||
|
||
A function returning an HTML string representing a target element, or a reference to a
|
||
single DOM element.
|
||
|
||
The function is invoked as part of the `.dataset()` API, whenever a new item is added
|
||
to the dataset, or an item in the dataset changes (if `dataset.dirtyCheck` is enabled).
|
||
|
||
The function receives the relevant dataset item as its first parameter.
|
||
|
||
|
||
|Type | Default
|
||
|--- | ---
|
||
|`function`| `'null'`
|
||
|
||
###### Example 1: Using string concatenation
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
render: {
|
||
target: function(item) {
|
||
return (
|
||
'<div class="mix">' +
|
||
'<h2>' + item.title + '</h2>' +
|
||
'</div>'
|
||
);
|
||
}
|
||
}
|
||
});
|
||
```
|
||
###### Example 2: Using an ES2015 template literal
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
render: {
|
||
target: function(item) {
|
||
return (
|
||
`<div class="mix">
|
||
<h2>${item.title}</h2>
|
||
</div>`
|
||
);
|
||
}
|
||
}
|
||
});
|
||
```
|
||
###### Example 3: Using a Handlebars template
|
||
|
||
```js
|
||
|
||
var targetTemplate = Handlebars.compile('<div class="mix"><h2>{{title}}</h2></div>');
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
render: {
|
||
target: targetTemplate
|
||
}
|
||
});
|
||
```
|
||
###### Example 4: Returning a DOM element
|
||
|
||
```js
|
||
|
||
var mixer = mixitup(containerEl, {
|
||
render: {
|
||
target: function(item) {
|
||
// Create a single element using your framework's built-in renderer
|
||
|
||
var el = ...
|
||
|
||
return el;
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|