Notoriously Pedantic Magistrate

    growl-js

    1.0.16 • Public • Published

    Growl-js

    A classy notification system for the browser.

    growl({ message: 'Excellent, Growl is working!', target: 'button' });
    

    Features

    • Easy to use.
    • Lazy loading (3kb initial page load).
    • Usable as a webpack/ES6 module or a pre-built browser bundle.
    • Auto-positioning based on the target element's position.
    • Target element can be specified by standard css selector, DOM element, or jQuery object.
    • Automatic duration based on message length & type.
    • Implements the 'Promise' interface, allowing sequential notifications.



    Demo

    Try me



    Installation

    Growl-js is a javascript package built for and using the ES6 module system, but it's also provided as a pre-built, minified browser package (in this package's "dist" folder).

    Browser

    1. Download & copy this package's "dist" folder into your web server's public folder eg. public/js/dist/*.
    2. Rename "dist" to "growl" eg. public/js/growl
    3. Load the growl script at the end of your web page (before the closing body tag) like this:
    <body>
        ...
    
        <script src="/js/growl/growl.js"></script>
    </body>
    </html>
    
    
    1. When the browser loads growl will be attached to the browser's global window object. Use it anywhere in your scripts like this:
    <button>Target</button>
    
    <script>
        document.querySelector('button').onclick = function(event) {
            growl({ message: 'You clicked on me' target: event.target });
        });
    </script>
    

    ES6 module

    Install the growl-js package into your project using npm:
    $ cd to/your/project
    $ npm install growl-js
    

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

    Static import

    import growl from 'growl';
    

    function helloWorld() { growl({ message: 'Hello World' }); }

    Dynamic import

    Leveraging Webpack's on-demand (lazy) loading and code-splitting:
    import(/* webpackChunkName: "growl" */ 'growl').then((module) => {
        const growl = module.default; 
        growl({ message: 'Hey, growl just loaded dynamically', type: 'success' });
    });
    



    Growl Options

    The growl function expects to be invoked with an options object. Eg.
    growl({ message: 'Hi' });


    Here's the full list of options:
    Option Type Description Default
    message (required) string the message content to display (plain text or simple HTML) [error] "Missing message content!"
    type (optional) string the type of message ie. 'success', 'error', 'warning', or 'info'. info
    target (optional) DOM element, CSS selector string, or jQuery object (optional) element to associate the growl notification with. #growlNoticeboard
    duration (optional) number how long the message is displayed (in seconds). 0 => must be dismissed by the end-user. automatic (based on message length/type)
    overwrite (optional) boolean whether this growl message will replace any existing notification on the same target. false

    Eg. using all the options:
        growl({
            message: 'You've selected "<strong>Delete my account</strong>"!',
            type: 'warning',
            target: 'input[type=submit]',
            duration: 10,
            overwrite: true
        });
    

    Sequential Notifications

    Since growl.js implements the 'Promise' interface, your scripts can build sequential interactions with users. Eg:
        let clickCount = 0;
        
        document.getElementById('target').onclick = function(event) {
            growl({
                message: `You've clicked this button ${++clickCount} times`,
                type: 'info',
                target: event.target,
                overwrite: true
            }).then(function() {
                if (clickCount === 3) {
                    growl({
                        message: 'I hope you're enjoying our app!',
                        type: 'success',
                    });
                }
            });
        };
    




    Package Management

    Growl-js supports npm under the name growl-js.

    NPM

    $ npm install growl-js --save

    Dependencies

    Growl-js depends on 2 external packages:
    1. jquery
    2. animejs
    3. @aamasri/dom-utils
    These dependencies are bundled (as separate pre-built 'chunks') in this package's "dist" folder.
    Invoking the growl() function will dynamically load these dependencies at run-time (if these scripts don't already exist on the page) and they'll be added to the global window object.
    If your page already uses the jQuery, animejs, or @aamasri/dom-utils packages, growl will use them instead.



    Manual release steps

    1. Increment the "version" attribute of `package.json`.
    2. Re-build the browser output bundle...
      npm run build-production
      ...and observe that webpack completed with no errors.
    3. Test the bundle by loading page: "dist/index.html" in a browser.
    4. Commit
      git commit -a -m "Release version x.x.x - description"
    5. Tag the commit with it's version number
      git tag x.x.x
    6. 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
    7. Publish to npm registry:
      npm publish

    Authors

    Install

    npm i growl-js

    DownloadsWeekly Downloads

    7

    Version

    1.0.16

    License

    MIT

    Unpacked Size

    233 kB

    Total Files

    17

    Last publish

    Collaborators

    • aamasri