njbox v3.0.3

njBox

Highly customizable vanilla javascript modal window.

Also plugin can do lightboxes and tooltips/popovers.

React/Vue/Angular wrapper - todo

DOTA 2 popup example

• Install
  • npm
  • manual
• Dependencies
• Usage
  • "Native" dialogs (alert, confirm, prompt)
• Addons
  • Gallery addon
  • Popover addon
• Examples
• Customization
  • Animation
    • Integration with Animate.css
  • HTML API
  • Delegate attributes
  • JS API
  • Options
  • Templates
  • Text
  • Changing default settings
• Events
• Tips && tricks
• Modal instance structure
  • Receiving instance
  • Instance description
• License

Install

npm

npm i njbox -S

manual

1. Download njBox.min.css and njBox.min.js files from the dist folder.
2. Include css in head

<link rel="stylesheet" href="njBox.min.css" />

3. Include js before closing </body> tag

<script src="njBox.min.js"></script>

Dependencies

Plugin have no dependencies and support all modern browsers (ie11+). But, if you need to support older browsers, you can include jQuery, plugin will find and use it, you don't need to configure anything here. Also if you need ie10, 9 for example, you can insert some polyfills without jQuery at all.

Usage

You can initialize plugin in few ways: 1) Bootstrap style autoinitialization (HTML api, without js at all), all settings you should set in data-njb-* attributes

Codepen example: simple modal HTML API

Codepen example: gallery HTML API

<a href="#modalDiv" data-toggle="modal">Show popup</a>
<!-- or -->
<button data-toggle="modal" data-njb-content="#modalDiv">Show popup</button>

<!-- or gallery (with gallery addon)-->
<div data-njb-gallery="a" data-toggle="modal">
  <a href="img1.jpg"><img src="img1.jpg"></a>
  <a href="img2.jpg"><img src="img2.jpg"></a>
  <a href="img3.jpg"><img src="img3.jpg"></a>
</div>

2. Javascript style (if you need callbacks or advanced api)

Codepen example: simple modal JS API

Codepen example: gallery JS API

HTML

<a href="#modalDiv" id="myModal">Show popup</a>
<div id="modalDiv">
  my modal window
</div>

javascript

var modal = new njBox('#myModal')
// or
var modal = new njBox({elem:'#myModal'})
// or with options
var modal = new njBox('#myModal', {scrollbar:'show'})
// or
var modal = new njBox({elem: '#myModal', scrollbar:'show'})

// gallery example (only with gallery addon)
var gallery = new njBox({
  elem: '.gallery',
  gallery: 'a'
})

"Native" dialogs (alert, confirm, prompt)

You can easily imitate native dialogs with njBox!

Codepen example: "alert"

Codepen example: "confirm"

Codepen example: "prompt"

Addons

njBox very very friendly to customization, seems you can customize everything you want.

A convenient way to expand functionality of main plugin are addons, they add new cool features to main plugin, you can use them all together. Now njBox had 2 addons: lightbox gallery addon and popover addon. Usage is very simple, just add files after njBox.js.

<script src="njBox.js"></script>
<script src="njBox-gallery.js"></script>
<script src="njBox-popover.js"></script>

Css for this addons already inside njBox.css.

Gallery addon

While main plugin allows to show single images, this addon adds possibility of galleries (lightboxes). For creating gallery, option "gallery" required. Also "wrap" element is required for gallery items, initialization can be produced only on one element, while all items inside.

Options added with gallery addon: gallery, arrows, start, loop, preload. Descriptions you can read in options section

Not only images can be inside, you can use any type of content in gallery.

Codepen example: gallery from multiple content types

HTML API example

<div data-njb-gallery="a" data-toggle="modal">
  <a href="#modal" data-njb-header="some header in this slide">modal link</a>
  <a href="img1.jpg" title="title via atribute">image one</a>
  <a href="img2.jpg" data-njb-title="title via data atribute">image two</a>
  <a href="img3.jpg">image three</a>
  <a href="img4.jpg">image four</a>
</div>

JS API example

<div class="gallery">
  <a href="#modal" data-njb-header="some header in this slide">modal link</a>
  <a href="img1.jpg" title="title via atribute">image one</a>
  <a href="img2.jpg" data-njb-title="title via data atribute">image two</a>
  <a href="img3.jpg">image three</a>
  <a href="img4.jpg">image four</a>
</div>

var gallery = new njBox({
  elem: '.gallery',
  gallery: 'a'
})

Popover addon

Besides classic modal windows you can simply create tooltips/popovers with just adding popover addon! For creating tooltip/popover, option "layout:popover" required.

Options added with popover addon: 'layout:popover', trigger, placement, reverse, offset, boundary. Descriptions you can read in options section

HTML API example

<button data-toggle="modal" data-njb-layout="popover" data-njb-content="My tooltip!">some text</button>

JS API example

<button class="tooltip">some text</button>

var tooltip = new njBox({
  elem: '.tooltip',
  layout: 'popover',
  content: 'My tooltip!'
})

Examples

You can find a lot of examples in collection at codepen!

• DOTA2 popup example

• simple modal HTML API

• gallery HTML API

• simple modal JS API

• gallery JS API

• gallery from multiple content types

• animation with Animate.css

• custom close button

• custom close button with disabled native close

• data-njb-return, data-njb-ok, data-njb-cancel

• mixed options form HTML and JS

• callbacks

• events

• custom alert

• custom confirm

• custom prompt

• youtube video example

Customization

Animation

Everyone loves beautiful animations. I made a very easy way to add animations to your modals.

For such purpose you have few options. Main option is "anim" (see options) it's space separated string for show/hide animations. All what this option does is adding this classes to modal.

Built in animations are: scale, scaleIn, scaleOut, fade, fadeIn, fadeOut. Default naimation - scale.

!!! IMPORTANT !!! If you want one animation for showing and hiding, simple set option anim like this (anim:'scale'). For hiding wil be used reversed animation of show animation with adding .njb-anim-reverse class. But if you want different animation for showing and hiding you CANNOT set anim:'scale fade', you SHOULD set anim:'scaleIn fadeOut'. By default plugin just reverse show animation when hiding if no hide animation presented

  <a href="#modal" data-toggle="modal" data-njb-anim="fade">show modal</a>

Integration with Animate.css

Using this library very very easy. Just add css animate.css file in you <head>. Then use desired animations in "anim" option. This library required additional 'animated' class. For this purposes you can use 'animclass' options (animclass: 'animated')

Codepen example: animation with Animate.css

<html>
  <head>
    <link rel="stylesheet" href="njBox.min.css">
    <link rel="stylesheet" href="animate.min.css">
  </head>
  <body>
    <button data-toggle="modal" data-njb-anim="zoomInDown zoomOutDown" data-njb-content="content">some text</button>
    <script src="njBox.js"></script>
  </body>
</html>

HTML API

Plugin supports declarative html api. You can initialize and set options with html only, without any js.

For init you should set set data-toggle="modal" or data-toggle="box" attribute. (can be changed in njBox.defaults.autobind)

For options you should set data-njb-* attributes. If you have many options, they can be setted via one attribute in json format - data-njb-options='{"backdrop":false, "close":"inside", "scrollbar":"show"}' Please note, that it should be a VALID JSON

P.S. You can't use callbacks with html api.

Codepen example: simple modal HTML API

<a href="#modalDiv" id="myModal" data-toggle="modal" 
                                 data-njb-backdrop="false"
                                 data-njb-close="inside" 
                                 data-njb-scrollbar="show">
<!-- or -->
<a href="#modalDiv" id="myModal" data-toggle="modal"
                                 data-njb-options='{"backdrop":false, "close":"inside", "scrollbar":"show"}'>
Show popup</a>

Delegate attributes

Delegate attributes also part of HTML API. For most events we using delegate method that binds on elements with specific attribute. For example if you need custom close button in your modal, you don't need to manage it with js api (but of course you can), you can add to button data-njb-close attribute. Also this attributes used as markers for dom creation, if you need to customize templates.

Codepen example: custom close button

Codepen example: custom close button with disabled native close

Codepen example: data-njb-return, data-njb-ok, data-njb-cancel

List of interactive attributes:

Markers for dom creation:

JS API

"new njBox" returns instance of modal. Later you can call public methods on this instance.

P.S. All public method are chainable (like jQuery methods)

Codepen example: simple modal JS API

//create instance
var modal = new njBox('#myModalLink');
//use api
modal	
.show(index)//index - for gallery, from what index we should show gallery
.hide()
.position()//can be used, when you made your custom ui... or whatever
.destroy()
.update()//update just recreate all slides with current settings (can be used when you add images to gallery dynamically)
.on(event, handler)//add event listener
.off(event, handler)//remove event listener

//Gallery addon methods
.prev()
.next()
.goTo(index)

Also plugin have some useful static methods and properties on njBox class.

njBox.get(selector)//method tat return instance of modal from this selector/dom element
njBox.autobind(selector)//autoinitialize modals (bootstrap style) from data-attributes. It fires automatically on document.ready
njBox.addons//object with included addons (gallery, popover for example)
njBox.defaults//object with default options P.S. you can change it before any initialization
njBox.templates//object with default templates P.S. you can change it before any initialization
njBox.text//object with default text P.S. you can change it before any initialization
njBox.addAddon(name, addon)//register addon, addon structure you can see in njBox-gallery.js addon

//imitation of defaut dialog methods
njBox.alert(message, okCallback, cancelCallback)
njBox.confirm(message, okCallback, cancelCallback)
njBox.prompt(message, placeholder, okCallback, cancelCallback)//result from input you can gather from first argument in callbacks and in this.returnValue

var modal = new njBox({
  elem:'#myModal',
  backdrop: false,
  close: 'inside',
  scrollbar: 'show',
  onshow: function() {},
  onshown: function() {},
  onhide: function() {},
  onhidden: function() {}//more callbacks in advanced section
})

Options

Options will be gathered and from element (HTML API) and from options object from js api Codepen example: mixed options form HTML and JS

Options priority:

1. defaults from njBox.defaults
2. options passed as object in constructor (e.g. new njBox({content:"constructor"})
3. global JSON data object from data-njb-options (e.g. data-njb-options='{"content": "test2"}')
4. content form "href" attribute if it is link (only for "content" option) (e.g. <a href="#modal">show modal</a>)
5. content from "title" attribute (or other attribute form options, only for "title" option) (e.g. <a href="pathToImg" title="My awesome image!">show modal</a>)
6. data-njb-* separate options (e.g. data-njb-content="test3")

<a href="content from href" class="modal" data-njb-content="content from separate data" data-njb-options='{"content": "content from data options"}'>image</a>

var modal = new njBox({elem: '.modal', content: 'content from constructor'});

In this example "content" option calculated in next priority: 1) njBox plugin: meow, put some content here... (default text if "content" is undefined) 2) content from constructor 3) content from data options 4) content from href 5) content from data-njb-content

"content from separate data" eventually won and modal will show this text.

Templates

templates: {
  wrap: '<div class="njb-wrap"><div class="njb-items"></div></div>',
  backdrop: '<div class="njb-backdrop"></div>',
  modalOuter: '<div class="njb-outer" data-njb-outer></div>',
  modal: '<aside class="njb" tabindex="-1"></aside>',
  body: '<div class="njb__body" data-njb-body></div>',
  header: '<header class="njb__header" data-njb-header></header>',
  footer: '<footer class="njb__footer" data-njb-footer></footer>',
  close: '<button type="button" class="njb-ui__close" data-njb-close>×</button>',
  focusCatcher: '<a href="#!" class="njb-focus-catch">This link is just focus catcher of modal window, link do nothing.</a>',
  preloader:   '<div class="njb-preloader"><div class="njb-preloader__inner"><div class="njb-preloader__bar1"></div><div class="njb-preloader__bar2"></div><div class="njb-preloader__bar3"></div></div></div>',
  ui:          '<div class="njb-ui"></div>',
  title:       '<div class="njb-ui__title-outer"><div class="njb-ui__title-inner" data-njb-title></div></div>',

  //Gallery addon templates
  count:       '<div class="njb-ui__count"><span data-njb-current>1</span> / <span data-njb-total>2</span></div>',
  prev:        '<button type="button" class="njb-ui__arrow njb-ui__arrow--prev" data-njb-prev></button>',
  next:        '<button type="button" class="njb-ui__arrow njb-ui__arrow--next" data-njb-next></button>'
}

Text

text: {
  _missedContent: 'njBox plugin: meow, put some content here...',//text for case, when slide have no content
  preloader:      'Loading...',//title on preloader element
  imageError:     '<a href="%url%">This image</a> can not be loaded.',
  close:          'Close (Esc)',//title on close button
  ok:             'Ok',//text on 'ok' button when dialog modal(alert, prompt, confirm) or in any other custom type
  cancel:         'Cancel',//text on 'cancel' button when dialog modal(alert, prompt, confirm) or in any other custom type
  placeholder:    ''//placeholder for prompt input
  
  //Gallery addon text
  current:        'Current slide',
  total:          'Total slides',
  prev:           'Previous (Left arrow key)',//prev slide button title
  next:           'Next (Right arrow key)',//next slide button title
}

Changing default settings

If you need to change default settings to all modals in your project, you can do it via changing njBox.defaults

njBox.defaults.autobind = '.myAutoBindSelector';
njBox.defaults.scrollbar = 'show';
njBox.defaults.backdrop =  false;

Events

• Helper events pursue a single goal - when they fire, all user/addons callbacks related to helper already fired. It's important for addons, as example we can use options_set event. One addon change some option, and second addon also changes this option. You can use options_setted event to be sure all callbacks/addons fires and now options are final.

1. Using callbacks

Codepen example: callbacks

var modal = new njBox({
  elem:'#myModalLink',
  onshow: function() {
    console.log('Show my modal! :)')
    // this in callbacks always refers to modal instance, so you have access to: this.o, this.dom, this.items, this.state
  },
  onhidden: function() {
    console.log('My modal is hidden :(')
    // this in callbacks always refers to modal instance, so you have access to: this.o, this.dom, this.items, this.state
  }
});

