Utility functions
There are a selection of utility functions that are available for use through Framework. These have been produced to help replace common functions that jQuery provided eg. show/hide, fadeIn/fadeOut, slideIn/slideOut etc.
Load in the functions to use in your own modules by referencing 'utility' and pass utility into your module eg.
define( [ 'utility' ], function run( utility ) {Constants
- utility.smallTag
- Returns 'small' which matches the response of the getBreakpoint function when at mobile
- utility.mediumTag
- Returns 'medium' which matches the response of the getBreakpoint function when at tablet
- utility.largeTag
- Returns 'large' which matches the response of the getBreakpoint function when at desktop
- utility.urlRegExp
- Regexp to validate if a string is a valid URL
- utility.urlAnchorRegExp
- Regexp to validate/search for anchor tags within a url. It only validated to HTML4 compatible characters
Trigger event
Helps with triggering an event on a particular Node.
utility.trigger( target, eventName );Add class
Add multiple classes (provided in a space separated string) onto a Node.
utility.addClass( target, classNames );Add measurements
Adds an array of measurements that can include suffixs together and return a number. If any of the measurements are NaN it will return 'auto'.
utility.addMeasurements( measurementArray );Convert to pixel value
Converts a number to a pixel value for use when setting size on Nodes and will not add 'px' if the value is 0. If 'noAuto' is not set or false then if the value passed in is 'auto' or NaN then the function will return 'auto'. If 'noAuto' is set to true the function will return 0 instead.
utility.convertToPx( number, noAuto );Debounce
Method for preventing functions being called too rapidly eg. on page resize. Wait is set in milliseconds.
utility.debounce( function, wait );Escape HTML
Safely escape HTML strings to prevent XSS attacks.
utility.escapeHtml( HTMLstring );Extend
To deep merge two or more objects together
utility.extend( targetObject [, object1 ] [, objectN ] );Fade
Function to fade in/out/toggle.
- duration
- Duration of animation in ms.
- options
-
Object containing any settings that need changing from defaults.
- variant - 'in', 'out' or 'toggle', default is toggle
- displayNone - boolean, default is true
- minFade - Number 0-1, default 0
- maxFade - Number 0-1, default 1
- callback - Function to be called when animation complete
utility.fade( target, duration, options );Find
Find elements within a array of Nodes using a given selector. Function returns an array of matched Nodes.
utility.find( elements, selector );Get anchor
Get any anchor from the current pages href.
utility.getAnchor();Get breakpoint
Get the current breakpoint for the page. Returns 'small', 'medium' or 'large'.
utility.getBreakpoint();Get data
Get data attributes as an object from the Node.
utility.getData( target );Hex to RGBA
Covert a Hexidecimal value to RGBA.
utility.hexToRgba( HexValue );HTML string to element
Returns a single Node from an HTML string passed in.
utility.htmlStringToElement( HTMLstring );HTML string to elements
Returns a array of Nodes from an HTML string passed in.
utility.htmlStringToElements( HTMLstring );In range
Check if a number is within a specified range of another number.
utility.inRange( originalNumber, comparitorNumber, plusMinusNumber, inclusiveBoolean );Is Node
Check for if something is a Node or not, returns boolean value.
utility.isNode( target );Is overflown
Check if an Node has overflown (has scroll bars). The axis can be optionally set to 'x' or 'y' for an overflow check on a particular axis otherwise the function will check if either axis is scrolling.
utility.isOverflown( target, axis );Is visible
Check if an Node a Node is visible (has height or width of 0 or is set to display none). Returns boolean.
utility.isVisible( target );Make unique ID
Create a unique ID with optional prefix.
utility.makeId( prefix );Matches
Checks if an Node matches a given selector eg. ':checked'. Returns boolean.
utility.matches( target, selector );Offset
Get the offset of the current Node. Returns an object with 'top' and 'left' values.
utility.offset( target );Get outer height
Get height of the given Node including its margins.
utility.outerHeightTrue( target );Get outer width
Get width of the given Node including its margins.
utility.outerWidthTrue( target );Parents
Get array of matching parent Nodes for the given Node.
utility.parents( target, selector );Process in-page links
Function finds all links that are anchoring within the current page and calls the provided function, passing in the matched Node.
utility.processInPageLinks( selector, function );Remove class
Remove multiple classes (provided in a space separated string) from a Node.
utility.removeClass( target, classNames );Remove measurement suffix
Remove any measurement suffix eg. px, em etc and return a number. Will return 'auto' if 'auto' is received unless 'noAuto' is set to true, it will return 0 in this case.
utility.removeMeasurementSuffix( value, noAuto );Reset styles
Set styles in provided object on Node provided. If a style value is set to null the style will be removed from the Node.
utility.resetStyles( target, styles );Request AJAX content load into Node
Request content from another URL is loaded into the provided Node. Optional callback can be provided for after content has successfully loaded.
utility.requestLoadInto( target, href, callback );Get scroll parent
Get the scroll parent for the given Node. Optional boolean can be provided to set if to include currently hidden parent Nodes or not.
utility.scrollParent( target, isHidden );Set attributes
Set multiple attributes on a single Node. Pass in object with the attributes to be set and their values.
utility.setAttributes( target, attributes );Get siblings
Get all siblings of provided Node. Can optionally supply a selector for them to match, if no selector supplied all sibling Nodes will be returned.
utility.siblings( target, selector );Slide up/down/toggle
Function to slide a Node in/out/toggle.
- duration
- Duration of animation in ms.
- options
-
Object containing any settings that need changing from defaults.
- variant - 'up', 'down' or 'toggle', default is toggle
- overlapMargin - boolean, default is false
- customStartHeight - Number, default null
- customEndHeight - Number, default null
- minFade - Number 0-1, default 0
- maxFade - Number 0-1, default 1
- fade - boolean, default false
- callback - Function to be called when animation complete
utility.slideToggle( target, duration, options );Smooth scroll
Smoothly scroll to the given coordinates. Duration time (in millisecnds) is use for browsers that do not natively support smooth scrolling.
By default the function with scroll the window, an alterntive scrollable area can be set if required. Callback function is optional.
utility.smoothScroll( xCoord, yCoord, duration, scrollArea, callbackFn );Subtract measurements
Subtracts an array of measurements that can include suffixs and return a number. If any of the measurements are NaN it will return 'auto'.
utility.subtractMeasurements( measurementArray );Unwrap
Unwrap provided Nodes children and remove original Node.
utility.unwrap( target );Update history
Update the browser history with the provided anchor.
utility.updateHistory( anchor );Wrap
Wrap target Node with provided Node element, if no Node element is provided to wrap the target a div will be wrapped around the target.
utility.wrap( target, wrappingNode );Wrap Inner
Wrap target Node children with provided Node element. Optional list of class names can be proved in the format of a space separated string.
utility.wrapInner( target, wrappingNode, classNames );