Msg

A javascript library to create and manage highly customizable modal windows and popup messages.

Modal   Popups   Windows   Installation   Basic Usage

Structure   Styling   Options   Properties   Methods   Presets

Modal

Modal windows with different options and appearance can be created.

Demo 1   Demo 2   Demo 3   Demo 4

Popups

You can create stackable popup messages using certain options.

Keep clicking the demos to stack the popups:

edge_padding_x:           edge_padding_y:  

sideStack:           sideStack_padding:  

autoclose:           sideStack_collapse:           enable_titlebar:           lock:  

window_x:           enable_overlay:           overlay_x:  

center   top   bottom   left   right   topleft   bottomleft   topright   bottomright
let msg_pop = Msg.factory({
    preset: "popup" // or "popup_autoclose",
    position: "bottomright"
})

Full Windows

Using the "window" preset, full page, clean windows, can be created as a canvas to create anything on top. This is useful to add different layers to your application while still taking advantage of the Msg instance control system. The content takes 100vh height and 100vw width. If you want to have scrolling content you must create your own containers.

Open Window   
let msg_window = Msg.factory({
    preset:"window"
})

Installation

Get the code here

To install just include the file in /dist:
<script src="msg.js"></script>
Or the minified, smaller file:
<script src="msg.min.js"></script>
It's also available on NPM:
npm install msg-modal
Then you can include the file:
<script src="node_modules/msg-modal/dist/msg.js"></script>
Or the minified version:
<script src="node_modules/msg-modal/dist/msg.min.js"></script>

Basic Usage

To use, first make an instance:
let msg = Msg.factory()
To show a window just pass a string or an html element to the show method:

msg.show("<i>Hello</i> <b>World</b>")

msg.show(document.getElementsByTagName("h1")[0])

You can re-use the same instance to display different things.

Note that an instance can only show one thing at a time.

If you want to have multiple windows open you need to create multiple instances.

You can create factory functions to create and show instances on the fly.

The "persistent" option is to be considered when creating on the fly instances. If you're not going to use the instance again, it's advised to use persistent: false, which destroys the html elements after close, to avoid filling the dom with unncecesary elements.
function remind(html) {
    let msg = Msg.factory({
        class: "green",
        enable_titlebar: true,
        persistent: false
    })

    msg.show(["Reminder", html])
}

remind("Water the trees.")
Run This Demo

Structure

Four elements are created with the following ids:

"Msg-container-id" (with classes: "Msg-container" and "Msg-container-class")
"Msg-window-id" (with classes: "Msg-window" and "Msg-window-class")
"Msg-content-container-id" (with classes: "Msg-content-container" and "Msg-content-container-class")
"Msg-content-id" (with classes: "Msg-content" and "Msg-content-class")

These elements are optional:

"Msg-overlay-id" (with classes: "Msg-overlay" and "Msg-overlay-class") (Created by default)
"Msg-topbar-id" (with classes: "Msg-topbar" and "Msg-topbar-class") (Created if Msg-window-inner-x or Msg-titlebar are created)
"Msg-titlebar-id" (with classes: "Msg-titlebar" and "Msg-titlebar-class") (Not created by default)
"Msg-window-inner-x-id" (with classes: "Msg-window-inner-x" and "Msg-window-inner-x-class") (Created by default)
"Msg-window-floating-x-id" (with classes: "Msg-window-floating-x" and "Msg-window-floating-x-class") (Not created by default)
"Msg-overlay-x-id" (with classes: "Msg-overlay-x" and "Msg-overlay-x-class") (Not created by default)
"Msg-progressbar-container-id" (with classes: "Msg-progressbar-container" and "Msg-progressbar-container-class") (Created if Msg-progressbar is created)
"Msg-progressbar-id" (with classes: "Msg-progressbar" and "Msg-progressbar-class") (Not created by default)

