0.1.5 • Published 8 years ago
tracky v0.1.5
tracky.js
tracky.js is a helper streamlining user interaction into css-classes. This means tracky transforms user interaction like scrolling, device orientation changes or cursor movements on defined breakpoints into css classes.
Install && Getting started
Installation
npm install tracky --saveExample ES2015:
import Tracky from 'tracky';
let bodyTracker = new Tracky('body', { options: 'example' });Example common.js:
let Tracky = require('tracky');
let bodyTracker = new Tracky('body', { options: 'example' });Example ES5:
<script src='../your-path-to-the-file/tracky/dist/tracky.min.js'><script>
var bodyTracker = new Tracky('body', { options: 'example' });
</script>Documentation
Tracky
Tracky( selector, { options } )
Arguments
- selector (String | Array | default: 'body') - selector or array of strings that fits into
querySelectAll(). - options (Object | default: null) - options for your Tracky instance
Returns
Tracky instance
Example
// apply trackers to body
new Tracky('body');
// apply trackers to .selector1 and .selector2
new Tracky(['.selector1', '.selector2']);
// apply trackers to any div with the default options
new Tracky('div', {
classPrefix: 'tracky-',
classSuffix: '',
classGtPrefix: 'gt-',
classLtPrefix: 'lt-',
classEqPrefix: 'eq-',
classBtPrefix: 'bt-',
events: {
scroll: {
enable: false,
breakpoints: []
},
edge: {
enable: false,
breakpoints: []
},
orientation: {
enable: false,
breakpoints: []
}
}
});Tracky.addSelector()
Adds one or many selector to the existing selectors and attach events.
.addSelector( selector )
Arguments
- selector (String | Array) - selector or array of strings that fits into
querySelectAll().
Returns
Tracky instance
Example
// apply trackers to body
let t = new Tracky('body');
// add .selector1 and .selector2
t.addSelector(['.selector1', '.selector2']);
// add #single-selector
t.addSelector('#single-selector');Tracky.removeSelector()
Removes one or many selector from the existing selectors and unbind events.
.removeSelector( selector )
Arguments
- selector (String | Array) - selector or array of selectors that are currently added to the instance.
Returns
Tracky instance
Example
// apply trackers
let t = new Tracky(['body','.s2','.s3','#s4']);
// remove .s2 and .s3
t.removeSelector(['.s2', '.s3']);
// remove #s4
t.removeSelector('#s4');Tracky.disable()
Disables a given tracker and unbind the event listeners.
.disable( tracker )
Arguments
- tracker (String) - tracker as a string that is currently enabled.
Returns
Tracky instance
Example
// apply events to body
let t = new Tracky(['body'], {
events : {
scroll : {
enable: true,
breakpoints: [255, '99%']
}
}
});
// disabling scroll events
t.disable('scroll');Tracky.enable()
Enables a given event and unbind the event listeners.
.enable( tracker )
Arguments
- tracker (String) - tracker as a string from the listeners.
Returns
Tracky instance
Example
// apply events to body
let t = new Tracky(['body'], {
events : {
orientation : {
enable: false,
breakpoints: [255, '99%']
}
}
});
// enabling orientation events
t.enable('orientation');Event Options
scroll
Tracks horizontal and vertical scroll.
(Notice: console recording and demo above are not synced)
Default classNames
If no custom css class-name is defined. Tracky creates a unique name by the given values by default. Note that the %-digit will be replaced by 'pc' (percent).
// value: [value]
[options.classPrefix]['scroll'][options.classLtPrefix][value][options.classSuffix] // when lower than [value]
[options.classPrefix]['scroll'][options.classGtPrefix][value][options.classSuffix] // when greater than [value]
[options.classPrefix]['scroll'][options.classEqPrefix][value][options.classSuffix] // when equal than [value]// value: { min, max } // as a range
[options.classPrefix]['scroll'][options.classBtPrefix]{min}['-']{max}[options.classSuffix] // when between {min} and {max}// value: 50
tracky-scroll-lt-50 // when lower than 50px
tracky-scroll-gt-50 // when greater than 50px
tracky-scroll-eq-50 // when equal than 50px// value: 77%
tracky-scroll-lt-77pc // when lower than 77%
tracky-scroll-gt-77pc // when greater than 77%
tracky-scroll-eq-77pc // when equal than 77%// min: 5% / max: 200
tracky-scroll-bt-5pc-200 // when between 5% and 200 pixelExample configuration:
{
events: {
scroll: {
/* Enable the scroll tracker */
enable: true,
/* Array with breakpoints */
breakpoints: [
/* Breakpoints can be set as a single number */
0,
/* Breakpoint can be set as percentage */
'50%',
/* Breakpoint set as object with property value given */
{value: '99%'},
/* Breakpoint set as object with min and max property */
{min: 60, max: '40%'},
/* CSS class as a string will be applied when between 40% and 60% */
{
css: 'element-scroll-is-in-range',
min: '40%',
max: '60%'
},
/* complex custom breakpoint example */
{
/* css as an object */
css: {
/* class applied when scroll < value */
lt: 'this-is-my-special-class-under-350',
/* class applied when scroll > value */
gt: 'this-is-my-special-class-over-350',
/* class applied when scroll === value */
eq: 'this-is-my-special-class-at-350'
},
/* scroll direction measured ['x' | 'y'] (x = horizontal / y = vertical) (Default: 'y') */
axis: 'x',
/* Breakpoint as value */
value: 350,
/* Callback when 'eq' -> scroll === value | min-max-range */
onMatch: function () {
console.log('wow, this was a 350px-scroll-match!');
},
/* Callback when scroll position does not match anymore */
onUnmatch: function () {
console.log('nope, this was not a 350px-scroll-match!');
},
/* Callback when scroll > value (fired only once per condition change) */
onGreater: function () {
console.log('aaaha... the scroll is greater than 350px');
},
/* Callback when scroll < value (fired only once condition change) */
onLower: function () {
console.log('huhuu... going low now? < 350px');
}
},
/* min-max-range example */
{
/* css as an object */
css: {
/* class applied when scroll >= min && scroll <= max */
/* lt / gt / eq do not work with a min and max range */
bt: 'this-is-my-special-class-match-range'
},
/* min value */
min: 15,
/* max value */
max: '60%'
}
]
}
}
}edge
Tracks mousemove on a certain area of an elements edge.
(Notice: console recording and demo above are not synced)
Default classNames
If no custom css class-name is defined. Tracky creates a unique name by the given values by default. Note that the %-digit will be replaced by 'pc' (percent).
// value: [value]
[options.classPrefix]['edge'][matchedPosition='top | right | bottom | left'][value][options.classSuffix]// in case of a corner the values will be combined
// value: [ y | x ]
[options.classPrefix]['edge'][matchedPosition='top-right | top-left | bottom-right | bottom-left'][value.y]['-'][value.x][options.classSuffix]// value: 50
tracky-edge-top-50 // when touches top
tracky-edge-right-50 // when touches right
tracky-edge-bottom-50 // when touches bottom
tracky-edge-left-50 // when touches left
tracky-edge-top-right-50-50 // when touches top-right
tracky-edge-top-left-50-50 // when touches top-left
tracky-edge-bottom-right-50-50 // when touches bottom right
tracky-edge-bottom-left-50-50 // when touches bottom left// value: [50,'25%',10,90]
tracky-edge-top-50 // when touches top
tracky-edge-right-25pc // when touches right
tracky-edge-bottom-10 // when touches bottom
tracky-edge-left-90 // when touches left
tracky-edge-top-right-50-25pc // when touches top-right
tracky-edge-top-left-50-90 // when touches top-left
tracky-edge-bottom-right-10-25pc // when touches bottom right
tracky-edge-bottom-left-10-90 // when touches bottom leftExample configuration object
{
events: {
edge: {
breakpoints: [
/* defines an edge area of 50 pixel */
50,
/* defines an edge area of 20 percent */
'20%',
/* defines an edge area as array */
/* of top: 18px right: 55px, bottom: 66%, left: 77px */
[18, 55, '66%', 77],
/* define an edge area with a more complex object */
{
css: {
/* class applied when cursor hits the top edge area */
top: 'edge-tracker-top',
/* class applied when cursor hits the right edge area */
right: 'edge-tracker-right',
/* class applied when cursor hits the bottom edge area */
bottom: 'edge-tracker-bottom',
/* class applied when cursor hits the left edge area */
left: 'edge-tracker-left',
/* class applied when cursor hits the overlapping coner of top and right edge area */
topRight: 'edge-tracker-top-right',
/* class applied when cursor hits the overlapping coner of top and left edge area */
topLeft: 'edge-tracker-top-left',
/* class applied when cursor hits the overlapping coner of bottom and right edge area */
bottomRight: 'edge-tracker-bottom-right',
/* class applied when cursor hits the overlapping coner of bottom and left edge area */
bottomLeft: 'edge-tracker-bottom-left',
},
/* value defines the edge area around the element */
value: '15%',
/* callback when cursor touches any edge area */
onMatch: function () {
console.log('cb: match');
},
/* callback when cursor has left any edge area */
onUnmatch: function () {
console.log('cb: mismatch');
},
/* callback when cursor touches top edge area */
onMatchTop: function () {
console.log('cb: match-top');
},
/* callback when cursor touches right edge area */
onMatchRight: function () {
console.log('cb: match-right');
},
/* callback when cursor touches bottom edge area */
onMatchBottom: function () {
console.log('cb: match-bottom');
},
/* callback when cursor touches left edge area */
onMatchLeft: function () {
console.log('cb: match-left');
},
/* callback when cursor touches top right corner */
onMatchTopRight: function () {
console.log('cb: match-top-right');
},
/* callback when cursor touches top left corner */
onMatchTopLeft: function () {
console.log('cb: match-top-left');
},
/* callback when cursor touches bottom right corner */
onMatchBottomRight: function () {
console.log('cb: match-bottom-right');
},
/* callback when cursor touches bottom left corner */
onMatchBottomLeft: function () {
console.log('cb: match-bottom-left');
},
/* callback when cursor left top edge */
onUnmatchTop: function () {
console.log('cb: un-match-top');
},
/* callback when cursor left right edge */
onUnmatchRight: function () {
console.log('cb: un-match-right');
},
/* callback when cursor left bottom edge */
onUnmatchBottom: function () {
console.log('cb: un-match-bottom');
},
/* callback when cursor left left edge */
onUnmatchLeft: function () {
console.log('cb: un-match-left');
},
/* callback when cursor left top right corner */
onUnmatchTopRight: function () {
console.log('cb: un-match-top-right');
},
/* callback when cursor left top left corner */
onUnmatchTopLeft: function () {
console.log('cb: un-match-top-left');
},
/* callback when cursor left bottom right corner */
onUnmatchBottomRight: function () {
console.log('cb: un-match-bottom-right');
},
/* callback when cursor left bottom left corner */
onUnmatchBottomLeft: function () {
console.log('cb: un-match-bottom-left');
}
},
/* define a value as an array of (top/right/buttom/left) */
{
value: [
'15%',
'88%',
45,
66
]
},
/* define a value as an object with specific areas */
{
value: {
top: 44,
right: 88,
bottom: '66%',
left: 99,
}
},
{
/* define css class as string will apply this class whenever an area is touched */
css: 'hit-any-edge',
/* define a value with an array of 2 elements will follow the css rules for padding/margin */
/* so this will autocomplete bottom and left like - top: 14px, right: 66px, bottom: 14px, left: 66px */
value: [14, 66]
}
]
}
}
}orientation
Tracks device orientation on x/y/z axis. Defined by the angle of alpha/beta/gamma. Values are in degree or percent.
(Notice: console recording and demo above are not synced)
Default classNames
If no custom css class-name is defined. Tracky creates a unique name by the given values by default. Note that the %-digit will be replaced by 'pc' (percent).
// value: [value]
[options.classPrefix]['orientation'][axis='alpha | beta | gamma'][direction='(empty) | left | right | up | down'][value][options.classSuffix]// value: 50
tracky-orientation-alpha-50 // when alpha > value
tracky-orientation-alpha-left-50 // when alpha > value && direction === left
tracky-orientation-alpha-right-50 // when alpha > value && direction === right
tracky-orientation-beta-50 // when alpha > value
tracky-orientation-beta-up-50 // when beta > value && direction === upwards
tracky-orientation-beta-down-50 // when beta > value && direction === downwards
tracky-orientation-gamma-50 // when gamma > value
tracky-orientation-gamma-left-50 // when gamma > value && direction === left
tracky-orientation-gamma-right-50 // when gamma > value && direction === right// value: [50,'25%',10]
tracky-orientation-alpha-50 // when alpha > value
tracky-orientation-alpha-left-50 // when alpha > value && direction === left
tracky-orientation-alpha-right-50 // when alpha > value && direction === right
tracky-orientation-beta-25pc // when alpha > value
tracky-orientation-beta-up-25pc // when beta > value && direction === upwards
tracky-orientation-beta-down-25pc // when beta > value && direction === downwards
tracky-orientation-gamma-10 // when gamma > value
tracky-orientation-gamma-left-10 // when gamma > value && direction === left
tracky-orientation-gamma-right-10 // when gamma > value && direction === rightExample configuration object
{
events: {
orientation: {
/* Enable the orientation tracker */
enable: true,
breakpoints: [
/* breakpoint as number will apply this value for alpha/beta/gamma */
50,
/* breakpoint as array with a length of 3 will deconstruct the values to alpha[0]/beta[1]/gamma[2] */
[18, 55, 66],
/* breakpoint as percent string will apply this value for alpha/beta/gamma - consider: */
/* alpha 100% = 360deg */
/* beta 100% = 180deg */
/* gamma 100% = 90deg */
'30%',
/* breakpoint values can be set as object with property alpha/beta/gamma */
{
value: {
alpha: 44,
beta: 88,
gamma: '66%',
}
},
/* breakpoint as complex object */
{
css: {
/* css class applied when alpha > value.alpha */
alpha: 'edge-tracker-alpha',
/* css class applied when beta > value.beta */
beta: 'edge-tracker-beta',
/* css class applied when gamma > value.gamma */
gamma: 'edge-tracker-gamma',
/* css class applied when alpha direction is heading left */
alphaLeft: 'edge-tracker-alpha-left',
/* css class applied when alpha direction is heading right */
alphaRight: 'edge-tracker-alpha-right',
/* css class applied when beta direction is heading downwards */
betaDown: 'edge-tracker-beta-down',
/* css class applied when beta direction is heading upwards */
betaUp: 'edge-tracker-beta-up',
/* css class applied when gamma direction is heading right */
gammaRight: 'edge-tracker-gamma-right',
/* css class applied when gamma direction is heading left */
gammaLeft: 'edge-tracker-gamma-left',
},
/* values set as array (alpha/beta/gamma) */
value: ['15%', 66, 99],
/* callback when any value matches the condition */
onMatch: function () {
console.log('cb: match');
},
/* callback when any value left condition */
onUnmatch: function () {
console.log('cb: mismatch');
},
/* callback when alpha value match the condition */
onMatchAlpha: function () {
console.log('cb: match-alpha');
},
/* callback when beta value match the condition */
onMatchBeta: function () {
console.log('cb: match-beta');
},
/* callback when gamma value match the condition */
onMatchGamma: function () {
console.log('cb: match-gamma');
},
/* callback when alpha value left the condition */
onUnmatchAlpha: function () {
console.log('cb: unmatch-alpha');
},
/* callback when beta value left the condition */
onUnmatchBeta: function () {
console.log('cb: un-match-beta');
},
/* callback when gamma value left the condition */
onUnmatchGamma: function () {
console.log('cb: un-match-gamma');
},
/* callback when alpha value match the condition and is heading left */
onMatchAlphaLeft: function () {
console.log('cb: match-alpha-left');
},
/* callback when alpha value match the condition and is heading right */
onMatchAlphaRight: function () {
console.log('cb: match-alpha-right');
},
/* callback when beta value match the condition and is heading upwards */
onMatchBetaUp: function () {
console.log('cb: match-beta-up');
},
/* callback when beta value match the condition and is heading downwards */
onMatchBetaDown: function () {
console.log('cb: match-beta-down');
},
/* callback when gamma value match the condition and is heading left */
onMatchGammaLeft: function () {
console.log('cb: match-gamma-left');
},
/* callback when gamma value match the condition and is heading right */
onMatchGammaRight: function () {
console.log('cb: match-gamma-right');
},
/* callback when condition left -> alpha heading left */
onUnmatchAlphaLeft: function () {
console.log('cb: un-match-alpha-left');
},
/* callback when condition left -> alpha heading right */
onUnmatchAlphaRight: function () {
console.log('cb: un-match-alpha-right');
},
/* callback when condition left -> beta heading up */
onUnmatchBetaUp: function () {
console.log('cb: un-match-beta-up');
},
/* callback when condition left -> beta heading down */
onUnmatchBetaDown: function () {
console.log('cb: un-match-beta-down');
},
/* callback when condition left -> gamma heading left */
onUnmatchGammaLeft: function () {
console.log('cb: un-match-gamma-left');
},
/* callback when condition left -> gamma heading right */
onUnmatchGammaRight: function () {
console.log('cb: un-match-gamma-right');
}
},
/* small configuration with css as string applied for any match */
{
css: 'hit-any-orientation',
value: 40,
},
/* value defined as object with only alpha and gamma defined */
{
value: {
alpha: 13,
gamma: 88,
}
}
]
}
}
}Features
Scroll Tracker
Tracking a scroll event on defined breakpoints or within a certain range. Including horizontal and vertical scroll.
Cursor-Edge Tracker
Tracks if a the cursor touches the edge of an element within a defined range.
Device orientation Tracker
Detects device orientation tilting on x/y/z-axis.
Live bindings
DOM-changes are on track and will bind and unbind events on a selector when the elements appears or removes. This makes it easy to use in Angular, React or Ionic.
Debounced events
Tracker events are debounced by default to avoid unnecessary DOM-rendering.
ES2015 (ES6)-Modules
You can easily import the Tracky-Module with ES2015 module-loaders. It also have a backward compatible version for ES5-Support.
Vanilla JS
Written in plain Javascript without the need for jQuery or other libraries.