Polipop

A dependency-free JavaScript library for creating discreet pop-up notifications.

Demo

See demo at minitek.github.io/polipop/.

Documentation

See documentation at minitek.gr/support/documentation/javascript/polipop.

Installation

There are several ways to install Polipop into your project:

1. Download the latest release
2. Use a CDN service
3. Install via NPM

1. Download the latest release

Link to dist/polipop.min.js:

<script src="/path/to/dist/polipop.min.js"></script>

Include the core stylesheet:

<link rel="stylesheet" href="/path/to/dist/css/polipop.core.min.css" />

Include a theme stylesheet (eg. default):

<link rel="stylesheet" href="/path/to/dist/css/polipop.default.min.css" />

2. Use a CDN Service

UNPKG

Link to dist/polipop.min.js:

<script src="https://unpkg.com/polipop/dist/polipop.min.js"></script>

Include the core stylesheet:

<link
    rel="stylesheet"
    href="https://unpkg.com/polipop/dist/css/polipop.core.min.css"
/>

Include a theme stylesheet (eg. default):

<link
    rel="stylesheet"
    href="https://unpkg.com/polipop/dist/css/polipop.default.min.css"
/>

jsDelivr

Link to dist/polipop.min.js:

<script src="https://cdn.jsdelivr.net/npm/polipop/dist/polipop.min.js"></script>

Include the core stylesheet:

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/polipop/dist/css/polipop.core.min.css"
/>

Include a theme stylesheet (eg. default):

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/polipop/dist/css/polipop.default.min.css"
/>

3. Install via NPM

npm install polipop

Include distribution files

Link to dist/polipop.min.js:

<script src="node_modules/polipop/dist/polipop.min.js"></script>

Include the core stylesheet:

<link
    rel="stylesheet"
    href="node_modules/polipop/dist/css/polipop.core.min.css"
/>

Include a theme stylesheet (eg. default):

<link
    rel="stylesheet"
    href="node_modules/polipop/dist/css/polipop.default.min.css"
/>

Import source files

Import ES module:

import Polipop from 'polipop';

Import the core stylesheet:

@import 'node_modules/polipop/src/sass/core';

Import a theme stylesheet (eg. default):

@import 'node_modules/polipop/src/sass/default';

Building

The following NPM scripts are available:

• build:css - Builds CSS files from SCSS files.
• build:js - Builds JavaScript files.
• build - Builds all JavaScript and CSS files.
• lint - Lints source JavaScript files.

Initialization

Creating a new Polipop instance

var polipop = new Polipop(selector, options);

selector

Type: String

