@aamasri/dom-utils

    1.1.5 • Public • Published

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

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

    Install

    npm i @aamasri/dom-utils

    DownloadsWeekly Downloads

    7

    Version

    1.1.5

    License

    MIT

    Unpacked Size

    21.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • aamasri