node-front-end-lib
a simple front-end js library
ajax
ajax.get( url, options )
@param {string} url
@param {Object} [options]
@param {Function} [options.abort]
@param {string} [options.content-type = application/x-www-form-urlencoded]
@param {Function} [options.onreadystatechange]
@param {Function} [options.ontimeout]
@param {Function} [options.progress]
@param {number} [options.timeout = 7000] in milliseconds
@returns {Promise|undefined}
ajax.post( url, options )
@param {string} url
@param {Object} [options]
@param {Function} [options.abort]
@param {string} [options.content-type = application/x-www-form-urlencoded]
@param {string|Object} [options.data]
@param {Function} [options.onreadystatechange]
@param {Function} [options.ontimeout]
@param {Function} [options.progress]
@param {number} [options.timeout = 7000] in milliseconds
@returns {Promise|undefined}
extractXhrResponse( xhr )
attempts to extract a response from an XMLHttpRequestProgressEvent
@param {Object} xhr
@throws {Error}
@returns {string|undefined}
animations
scrollToY( elm, duration, offset, callback )
scrolls the browser viewport vertically to the elm provided
@param {HTMLElement} elm
@param {number} [duration = 500] in milliseconds
@param {number} [offset]
@param {Function} [callback]
dom
addClass( elm, class_name, callback )
adds the class, or classes, given, to the elm provided, with an optional callback called after the operation has completed
@param {Element} elm
@param {string|Array} class_name
@param {Function} [callback]
createElement( tag_name, attributes )
creates a dom element based on the tag_name provided. will also set attributes for the element if an array of attribute objects is provided. an attribute object is expected to contain a key and a value representing the attribute.
@param {string} tag_name
@param {Array} attributes
@returns {HTMLElement|undefined}
findAncestorWithClass( elm, class_name )
finds an html element ancestor, of the elm provided, that has the class name given
@param {HTMLElement} elm
@param {string} class_name
@returns {HTMLElement|undefined}
findAncestorWithTagName( elm, tag_name )
finds an html element ancestor, of the elm provided, that has the tag name given
@param {HTMLElement} elm
@param {string} tag_name
@returns {HTMLElement|undefined}
findNextSiblingWithClass( elm, class_name )
finds an html element sibling, of the elm provided, that has the class name given
@param {HTMLElement} elm
@param {string} class_name
@returns {HTMLElement|undefined}
findNextSiblingWithTagName( elm, tag_name )
finds an html element sibling, of the elm provided, that has the tag name given
@param {HTMLElement} elm
@param {string} tag_name
@returns {HTMLElement|undefined}
findPreviousSiblingWithClass( elm, class_name )
finds an html element sibling, of the elm provided, that has the class name given
@param {HTMLElement} elm
@param {string} class_name
@returns {HTMLElement|undefined}
findPreviousSiblingWithTagName( elm, tag_name )
finds an html element sibling, of the elm provided, that has the tag name given
@param {HTMLElement} elm
@param {string} tag_name
@returns {HTMLElement|undefined}
getBoundingClientRect( elm )
returns the ClientRect of the elm provided
@param {HTMLElement} elm
@returns {ClientRect|undefined}
getElementHeight( elm )
returns the height, in pixels, of the elm provided. remember to add the string 'px' to the value returned when using it in a elm.style.x =
statement
@param {HTMLElement} elm
@returns {number|undefined}
getFieldByName( name )
returns an html element, or collection of elements, that match the given name
@param {string} name
@param {boolean} [return_collection = false]
@returns {HTMLElement|HTMLCollection|undefined}
getFieldByTagName( tag_name )
returns an html element, or collection of elements, that match the given tag name
@param {string} tag_name
@param {boolean} [return_collection = false]
@returns {HTMLElement|HTMLCollection|undefined}
hasClass( elm, class_name )
returns whether or not the given elm has the class name provided
@param {Element} elm
@param {string} class_name
@returns {boolean|undefined}
removeClass( elm, class_name, callback )
removes the class, or classes, given, from the elm provided, with an optional callback called after the operation has completed
@param {Element} elm
@param {string|Array} class_name
@param {Function} [callback]
setAttributes( elm, attributes )
will set attributes for the element if an array of attribute objects is provided. an attribute object is expected to contain a key and a value representing the attribute.
@param {string} tag_name
@param {Array} attributes
@returns {HTMLElement|undefined}
toggleClass( elm, class_name, callback )
toggles the class given, removes it if it exists, or adds it if it doesn’t exist, on the elm provided, with an optional callback called after the operation has completed
@param {HTMLElement} elm
@param {string|Array} class_name
@param {Function} [callback]
polyfills
addCustomEvent()
getWindowLocationOrigin()
utils
addCallback( callback, callbacks )
adds a callback to a given array of callbacks. ensures that the callback is a function and that the callbacks are an array.
@param {Function} callback
@param {Array} callbacks
bindEventDataToEvent( elm, event_name, fn, event_data )
@param {HTMLElement} elm
@param {string} event_name
@param {Function} fn
@param {Object}
callCallbacks( callbacks )
given an array of callbacks, calls each one using the apply method, passing in any arguments provided less the initial array of callbacks
@param {Array} callbacks
checkConditionOnInterval( condition, interval_delay, interval_max )
using setInterval(), checks for the given condition, which should be a function that returns a truthy or falsy result.
@param {Function} condition
@param {number} [interval_delay]
@param {number} [interval_max]
@returns {Promise}
debounce( func, wait, immediate )
@see https://davidwalsh.name/javascript-debounce-function
returns a function, that, as long as it continues to be invoked, will not be triggered. the function will be called after it stops being called for N milliseconds. if immediate
is passed, trigger the function on the leading edge, instead of the trailing.
@param {Function} func
@param {number} wait
@param {boolean} immediate
@returns {Function}
getScrollPosition()
returns the viewport’s current scroll position
@returns {x: number, y: number}
objectPropertyExists( obj )
tests whether or not an object property exists; does not search the object prototype.
@example
objectPropertyExists( window, 'location', 'href' );
@param {Object} obj
@param {string} [property-name, property-name, ...]
@returns {bool}
padInteger( number, length, padding )
prefixes a given number with 0’s, or padding, if given, in order to satisfy the string length given
@param {number} number
@param {number} length
@param {string} [padding = '0']
@returns {string}
preventBackspace()
prevents the backspace key from triggering a history back call to the browser. allows the backspace key to be used in form input fields with the type:
- password
- search
- tel
- text
- textarea
- url
serializeForIe( container, options )
used to serialize form controls for browsers that do not support form.elements
- can be used, for example, in combination with form-serialize; when form-serialize returns an empty result, use this method to serialize the form elements
- options.hidden_with_value = true will only pass hidden fields that contain a value.length > 0
@param {HTMLFormElement} container
@param {Object} [options]
@param {boolean} [options.hidden_with_value]
@returns {string}
touchEventsExist()
determine whether or not the browsing environment supports touch events
@returns {boolean}
triggerEvent( event_name, event_type, elm )
@param {string} event_name
@param {string} event_type
@param {HTMLElement} elm
validateEnvironment()
returns whether or not the front-end environment meets the validations in the method.
@returns {boolean}
whichTransitionEndEvent()
returns the transitionend event listener name that can be used in the current environment.
@returns {string|undefined}
windowResize( callback )
registers the callback with a universal window onresize event listener, which is called via a debounce function that is set with a hard coded timeout of 400 milliseconds
@param {Function} callback
web apis
getGeolocation()
resolves with an object { lat: {number}, lon: {number} } or false if geolocation cannot be determined
@returns {Promise}