A selector `representing the id of the element on which to instantiate Polipop.

options

Type: Object

The Configuration options.

For example:

var polipop = new Polipop('mypolipop', {
    layout: 'popups',
    insert: 'before',
    pool: 5,
    sticky: true,
});

Adding a notification to the queue

Notifications are added into a queue. Queued notifications are then rendered automatically into the DOM at a specific time interval.

polipop.add({
    content: 'This is the message content.',
    title: 'Message',
    type: 'success',
});

See add method.

Configuration options

The display and behavior of Polipop can be adjusted via the configuration options. The options are passed as an object when initializing a new instance.

var polipop = new Polipop('mypolipop', {
    // Configuration options
    layout: 'popups',
    insert: 'before',
    pool: 5,
    sticky: true,
});

| Option | Type | Description | | ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | appendTo | String | Default: body A DOM element or selector string representing the element where the Polipop wrapper element will be appended to. Can only be set on class instantiation. | | block | String | Default: polipop The BEM block name which is used for generating css classes for all elements within the wrapper element. Can only be set on class instantiation. | | position | String | Default: top-right The position of the wrapper element within the viewport. Can only be set on class instantiation. Accepted values: top-left, center, top-right, bottom-right, bottom-left or inline. | | layout | String | Default: popups The layout of the Polipop wrapper. Can only be set on class instantiation. Accepted values: popups or panel. | | theme | String | Default: default The css theme of the Polipop wrapper. Accepted values: default, compact, minimal or any custom theme. Can only be set on class instantiation. | | icons | Boolean | Default: true A boolean designating whether each notification element displays an icon, according to the notification type. Can only be set on class instantiation. | | insert | String | Default: after Designates whether a notification element should be appended or prepended to the notifications container. Accepted values: after or before. | | spacing | Number | Default: 10 The vertical spacing between the notification elements. Can only be set on class instantiation. | | pool | Number | Default: 0 Limits the number of concurrent notification elements that can be rendered within the notifications container at any given time. A value of 0 means that there is no limit. | | sticky | Boolean | Default: false A boolean designating whether the notification elements should be removed automatically when they expire or whether they should stay in the DOM until they are removed manually. | | life | Number | Default: 3000 Expiration time for non-sticky notification elements in milliseconds. | | progressbar | Boolean | Default: false A boolean designating whether the life time progress bar will be displayed for each notification element. | | pauseOnHover | Boolean | Default: true A boolean designating whether the notifications expiration control should pause when hovering over the wrapper element. Can only be set on class instantiation. | | headerText | String | Default: Messages The text that is displayed inside the panel layout header. Can only be set on class instantiation. | | closer | Boolean | Default: true A boolean designating whether the closer button element will be displayed when there are rendered notification elements. Can only be set on class instantiation. | | closeText | String | Default: Close The text that is displayed inside the closer button element when the notifications queue is empty. | | loadMoreText | String | Default: Load more The text that is displayed inside the closer button element when the notifications queue contains queued notification objects. | | hideEmpty | Boolean | Default: false A boolean designating whether the 'panel' layout wrapper element will be hidden when there are no rendered notification elements. | | interval | Number | Default: 250 The time, in milliseconds, the timer should delay in between executions of the _loop function. Can only be set on class instantiation. | | effect | String | Default: fade The animation effect when adding or removing notification elements. Accepted values: fade or slide. | | easing | String | Default: linear The rate of the animation's change over time. Accepted values: linear, ease, ease-in, ease-out, ease-in-out or a custom cubic-bezier value. | | effectDuration | Number | Default: 250 The number of milliseconds each iteration of the animation takes to complete. | | ready | function() | A callback function invoked immediately after the wrapper element has been rendered into the DOM. | | add | function(object) | A callback function invoked immediately after a notification object has been added into the queue. The notification object is passed to the function as argument. | | beforeOpen | function(object, Element) | A callback function invoked immediately before a notification element has been rendered into the DOM. The notification object and the notification element are passed to the function as arguments. | | open | function(object, Element) | A callback function invoked immediately after a notification element has been rendered into the DOM but before the element's opening animation has started. The notification object and the notification element are passed to the function as arguments. | | afterOpen | function(object, Element) | A callback function invoked immediately after a notification element has been rendered into the DOM and the element's animation has finished. The notification object and the notification element are passed to the function as arguments. | | beforeClose | function(object, Element) | A callback function invoked immediately after the Polipop.beforeClose event has been triggered on an element but before the element's closing animation has started. The notification object and the notification element are passed to the function as arguments. | | close | function(object, Element) | A callback function invoked immediately after the element's closing animation has finished, immediately before the element has been removed from the DOM. The notification object and the notification element are passed to the function as arguments. | | click | function(MouseEvent, object, Element) | A callback function invoked immediately after a notification element has been clicked. The MouseEvent, the notification object and the notification element are passed to the function as arguments. |

Properties

A Polipop instance has the following public properties:

options

Type: Object

Default: Default configuration options

The default configuration options merged with instance options.

var options = polipop.options;

queue

Type: Array

Default: []

An array containing the queued notification objects.

var queue = polipop.queue;

elements

Type: HTMLCollection | null

Default: null

An object containing a collection of rendered notification elements.

var elements = polipop.elements;

wrapperHeight

Type: Number

Default: 0

The height of the wrapper element.

var wrapperHeight = polipop.wrapperHeight;

Methods

A Polipop instance has the following public methods:

getOption(key)

Retrieves the value of a property within the configuration options object. Accepts the argument:

{String} key - The property or method name.

For example:

var theme = polipop.getOption('theme');

setOption(key, value)

Sets the value of a property within the configuration options object. Accepts the arguments:

{String} key - The property or method name. {String|Number|Boolean|Function} value - The property or method value.

polipop.setOption('pool', 5);

add(notification)

Adds a notification object to the queue. Accepts the argument:

{Object} notification - A notification object.

The notification object has the following properties:

| Option | Type | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------ | | type | String | The notification type. Accepted values: default, info, success, warning or error. | | title | String | The notification title. | | content | String | The notification content. |

For example:

polipop.add({
    type: 'success',
    title: 'Message',
    content: 'This is the message content.',
});

enable()

Enables adding notification objects to the queue.

polipop.enable();

disable()

Disables adding notification objects to the queue.

polipop.disable();

pause()

Pauses the rendering and the expiration of notification elements.

polipop.pause();

unpause()

Unpauses the rendering and the expiration of notification elements.

polipop.unpause();

closeAll()

Removes all rendered notification elements from the DOM.

polipop.closeAll();

emptyQueue()

Deletes all notification objects from the queue.

polipop.emptyQueue();

destroy()

Removes the wrapper element from the DOM and stops the main loop that starts in the _init function.

polipop.destroy();

Events

A Polipop instance dispatches the following events:

ready

A callback function invoked immediately after the wrapper element has been rendered into the DOM.

var polipop = new Polipop('polipop', {
  ready: function () {
    ...
  },
});

add

A callback function invoked immediately after a notification object has been added into the queue. Accepts the argument:

{Object} notification - A notification object.

var polipop = new Polipop('polipop', {
  add: function (notification) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  add: function (notification) {
    ...
  }
});

beforeOpen

A callback function invoked immediately before a notification element has been rendered into the DOM. Accepts the arguments:

{Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  beforeOpen: function (notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  beforeOpen: function (notification, element) {
    ...
  }
});

open

A callback function invoked immediately after a notification element has been rendered into the DOM but before the element's opening animation has started. Accepts the arguments:

{Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  open: function (notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  open: function (notification, element) {
    ...
  }
});

afterOpen

A callback function invoked immediately after a notification element has been rendered into the DOM and the element's animation has finished. Accepts the arguments:

{Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  afterOpen: function (notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  afterOpen: function (notification, element) {
    ...
  }
});

beforeClose

A callback function invoked immediately after the Polipop.beforeClose event has been triggered on an element but before the element's closing animation has started. Accepts the arguments:

{Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  beforeClose: function (notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  beforeClose: function (notification, element) {
    ...
  }
});

close

A callback function invoked immediately after the element's closing animation has finished, immediately before the element has been removed from the DOM. Accepts the arguments:

{Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  close: function (notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  close: function (notification, element) {
    ...
  }
});

click

A callback function invoked immediately after a notification element has been clicked. Accepts the arguments:

{MouseEvent} event - The click event. {Object} notification - A notification object. {Element} element - A notification element.

var polipop = new Polipop('polipop', {
  click: function (event, notification, element) {
    ...
  }
});

polipop.add({
  type: 'success',
  title: 'Message',
  content: 'This is the message content.',
  click: function (event, notification, element) {
    ...
  }
});

Credits

• Yannis Maragos - Author

License

Polipop is dual-licensed under the GNU General Public License (GPL) and the Polipop Commercial License.

Open source license

If you are creating an open source application under a license compatible with the GNU GPL license v3, you may use the library under the terms of the GPLv3.

Commercial license

If you want to use Polipop in a commercial project or product, you'll need to purchase a commercial license.