The structure looks like this:
[container] (instance.container)

    [overlay] (Optional) (instance.overlay)
        [overlay-x][/overlay-x] (Optional) (instance.overlay_x)
    [/overlay]

    [window] (instance.window)

        [window-floating-x][/window-floating-x] (Optional) (instance.window_floating_x)

        [topbar] (instance.topbar)
            [titlebar][/titlebar] (Optional) (instance.titlebar)
            [window-inner-x][/window-inner-x] (Optional) (instance.window_inner_x)
        [/topbar]

        [content-container] (instance.content_container)
            [content][/content] (instance.content)
        [/content-container]

        [progressbar-container] (instance.progressbar_container)
            [progressbar][/progressbar] (instance.progressbar)
        [/progressbar-container]

    [/window]

[/container]
By default, ids are based on the number of instances created, they are incremental. Custom ids and classes can be specified via options.

The z-index values of the windows are generated when they are shown, allowing for windows with different ids to stack on top of each other. This stack is called the zStack.

Stack Demo

Styling

You can set custom ids and classes via options.

You can play with the ids and classes to have different types of windows.

Elements can have multiple classes. For example, class:"foo bar" would create all elements with those classes, for example, content would have the classes "Msg-content", "Msg-content-foo" and "Msg-content-bar". It also works with specific classes, like content_class:"foo bar".

If you don't want a class name to be turned into the Msg-element-classname format, you can append a "!" to it. For example overlay_class:"!glow" would use "glow" instead of "Msg-overlay-glow".

The Msg-content's padding is set depending on your settings, to try to make it look pleasing in different situations.

To override the css you will probably need to use !important declarations.
Demo Code:

//js

let msg_custom = Msg.factory({
  id: `foo`,
  class: `bar`,
  content_class: `!big`,
  enable_titlebar: true,
})

//css

#Msg-overlay-foo {
  background-color: rgba(61, 157, 192, 0.7) !important;
}

.Msg-window-bar {
  background-color: yellow !important;
}

.Msg-titlebar-bar {
  background-color: green !important;
  color: white !important;
}

#Msg-window-inner-x-foo {
  background-color: red !important;
  color: #ffffff !important;
}

#Msg-window-inner-x-foo:hover {
  background-color: #a72b2b !important;
}

.big {
  font-size: 1.8em !important;
}

msg.show(["Window Example", some_text])
Run This Demo

There are some pre-made classes:

Red   Blue   Green   Black

With titlebar enabled:

Red   Blue   Green   Black

Options

The following options can be passed inside an object when creating an instance:

id (Default: Number of instances): The id of the instance. For example, id:"foo".

class (Default: "default"): The class of the instance. For example, class:"bar". It can be multiple classes, for example, class:"one two three".

container_class (Default: undefined): If this is defined, the Msg-container will use this instead of the class option.

overlay_class (Default: undefined): If this is defined, the Msg-overlay will use this instead of the class option.

window_class (Default: undefined): If this is defined, the Msg-window will use this instead of the class option.

topbar_class (Default: undefined): If this is defined, the Msg-topbar will use this instead of the class option.

titlebar_class (Default: undefined): If this is defined, the Msg-titlebar will use this instead of the class option.

content_class (Default: undefined): If this is defined, the Msg-content will use this instead of the class option.

window_inner_x_class (Default: undefined): If this is defined, the Msg-window-inner-x will use this instead of the class option.

window_floating_x_class (Default: undefined): If this is defined, the Msg-window-floating-x will use this instead of the class option.

window_overlay_x_class (Default: undefined): If this is defined, the Msg-overlay-x will use this instead of the class option.

progressbar_container_class (Default: undefined): If this is defined, the Msg-progressbar-container will use this instead of the class option.

progressbar_class (Default: undefined): If this is defined, the Msg-progressbar will use this instead of the class option.

lock (Default: true): Prevents scrolling from propagating to the body. This is done through css by adding a class to the body temporarily.

locked_element (Default: "body"): String argument for document.querySelector() to find the element to be locked.

close_on_overlay_click (Default: true): Closes the window when the overlay is clicked.

close_on_escape (Default: true): Closes the window when Escape is pressed.

closeable (Default: true): Whether the window is closable at all.

clear_editables (Default: false): When pressing Escape, it removes the last word from an active input=text or textarea element, if it has a value. If it's empty and close_on_escape is true, it closes the window.

