README

Polipop

GitHub package.json version GitHub

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:

Download the latest release
Use a CDN service
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: