Have ideas to improve npm?Join in the discussion! »

    @aamasri/dialog

    1.1.5 • Public • Published

    Dialog

    A flexible javascript popup dialog.

    dialog.open({
            title: 'Dialog Title',
            source: 'Body content can be (HTML, CSS selector, DOM element, or URL)',
        }).then(...);
    

    Features

    • Easy to use.
    • Lazy loading (3kb initial page load).
    • Usable as a webpack/ES6 module or a pre-built browser bundle.
    • Handles multiple programming scenarios and content sources.
    • Simple HTML structure and easy custom styling using CSS3 variables.
    • Dialogs can be 'modal', and/or can be layered on top of each other.
    • Implements the 'Promise' interface, allowing sequential notifications.



    Demo

    Try me



    Installation

    Dialog 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 "dialog" eg. public/js/dialog
    3. Load the dialog script at the end of your web page (before the closing body tag) like this:
    <body>
        ...
    
        <script src="/js/dialog/dialog.js"></script>
    </body>
    </html>
    
    
    1. When the browser loads, dialog will be attached to the browser's global window object. Use it anywhere in your scripts like this:
    <button>Target</button>
    
    <script>
        dialog.open();          // Display the dialog cheat sheet
    
        ...
    
        dialog.closeLast();     // close the on-top dialog
        
        ...
        
        dialog.closeAll();
    
    </script>
    

    ES6 module

    Install the dialog package into your project using npm:
    $ cd to/your/project
    $ npm install @aamasri/dialog
    

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

    Static import

    import dialog from 'dialog';
    

    function helloWorld() { dialog.open({ title: 'Greetings', source: 'Hello World' }); }

    Dynamic import

    Leveraging Webpack's on-demand (lazy) loading and code-splitting:
    import(/* webpackChunkName: "dialog" */ 'dialog').then((dialog) => {
        dialog.closeAll();
    
    dialog.open(...
    

    });



    Dialog Functions

    dialog.open({ .. }).then((dialogElement) => { .. })    // create a new dialog
    dialog.close(dialogElement)                            // close a specific dialog instance
    dialog.closeAll()                                      // close all dialogs
    dialog.closeLast()                                     // close the on-top dialog



    Dialog.open Options

    Here's another example with different options; eg. to load/display a fragment of the HTML returned by a URL:
        dialog.open({ 
                 title: `${userName}'s User Profile`, 
                 source: userUrl,
                 fragment: '.contact-info'
                 modal: true,
                 onClose: function() { alert: `Don't hesitate to call ${userName}!`; }
             }).then( function(dialogElement) {
                 console.log('fyi the contact info dialog just launched');
    
             window.setTimeout( function() {
                dialog.close(dialogElement);
             }, 10000);
         });
    


    Here's the full list of dialog.open options:
    Option Type Description Default
    title string | undefined dialog title, else source element title attribute "Missing Title"
    source string | object | undefined the content source: html content, selector, url, or element usage instructions
    fragment** string | undefined selector by which to extract a portion of the source HTML
    iframe** boolean | undefined page background dimming false
    modal boolean | undefined if the source is a url, whether to load it in an iFrame false
    replace boolean | undefined whether to close any existing dialogs or layer up false
    persistent boolean | undefined whether ESC key or blur events close the dialog false
    onClose function | string | undefined callback function or eval(string) to execute after dialog dismissed
    classes string | undefined additional classes to apply to the dialog container element

    Notes

    1. To create a chrome-less dialog (ie. one with no padding or header, where the specified content completely fills the dialog box), simply omit the title option. 2. If loading a URL fails then it may be due to a CORS issue (if it's for a different domain).
    ** it is recommended to use the "iframe" or "fragment" options when loading a URL that returns a FULL HTML document.
    This is because HTML documents cannot be nested without an iframe; not specifying the "iframe" or "fragment" option will cause the dialog to reload the URL in an iframe (which may unnecessarily increase the dialog load time).



    Dialog Styling

    The dialog's default CSS styles may easily be themed to fit your application. Change any of these default styles in your CSS :root or body scope:
    :root {
        --dialogBoxShadow: 0 0 28px #CCC;
        --dialogBoxShadow: 0 0 28px #CCC;
        --dialogBoxShadow: 0 0 28px #CCC;
        --dialogBackground: #FFF;
        --dialogBorder: 1px solid #DDD;
        --dialogBoxShadow: 0 0 28px #CCC;
        --dialogBorderRadius: 4px;
        --dialogFontFamily: Helvetica, Verdana, sans-serif;
        --dialogLineHeight: 1.8;
        --dialogTitleSize: 1.3rem;
        --dialogTitleColor: #888;
        --dialogTitleWeight: bold;
        --dialogModalBackground: rgba(170, 170, 170, 0.3);
        --dialogModalOpacity: 0.3;
    




    Package Management

    Dialog supports npm under the name @aamasri/dialog.

    NPM

    $ npm install @aamasri/dialog --save

    Dependencies

    Dialog 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 dialog() 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 loads the jQuery, animejs, or @aamasri/dom-utils packages, dialog 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 @aamasri/dialog

    DownloadsWeekly Downloads

    22

    Version

    1.1.5

    License

    MIT

    Unpacked Size

    736 kB

    Total Files

    25

    Last publish

    Collaborators

    • avatar