persistent (Default: true): When true, it keeps the html elements in the dom when the window is closed. If false, it destroys the html elements on close.

remove_after_close (Default: true): If true, it will destroy the html elements and remove the instance from the instance registry after close.

position (Default: "center"): The position of the window in the screen. Either "center", "left" (hStackable), "right" (hStackable), "top" (vStackable), "bottom" (vStackable), "topleft" (vStackable) (hStackable), "topright" (vStackable) (hStackable), "bottomleft" (vStackable) (hStackable), or "bottomright" (vStackable) (hStackable).

window_width (Default: "auto"): The width of the Msg-window.

window_height (Default: "auto"): The height of the Msg-window.

window_min_width (Default: "auto"): The min-width of the Msg-window.

window_min_height (Default: "auto"): The min-height of the Msg-window.

window_max_width (Default: "80vw"): The max-width of the Msg-window.

window_max_height (Default: "80vh"): The max-height of the Msg-window.

window_cursor (Default: "default"): The cursor of the Msg-window. For example, "pointer" or "none".

titlebar_cursor (Default: "default"): The cursor of the Msg-titlebar. For example, "pointer" or "none".

window_unselectable (Default: false): If true, it will make the window's content unselectable. For example by dragging with the mouse.

edge_padding_x (Default: 20): The horizontal padding in pixels from the edge of the screen. Some positions don't support this.

edge_padding_y (Default: 20): The vertical padding in pixels from the edge of the screen. Some positions don't support this.

sideStack (Default: "vertical"): Either "vertical", "horizontal" or "none". This is what allows popup windows to stack on top of each other vertically or appear side by side horizontally.

sideStack_padding (Default: 20): The separation in pixels between vertically or horizontally stacked windows.

sideStack_collapse (Default: true): Whether windows in a vertical or horizontal stack collapse when a window is closed.

zStack_level (Default: 2): Level 1 zStacks start at a z-index of 5000000 (5 with 6 zeros), Level 2 zStacks start at a z-index of 50000000 (5 with 7 zeros). This is useful if you want to have popup messages that don't go above the modal windows.

autoclose (Default: false): Closes the window automatically after a certain amount of time.

autoclose_delay (Default: 5000): The amount of time in milliseconds that must pass before closing the window.

enable_titlebar (Default: false): Whether Msg-titlebar is created or not.

center_titlebar (Default: false): A mode where the text is placed in the center relative to the window. It adjusts to window_x settings.

enable_progressbar (Default: false): Whether Msg-progressbar is created or not.

bind_progressbar_to_autoclose (Default: true): If this is true, the progressbar will reflect the autoclose delay when the window is shown.

reverse_autoclose_progressbar (Default: false): If this is true, instead of the autoclose progressbar animation starting at 100% width and going down to 0%, it starts at 0% and goes up to 100%.

close_on_show (Default: false): When show() is called it will first close the window and then show it.

close_others_on_show (Default: false): When the window is first shown it will close all other open windows.

scroll_on_show (Default: true): Whether the scrolltop of Msg-content-container will become 0 on show. In other words, if it will automatically be scrolled to the top on show if there is overflow.

enable_overlay (Default: true): Whether the overlay is created or not.

window_x (Default: "inner_right"): Makes an x to close the window inside the window. Either "inner_right", "inner_left", "floating_right", "floating_left" or "none".

overlay_x (Default: "none"): Makes an x to close the window inside the overlay. Either "right", "left" or "none".

replace_linebreaks (Default: false): If true, strings passed to show() or set() will have every "\n" replaced with an html linebreak.

before_show (Default: Empty Function): Function that triggers before the show method. Receives the instance as an argument. If false is returned it aborts the execution.

after_show (Default: Empty Function): Function that triggers after the show method. Receives the instance as an argument.

before_set (Default: Empty Function): Function that triggers before the set method. Receives the instance as an argument. If false is returned it aborts the execution.

after_set (Default: Empty Function): Function that triggers after the set method. Receives the instance as an argument.

before_set_title (Default: Empty Function): Function that triggers before the set_title method. Receives the instance as an argument. If false is returned it aborts the execution.

