Dom Utils

A collection of DOM utils to add syntactic sugar and supplement jQuery.

This is not an (ES5) browser package. It's an ES6 source module designed to be 'imported' into a javascript project that's transpiled using babel & webpack.

Utility Function List

• ready().then(...) - deferred document ready.


• loaded().then(...) - deferred window loaded.


• $cache() - providing $(window), $(document), and $('body').


• isInIframe() - is our code running inside an iframe?


• isTouchDevice()


• isMobile()


• isVisible(element) - whether element is visible in the viewport or scrolled out of view.


• getViewportOffset(element) - top, right, bottom, left offsets from viewport.


• onTopZIndex() - for new elements to be displayed on top.


• getZIndex(element) - provides layer information.


• getAppliedStyle(element, style) - computed style.


• webpSupport() - whether the browser supports webP images.


• screenResolution() - returns 'lo', 'med' or 'hi' (to support a responsive image system).


• hash(content) - fast hash code generator.


• scrollTo(elementOrSelector) - an easier, more flexible alternative to element.scrollIntoView().

Usage Examples

async ready()

Defer script execution until the DOM is ready. Implements the Promise interface.

import { ready } from '@aamasri/dom-utils';
ready().then(function() { 
    alert('Your browser is ready to run scripts...');
});

async loaded()

Allows script execution to be deferred until after the initial page render. Implements the Promise interface.

import { loaded } from '@aamasri/dom-utils';
loaded().then(function() {
    domUtils.loaded().then(function() { 
        alert('Your browser has finished loading (including images)...');
    });
});

$cache()

Re-use the core jQuery objects (may save some overhead). Provides the $(window), $(document), and $('body') jQuery objects.

import { $cache } from '@aamasri/dom-utils';
let windowWidth = $cache().$window.width();

isInIframe()

Enables check in case our code is running inside an iframe. This can avoid the problem where a functions fails because it is unavailable inside the iframe.

import { isInIframe } from '@aamasri/dom-utils';
if (isInIframe) {
    parent.showMessage('I'm executing a parent window function');
} else {
    alert('This is in the iframe');
}

getViewportOffset(element)

Returns the top, right, bottom, left offsets of the element (relative to the viewport).

For example, a negative offset means that the element is scrolled out of view.

This function is also useful in positioning another element relative to the specified element.

import { getViewportOffset } from '@aamasri/dom-utils';
const target = window.getElementById('submitButton');
const targetOffsets = getViewportOffset(target);    // target can be a DOM element or jQuery object
if (targetOffsets.top < 0 || targetOffsets.bottom < 0) {
    target.scrollIntoView();
}

getDocumentOffset(element)

Returns the top, right, bottom, left offsets of the element (relative to the document).

For example, a negative offset means that the element is scrolled out of view.

This function is also useful in positioning another element relative to the specified element.

import { getViewportOffset } from '@aamasri/dom-utils';
const target = window.getElementById('submitButton');
const targetOffsets = getViewportOffset(target);    // target can be a DOM element or jQuery object
if (targetOffsets.top < 0 || targetOffsets.bottom < 0) {
    target.scrollIntoView();
}

onTopZIndex()

Returns the highest z-index value on the page.

This is useful for popup dialog boxes (or notifications) that need to display on-top of everything else already on the page.

import { onTopZIndex } from '@aamasri/dom-utils';
$dialog.css({ 'position', 'absolute', 'z-index', onTopZIndex() + 1 });  // position dialog box on top

getZIndex(element, recursive)

Gets the z-index style applied to an element.

More usefully (because parent z-index affects descendants), set the recursive option true for the effective z-index (ie. the element's ancestry).

import { getZIndex } from '@aamasri/dom-utils';
const dialogLayer = getZIndex(dialog, true);

getAppliedStyle(element, style)

Slightly easier to use than the native window.getComputedStyle() function.

import { getAppliedStyle } from '@aamasri/dom-utils';
const buttonVisible = getAppliedStyle(button, 'display') !== 'none';

webpSupport(feature)

As of 2021 full browser support for webp images is ~95%. Nevertheless, with Safari only recently offering full
support and considering many older IOS devices (which simply can't be upgraded), this function will probably be useful
through 2024.

This function checks for specific feature support (alpha by default) because some browsers added features incrementally
with lossy image support added first, followed by lossless & alpha, and finally support for animated images.

import { webpSupport } from '@aamasri/dom-utils';
// eg. check for full webp support including animation
webpSupport('animation').then(msg => {
    window.browserInfo.webpSupport = true;
    console.log(msg);
}).catch(errorMessage => {
    window.browserInfo.webpSupport = false;
    console.info(errorMessage);
    stripWebp();    // remove unsupported responsive webp images from srcset
});

screenResolution()

Part of a system to determine the optimal image resolution for a given device.

Returns 'lo', 'med' or 'hi' based on the size of the browser viewport.

import { screenResolution } from '@aamasri/dom-utils';
const resolution = screenResolution();
wallpaper.src = \/img/wallpaper-${resolution}.jpg\;

hash(content)

A simple, fast (faster than md5 etc) hash code generator.

import { hash } from '@aamasri/dom-utils';
const initialContent = $input.val();
const initialContentSignature = hash(initialContent);
$input.on('change', function() {
    const newContent = $input.val();
    const newContentSignature = hash(newContent);
    if (newContentSignature !== initialContentSignature)
        alert('the input value changed');
});

scrollTo(elementOrSelector)

An alternative to element.scrollIntoView()

1. It handles selectors and Elements

2. It's svelte friendly, handling components that are still rendering

import { scrollTo } from '@aamasri/dom-utils';
scrollTo('.user-profile-{userId}}');

Installation

Dom-utils is an ES6 source module intended to be imported into your ES6 projects - prior to transpiling into a browser bundle with Babel/Webpack.

$ cd to/your/project
$ npm install @aamasri/dom-utils --save-dev

Then import and use it in your project's ES6 modules:

Static import

import { ready, loaded, isVisible } from '@aamasri/dom-utils';
ready().then(function() {
    alert('Your browser is ready to run scripts...')
});

Dynamic import

Leveraging Webpack's on-demand (lazy) loading and code-splitting:

import(/ webpackChunkName: "dom-utils" / '@aamasri/dom-utils').then((domUtils) => {
    domUtils.loaded().then(function() { 
        alert('Your browser has finished loading (including images)...')
    });
});

Package Management

Dom-utils supports npm under the name @aamasri/dom-utils.

Dependencies

Some of the utility functions depend on the jQuery package.

Manual release steps

1. Increment the "version" attribute of package.json.


2. Increment the version number in the dom-utils.mjs file.


3. Commit

   git commit -a -m "Release version x.x.x - description"



4. Tag the commit with it's version number

   git tag x.x.x



5. Change the "latest" tag pointer to the latest commit & push:
   

   git tag -f latest
   git push origin master :refs/tags/latest
   git push origin master --tags

   
   
6. Publish to npm registry:

   npm publish

Authors

* Ananda Masri
* And awesome contributors