2. Listen events on created modal instance with .on method

Codepen example: events

var modal = new njBox({elem:'#myModalLink'});
modal.on('shown', function() {
  console.log('My modal is shown!')
})
//or at once
var modal = new njBox({elem:'#myModalLink'})
                                            .on('shown', function() {
                                              console.log('My modal is shown!')
                                              // this in event callbacks always refers to modal instance, so you have access to: this.o, this.dom, this.items, this.state
                                            }).on('hidden', function() {
                                              console.log('My modal is hidden!')
                                            })

Tips && tricks

• By default initialization of plugin is async. If you need sync initialization you can call it directly

var modal = new njBox({elem:'.el'})._init();

• Common case when you need custom close button. You can do it by adding data-njb-close attribute to some element inside modal without any javascript. As variant you can set close option to "inside".

<div id="modal">
  some content
  <button data-njb-close>close modal</button>
</div>

• You can open modal only with html. See Usage section.
• You can open modal only with js. "content" option is required.

  var modal = new njBox({content:'<h1>My awesome modal</h1>'})
  modal.show();
  //or
  new njBox({content:'<h1>My awesome modal</h1>'}).show()

• Options "content" and "placement"(from gallery addon) can be a function. As example lets see on static njBox.alert method.

export function alert(content, okCb, cancelCb) {
  return new njBox({
    content: function () {
      return (
`<div class="njb__body">
${content || this._text._missedContent}
</div>
<div class="njb__footer">
  <button data-njb-ok>${this._text.ok}</button>
</div>`);
    },
    type: 'template',
    role: 'alertdialog',
    out: false,
    onok: okCb,
    oncancel: cancelCb
  }).show()
}

• return false from show/hide callbacks will prevent action. As example - situation when window width is small - open image link directly in browser, without popup.

<a href="linkToImage" class="el">Show image</a>

var modal = new njBox({
  content: 'test content',
  onshow: function() {
    var open = true;
    if(window.innerWidth <= 480) {
      open = false;
    }

    return window.innerWidth <= 480;
  }
})

• Static margin top. Some people wants plugin not centered and be fixed somwhere at top like bootstrap, and here you can find way to do this. Plugin make centering via pure ccs, so we can change it via css styles.

  .modalStaticTop .njb-outer:before {
    display: none;
  }
  .modalStaticTop .njb {
    margin-top: 50px;
  }

new njBox({
  elem: '.el',
  class: 'modalStaticTop'
})

• Fixed width/height. Because of pure css centering, you can set your custom width/height via usual css. But its not good idea, due to loss of responsiveness.

  .fixedWidthHeight .njb {
    width: 600px;
    height: 450px;
  }

new njBox({
  elem: '.el',
  class: 'fixedWidthHeight'
})

• If you need to use image from url like this (http://lorempixel.com/400/200) without proper extension (.jpg, .png, etc) autodetection of image will fail, just set type manual.

<a href="http://lorempixel.com/400/200" data-njb-type="image">img1</a>

Modal instance structure

Receiving instance

new njBox() returns modal instance. Also every public method return instance, thats why all public methods chainable like jQuery methods. You can get accesss to instance by 4 ways: 1. save to variables on creation

var modalInstance = new njBox();

var modalInstance = new njBox().show();

2. use static method njBox.get(elem)

var modalInstance = njBox.get(selector)

3. from dom property on inited element (of course after initialization and you should remember that initialization is async, examples in Tips && tricks)

<a href="#modal" class="modalLink">open modal</a>

var modalInstance = document.querySelector('.modalLink').njBox

4. "this" in all callbacks binds to modalInstance

new njBox({
  elem: '.el',
  onshown: function() {
    var modalInstance = this;
    this.hide();
  }
})
new njBox({
      elem: '.el'
    }).on('shown', function() {
      this.hide();
    })

Instance description

Now lets see to instance structure:

  var modal = {
    $: function(){},//link to jQuery if it included in page, if no - link to light custom wrapper that have same as jquery syntax
    dom: {},//object with links to created by plugin dom elements (wrappers, buttons, ui)
    items: [],//array with object items (slides) to show. For usual modal always 1 item will be present, for galleries here will be object for every slide
    o: {},//options, object with computed options
    state: {},//internal state of plugin (this state resetted after every hiding modal)
    _defaults: {},//default settings
    _events: {},//all callbacks lives here
    _g: {},//internal global state that not resetted after every hide like "this.state"
    _handlers: {},//all links to event handlers lives here
    _templates: {},//self-explanatory object. html templates.
    _text: {}//all text lives here
  }

Public and static njBox methods can be found here.

License

njBox is licensed under the MIT License