after_set_title (Default: Empty Function): Function that triggers after the set_title method. Receives the instance as an argument.

before_set_progress (Default: Empty Function): Function that triggers before the set_progress method. Receives the instance as an argument. If false is returned it aborts the execution.

after_set_progress (Default: Empty Function): Function that triggers after the set_progress method. Receives the instance as an argument.

before_close (Default: Empty Function): Function that triggers before the close method. Receives the instance as an argument. If false is returned it aborts the execution.

after_close (Default: Empty Function): Function that triggers after the close method. Receives the instance as an argument.

after_last_closed (Default: Empty Function): Function that triggers after the last remaining open window was closed. Receives the instance as an argument.

before_toggle (Default: Empty Function): Function that triggers before the toggle method. Receives the instance as an argument. If false is returned it aborts the execution.

after_toggle (Default: Empty Function): Function that triggers after the toggle method. Receives the instance as an argument.

before_create (Default: Empty Function): Function that triggers before the create method. Receives the instance as an argument. If false is returned it aborts the execution.

after_create (Default: Empty Function): Function that triggers after the create method. Receives the instance as an argument.

before_destroy (Default: Empty Function): Function that triggers before the destroy method. Receives the instance as an argument. If false is returned it aborts the execution.

after_destroy (Default: Empty Function): Function that triggers after the destroy method. Receives the instance as an argument.

on_click (Default: Empty Function): Function that triggers when the window is clicked.

on_middle_click (Default: Empty Function): Function that triggers when the window is middle_clicked.

on_wheel_down (Default: Empty Function): Function that triggers on mouse scroll wheel down.

on_wheel_up (Default: Empty Function): Function that triggers on mouse scroll wheel up.

on_overlay_click (Default: Empty Function): Function that triggers when the overlay is clicked.

on_titlebar_click (Default: Empty Function): Function that triggers when the titlebar is clicked.

on_x_button_click (Default: Empty Function): Function that triggers when an X close button is clicked.

disable_transformations (Default: false): Disables transformations applied to windows to center them or put them in a certain place. Applies top and left to 0 as well.

disable_content_padding (Default: false): Doesn't apply padding to content.

full_content (Default: false): Makes content height 100vh and width 100vw.

Example:
let msg_test = Msg.factory({
    id: "test",
    class: "black",
    window_x: "floating_left",
    after_show: function(instance) {
        instance.set(instance.html() + ", Mr. Roboto");
    },
    after_set: function(instance) {
        console.log("instance.content.innerHTML set to: " + instance.html());
    },
    before_close: function(instance) {
        return confirm("Are you sure?");
    }
})

msg_test.show("Domo Arigato")
Test It

Properties

instance.container: The Msg-container html element.

instance.overlay: The Msg-overlay html element.

instance.overlay_x: The Msg-overlay-x html element.

instance.topbar: The Msg-topbar html element.

instance.titlebar: The Msg-titlebar html element.

instance.window_inner_x: The Msg-window-inner-x html element.

instance.window_floating_x: The Msg-window-floating-x html element.

instance.window: The Msg-window html element.

instance.content-container: The Msg-content-container html element.

instance.content: The Msg-content html element.

instance.progressbar-container: The Msg-progressbar-container html element.

instance.progressbar: The Msg-progressbar html element.

instance.options: The options object of the instance.

Methods

instance.show(html): Opens a window with the received string or html element as its content and puts it at the top of the zStack.

instance.show([title, html]): An alternative way to call show is passing an array with the title for the titlebar and the content html. Useful if you have the titlebar enabled and you want to change both things in the same call.

instance.show(): If no arguments are passed to show(), it displays the window with the last used html or the one passed to set() and puts it at the top of the zStack.

instance.set(html): Updates the html of the window without opening it. This is useful if you want to prepare the content without showing the window or if you want to change the content of the window without triggering the show events.

instance.set_or_show(html): If the window is open and at the top of the stack it changes the html content by calling set(). If the window is closed or not at the top of the stack it opens the window and shows the html content by calling show().

