@aamasri/dom-utils

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

Usage no npm install needed!

<script type="module">
  import aamasriDomUtils from 'https://cdn.skypack.dev/@aamasri/dom-utils';
</script>

README

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


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();
}

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';

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');
});




wallpaper.src = \`/img/wallpaper-${resolution}.jpg\`;



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.js` 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