Home

JS Helpers

What?

A collection of documented vanilla JS widgets.

In the A17 Boilerplate, we use these as a dependency and install via NPM. Alternatively you can copy the src folder and the index.js into a folder of your project and compile.

If installed via NPM, you'll want to import into your JavaScript by:

import helpers from '@area17/a17-helpers'

or, cherry pick individual helpers:

import { getCurrentMediaQuery, resized } from '@area17/a17-helpers'

Available helpers

• ajaxRequest - Performs ajax requests
• cookieHandler - cookie helpers
  • create - Creates a cookie with optional expiration date
  • delete - Deletes a named cookie
  • read - Returns the value of a named cookie
• copyTextToClipboard - Copies text to clipboard
• debounce - Debounced function call
• escapeString - Escapes and URL encodes a string
• extend - Merges the contents of two objects together
• focusDisplayHandler - adds data-focus-method to document.activeElement which differentiates between keyboard, mouse and touch focus
• focusTrap - trap keyboard tab focus within an element
• generateCsv - generates a CSV string from a data array
• getCurrentMediaQuery - Returns the current media query in use in the CSS
• getFocusableElements - 3.1.0 - Returns a list of focusable elements from within a target
• getIndex - Returns the index of a node in a nodeList
• getMetaContentByName - Returns a metatag content by name
• getOffset - Get the current coordinates of a node, relative to the document (uses getBoundingClientRect)
• getUrlParameterByName - Returns value of a parameter from a query string
• keyCodes - Abstraction of commonly used keycodes NB: object not a function
• ios100vhFix - stop iOS devices scaling up when rotating from portrait to landscape
• isBreakpoint - compare a breakpoint string against current CSS breakpoint
• isVisible - 3.1.0 - reports if an element is visible or not
• jsonpRequest - Performs JSONP requests
• listeners - 3.1.0
  • addListener - Add event listeners to node lists
  • removeListener - Remove event listeners from node lists
• messages - Growl like messages
• nl2br - 3.1.0 - Inserts HTML line breaks (<br>) before all newlines in a string
• objectifyForm - Generates a JS Object out of a form
• orientationChangeFix - Stopping iOS devices scaling up when rotating from portrait to landscape
• purgeProperties - Removes all properties from an object
• queryStringHandler
  • toObject - Takes the passed URL, or the current browser URL and returns an object of query string parameters
  • fromObject - Takes an object and turns it into a query string
  • updateParameter - Updates a specified url parameter to a new value
• removeEmoji - 3.1.0 - Remove Emoji from strings
• removeHTMLentities - 3.1.0 - Remove or replace HTML entities from strings
• removeNoneASCIICharacters - 3.1.0 - Removes non ASCII characters from a string
• removeNonePrintableCharacters - 3.1.0 - Remove or replace non printable characters from a string
• replaceAccentedCharacters - 3.1.0 - Replace accented characters (Diacritics) with regular ASCII characters
• resized - What to do on document resize, also checks if current media query has changed
• responsiveImageSizes - 3.2.0 - generates HTML sizes string
• responsiveImageSrcset - 3.2.0 - generates HTML srcset string
• responsiveImageUpdate - force Safari to re-asses srcset on resize
• scrollToY - Animated scroll to position
• sentEventToSegmentio - Tracks site wide requests for analytics events. Catches events before segment.io is ready, stores them and tries them again when it is ready. Follows conventions from segment.io: https://segment.com/docs/libraries/analytics.js/#selecting-integrations Checks a meta tag on init for identifying the user
• setFocusOnTarget - Sets focus on target node
• Store - Create your store with actions, mutations and an initial state

Deprecated

• fontLoadObserver - Adds a class and to the document and writes a cookie when fonts have loaded
• forEach - run a function on each item of an array
• lazyLoad - Lazy load images, videos, iframes, a A17-helperised version of: https://github.com/area17/lazyload
• manageBehaviors - inits and manages page data-behaviors on initial load and on page update
• triggerCustomEvent - Triggers a custom event

Developing

Feel free to add any vanilla JS helpers that will be common to many projects and save someone some time working them out in the future. The main aims are no dependencies, small elegant code and high potential sharing across sites.

.editorconfig

Download the editor config plugin for your text editor: http://editorconfig.org/#download

no jQuery

Intentionally vanilla JS to keep this JS library agnostic.

Tests

Written using Jest with tests in /test/. To run:

$ npm run test

To add/update a helper

• Make your changes
• Bump the version number
• Test it, you may need to update the tests in /test/
• Update the wiki document for it if required