instance.set_title(html): Updates the html of the titlebar. This doesn't open the window.

instance.close(): Closes the window.

instance.toggle(): If the window is closed it opens it. If the window is open it closes it.

instance.html(): A shortcut for instance.content.innerHTML. Returns "" if the html elements have not been created yet.

instance.title_html(): A shortcut for instance.titlebar.innerHTML. Returns "" if the titlebar element is not created.

instance.is_open(): Returns true if the window is open.

instance.any_open(): Returns true if any window with any id is open.

instance.any_higher_open(): Returns true if any window with zStack_level 2 is open. These are usually modals and windows.

instance.any_lower_open(): Returns true if any window with zStack_level 1 is open.

instance.num_open(): Returns the number of windows open.

instance.num_open_higher(): Returns the number of windows open with zStack_level 2. These are usually modals and windows.

instance.num_open_lower(): Returns the number of windows open with zStack_level 1.

instance.create(): Creates the html elements if they don't exist yet. This is done automatically on the first show() or set(), but there might be cases where you might want to create them first without showing anything.

instance.recreate(): Removes the html elements from the dom and creates them again. This should be called after ids or classes are changed.

instance.destroy(): Removes the html elements from the dom.

instance.remove(): Destroys the html elements and removes the instance from the instance registry. So it won't appear in instance.instances() for example.

instance.highest_zIndex(): Returns the highest z-index among all the created Msg-container elements. If it retuns -2000 it means no elements have been created.

instance.highest_instance(): It returns the instance with the highest z-index. If none is open it returns false.

instance.is_highest(): Returns true if the window is visible and at the top of the zStack.

instance.to_top(): Puts an already opened window at the top of the zStack. This is done automatically by show(), but there might be cases where you want to do this without triggering the show events.

instance.check_options(): This is done automatically when creating an instance. It checks the options object and applies the corresponding defaults to undefined properties.

instance.set_progress(percentage): Fills the progressbar to the specified percentage.

instance.get_progress(): Returns the current percentage of the progressbar.

instance.instances(): Returns a list with the created instances.

instance.higher_instances(): Returns a list with the created instances with zStack_level 2. These are usually modals and windows.

instance.lower_instances(): Returns a list with the created instances with zStack_level 1.

instance.get_instance_by_id(id): Returns an instance that has the specified instance id.

instance.show_all(): Opens all the windows.

instance.close_all(): Closes all the windows.

instance.close_all_higher(): Closes all the windows with zStack_level 2. These are usually modals and windows.

instance.close_all_lower(): Closes all the windows with zStack_level 1.

instance.create_all(): Creates the html elements of all the instances.

instance.recreate_all(): Recreates the html elements of all the instances.

instance.destroy_all(): Removes the html elements of all the instances.

instance.hide_titlebar(): Hides the titlebar including the inner_x. The whole topbar is hidden.

instance.show_titlebar(): Shows the titlebar including the inner_x. The whole topbar is shown.

Presets

preset: "popup"
instance.options.class = "green";
instance.options.enable_overlay = false;
instance.options.position = "bottomright";
instance.options.remove_after_close = true;
instance.options.zStack_level = 1;
instance.options.window_width = "460px";
instance.options.lock = false;

preset: "popup_autoclose"
instance.options.class = "green";
instance.options.enable_overlay = false;
instance.options.position = "bottomright";
instance.options.autoclose = true;
instance.options.enable_progressbar = true;
instance.options.remove_after_close = true;
instance.options.zStack_level = 1;
instance.options.window_width = "460px";
instance.options.lock = false;

preset: "window"
instance.options.window_height = "100vh";
instance.options.window_min_height = "100vh";
instance.options.window_max_height = "100vh";
instance.options.window_width = "100vw";
instance.options.window_min_width = "100vw";
instance.options.window_max_width = "100vw";
instance.options.disable_transformations = true;
instance.options.disable_content_padding = true;
instance.options.full_content = true;
instance.options.window_x = "none";

Note: It's advised to not modify the "display" or "z-index" css properties of the Msg HTML elements since they are handled internally.

One Last Demo

GitHub    Open Wiki    Issues