minsky-overlay v1.0.0

Overlay

Easy to setup/manage/maintain overlay class

Incorporates all the logic behind hiding/showing an overlay with backdrop to the page. For every instance that is created, a unique dom element is used as overlay so instance's interference will be limited (compared to v1 where only 1 dom element was used for every instance)

Class type: Component

Dependencies

• Component 1.0.0+
• PluginManager 1.0.0+

Getting started

A minimal set of parameters is required for the overlay to work properly. It will still manage to work if no content is given yet it'll remain empty and obsolete. SimpleOverlay will generate a whole new component internally which will be accessible through the el property.

const overlay = new SimpleOverlay({
	el: {
		content: 'Some content'
	}
});

overlay.show();

Or extend the class as is encouraged

export default class CustomOverlay extends SimpleOverlay {

	// constructor
	constructor(args = {}, objectName = 'Custom Overlay') {
		// edit args befor it is passed to the constructor
		args.el = {
			content: 'Some content of the customOverlay'
		}

		// call super constructor
		super(args, objectName);
	}
}

Constructor Parameters

args

Type: Object Default: {}

Config options that will be used when instance is created

objectName

Type: String Default: 'SimpleOverlay'

Object name that will be used as recognisable identifier and as prefix in logs

Interface

Options

el

Type: Object Default: {}

The settings needed to generate a new DOM element. The content is the most important one as it will be used to apply content to the overlay. List of possible properties:

• Content String/DOM
• Attributes Object Applies attributes with values to the generated dom element
• Components Object Defines the visibility toggles of some sub-components (closeBtn, backdrop)

trigger

Type: DOM/Array Default: []

List of external dom elements that may trigger the overlay on click. Eventlisteners will be managed internally

keepInDom

Type: Boolean Default: false

When true, it will make sure the generated overlay will be kept accessible in the DOM tree.

parent

Type: DOM Default: body

Defines the parent DOM element it needs to inject itself. When no parent is given, it will be injected at the bottom of the body to ensure z-index positioning.

generators

Type: Object Default: {}

A way to override internal dom generators.

plugins

Type: Object Default: {}

Plugin configuration object, make sure the required plugins are included in the project for them to work. Plugin examples:

• Ajax: calls the backend to be provided with content
• HashQuery: adds auto-show functionality based on hash content in the querystring
• History: Adds history state management

blockScroll

Type: Boolean Default: true

Adds a scroll block to the parent element when the instance is activated

Properties

el

Type: DOM

Contains the dom element generated by the instance.

triggers

Type: Array

Contains the list of triggers it listens to.

visible

Type: Boolean

Contains the visibility state of the dom element. State-change will be triggered when edited directly (visible => true = show())

hiding

Type: Boolean

Will be true if the instance is busy hiding the dom element.

showing

Type: Boolean

Will be true if the instance is busy showing the dom element.

quitOnEscape

Type: Boolean

Flag for overlay to close the element when escape is pressed. Can be edited directly at runtime.

... Component properties

Methods

show

Parameters: instante:boolean Return: undefined

Initiates the sequence the instance has to go through to show the dom element. May block the scroll if required

hide

Parameters: instante:boolean Return: undefined

Initiates the sequence the instance has to go through to hide the dom element. Will unblock the scroll

toggle

Parameters: instante:boolean Return: undefined

Will toggle the visibility state of the element. show() or hide() methods will be called internally.

addTrigger

Parameters: trigger:DOM Return: undefined

Adds a trigger to the list of triggers the instance has to listen to

removeTrigger

Parameters: trigger:DOM Return: undefined

Removes the trigger of the list of triggers the instance has to listen to.

setContent

Parameters: content:String/DOM Return: undefined

Replaces the content of the overlay entirely without any destruction process.

To Do

• Support Overlay DOM element to be passed to the el parameter in the constructor as it was the case in V1 & V2

Changelog

3.6.0

• scrollBlocked event added
• scrollUnBlocked event added
• Fix: Allow trigger to close the overlay when open by toggling the overlay instead of forcing a show on every click.

3.5.0

• Change: Added missing css class that should be applied to the given triggers, as it was the case in V2

3.4.0

• Change: quitOnEscape parameter added to allow the overlay to hade when the use taps the escape button

3.3.1

• Fix: Body scroll block rewritten again since it still contained some issues after browser behavior changes.

3.3.0

• Fix: Faulty body scroll block rewritten

3.2.0

• Change: Debug support added
• Change: Auto init block added
• Change: Plugin support added
• Change: ContentChanged Event added
• Change: El settings for sub-component visibility added

3.0.1

• Fix: Component selectors didn't use baseclass variable.

3.0.0

• Partial rewrite of SimpleOverlay v2 in ES6