From: zurbchris Date: Wed, 18 Nov 2015 02:21:52 +0000 (-0800) Subject: adds to javascript util docs and adds link to table of contents X-Git-Tag: v6.0.0^2~24^2~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=de97ea4b17fdb814509f157703861882abc31ebb;p=thirdparty%2Ffoundation%2Ffoundation-sites.git adds to javascript util docs and adds link to table of contents --- diff --git a/docs/pages/javascript-utilities.md b/docs/pages/javascript-utilities.md index 4cebd3d51..81c5047f9 100644 --- a/docs/pages/javascript-utilities.md +++ b/docs/pages/javascript-utilities.md @@ -8,15 +8,18 @@ description: Our JavaScript Utility Libraries are easy to use and super helpful. See our [JavaScript](javascript.html) and [Installation](installation.html) pages on how to install our files in your project. ## Box +`js/foundation.util.box.js` One of the useful libraries is `Foundation.Box`, and it has a couple methods designed to make your life easier. You can pass either jQuery objects or plain JavaScript elements to both. ```js + var dims = Foundation.Box.GetDimensions(element); ``` Will return an object that contains the dimensions of the `element` passed. The object return looks like: ```js + { height: 54, width: 521, @@ -35,20 +38,18 @@ Will return an object that contains the dimensions of the `element` passed. The Also included is the `ImNotTouchingYou` function. It returns a boolean based on whether the element you pass it is colliding with the edge of the window, or optionally, a parent element. The other two options are for detecting collisions on only one axis, and are simply booleans you pass in. ```js + var clear = Foundation.Box.ImNotTouchingYou(element [, parent, leftAndRightOnly, topAndBottomOnly]); ``` ## Keyboard +`js/foundation.util.keyboard.js` Another quite useful library, `Foundation.Keyboard` has several methods to make keyboard event interaction easier for all. Shout out to [Marius Olbertz](http://www.mariusolbertz.de/) of Germany who conceived and coded this library. -Ever wanted a handy list of common keycodes and the keys they represent? -```js -Foundation.Keyboard.keys; -``` -This is an object containing key/value pairs of the most frequently used keys in our framework. +Ever wanted a handy list of common keycodes and the keys they represent? Use `Foundation.Keyboard.keys`. This is an object containing key/value pairs of the most frequently used keys in our framework. -Want to manage your own keyboard inputs? No problem! Within your `.on('key**')` callback, call `Foundation.Keyboard.parseKey(event)` to get a string of what key was pressed. e.g. `'TAB'` or `'ALT_X'`. +Want to manage your own keyboard inputs? No problem! Within your `.on('key**')` callback, call `Foundation.Keyboard.parseKey(event)` to get a string of what key was pressed, e.g. `'TAB'` or `'ALT_X'`. What if you want to know if there's focusable elements somewhere on a page? Instead of writing that function and selector yourself, just use: ```js @@ -70,9 +71,11 @@ Foundation.Keyboard.handleKey(event, this, { ``` ## MediaQuery +`js/foundation.util.mediaquery.js` The media query library used by Foundation has two publicly accessible functions and two properties: ```js + Foundation.MediaQuery.get('medium'); // returns the minimum pixel value for the `medium` breakpoint. Foundation.MediaQuery.atLeast('large'); @@ -85,10 +88,12 @@ Foundation.MediaQuery.current; Also included is an event emitter for breakpoint changes. You can hook into this event with ```js + $(window).on('changed.zf.mediaquery', function(event, newSize, oldSize){}); ``` ## Motion & Move +`js/foundation.util.motion.js` Two handy utilities, one little file. @@ -103,10 +108,67 @@ Foundation.Move(durationInMS, $element, function(){ Your jQuery element will fire `finished.zf.animate` when the animation is complete. ## Timer & Images Loaded +`js/foundation.util.timerAndImageLoader.js` -Both functions used by [Orbit](orbit.html) and can be useful elsewhere as well. +Both functions are used by [Orbit](orbit.html) and can be useful elsewhere as well. ```js + var timer = new Foundation.Timer($element, {duration: ms, infinite: bool}, callback); // includes: timer.start(), timer.pause(), timer.restart() ``` Similar to `setInterval`, except you can pause and pick back up where you left off. + +```js +Foundation.onImagesLoaded($images, callback); +``` +This will execute your callback function after all the images in your jQuery collection have loaded. + +## Touch +`js/foundation.util.touch.js` + +Gives you the ability to add swipe and psuedo-drag events to elements. + +```js +$('selector').addTouch().on('mousemove', handleDrag); +// Binds elements to touch events. Used in the Slider plugin for mobile devices. +$('selector').spotSwipe().on('swipeleft', handleLeftSwipe); +// Binds elements to swipe events. Used in the Orbit plugin for mobile devices. +``` + +## Triggers +`js/foundation.util.triggers.js` + +Provides a number of event listeners and triggers your script can hook into. Most of them are self-explanatory, and utilized in many Foundation plugins. +```html + + + +``` +```js +// Add the data-open/close/toggle='idOfElement' tag to your markup. +// When a click event is triggered on that element, these are the non-bubbling events directed at your element. +// If you don't use an `id` selector, an event will be triggered that bubbles up to window. +$('selector').on('open.zf.trigger', handleOpen); +$('selector').on('close.zf.trigger', handleClose); +$('selector').on('toggle.zf.trigger', handleToggle); +``` +Besides these useful click triggers, there are also other listeners for you to tap into. Need to know when the window has been resized, but only when it's done resizing? How about a debounced scroll event? Add this markup and JavaScript and you're good to go! + +```html +
...
+
...
+``` +```js +$('#someId').on('scrollme.zf.trigger', handleScroll); +$('#someId').on('resizeme.zf.trigger', handleResize); +``` + +## Miscellaneous + +Foundation includes a couple useful features in the core library that are used in many places, that you can tap into. + +`Foundation.GetYoDigits([number, namespace])` returns a base-36, psuedo-random string with a hyphenated namespace (if you include one). Both arguments are optional, it will by default return a string six characters long. + +`Foundation.getFnName(fn)` returns a string representation of a named function. Seems small, but believe us, it's useful. + +`Foundation.transitionend` is a string of the properly vendor-prefixed version of `transitionend` events. Most browsers don't require a prefix these days, but for those that do, we've got you covered. diff --git a/docs/partials/component-list.html b/docs/partials/component-list.html index 309886154..9691b99b3 100644 --- a/docs/partials/component-list.html +++ b/docs/partials/component-list.html @@ -1,6 +1,6 @@