tiny popup / dialog library
npm install ldcovervanilla popup / dialog library.
install with npm:
npm install ldcover
include required files ( index.js and index.css ), and create a ldcover object:
var ldcv = new ldcover({ ... });
- root: container.
- you can use template tag as root for better performance during initialization. The first child in the template will be used as the real root for this ldcover.
- type: additional class to add. default: ''. space seprated.
- transform-fix: true/false. default: false.
add a 'shown' class after ldcover is shown, which removes transform from .inner block.
useful when content is blurred due to transform, but might lead to glitches when doing transition. use it carefully.
- delay: milliseconds. default 300. should be aligned with transition duration. use to control 'shown' and 'running' classes.
- autoZ: update root's z-index automatically. default true.
- baseZ: the minimal z-index of root. default 3000.
- with autoZ, ldcover keeps track of all cover' z-index and always use larger z-index for newly toggled covers.
baseZ is then used as a base value for all autoZ covers.
however, this may conflict with customized zmgr.
- zmgr: set z-index manager for this cover.
- baseZ will be used to call zmgr, which set a lower bound of z-index.
set baseZ to 0 for zmgr to correct work with lower values.
- animation: optional space separated class list.
- will be added to .inner node when toggling on, and removed when toggling off.
- handy for adding customized animation from libraries like transition.css or animate.css.
- escape: should pressing escape key close the dialog. boolean, default true, optional.
- lock: default false. if set to true, only API or data-ldcv-set could close this modal.
- resident: default false. if set to true, DOM for this cover will always attached under document. otherwise false.
- not resident node will be attached under container or document.body.
- inPlace: default true. if set to false, root will be removed from original parent and re-added under body.
- container: container for non-resident cover. by default parent of DOM or document.body
- by default, non-resident cover is inserted to the location we find it. Set container to change this behavior.
- when container is null, root is appended at the end of document.body when toggled.
- otherwise, rootis appended at the end of container when toggled.
- toggle(state, data): toggle on/off ldcover.
- data: optional parameter, which will be sent in data event.
- program that manages the content of this cover can use this data to update its content.
- get(data): toggle on ldcover and return a promise, which will only be resolved when ldcover.set is called.
- data: see toggle above.
- set(v, hide=true): set value, which resolve promises from get, and hide ldcover if hide = true.
- use data-ldcv-set on elements to automatically set value when elements are clicked.
- cancel(err, hide=true): reject promise returned by get with given error err.
- a default Error object with {name: 'lderror', id: 999} will be used if err is omitted.
- ldcover is hidden if hide = true. true by default.
- use data-ldcv-cancel on elements to automatically cancel when clicked.
- on(event, cb): listen to certain event. evnets:
- toggle.on: when ldcover is toggled on. may fired before shown.
- toggle.off: when ldcover is toggled off. may fired before hidden.
- toggled.on: when ldcover is toggled on. fired after shown.
- toggled.off: when ldcover is toggled off. fired after hidden.
- isOn(): is this modal active ( opened ). return true or false
- lock(): lock this cover. ( can't be dismissed by escaping )
- alternatively, you can lock cover by adding data-lock="true" attribute to cover root.
- root(): get cover root node.
- zmgr(mgr): set z-index manager for this cover. return the zmgr used if mgr is omitted.
- baseZ will be used to call zmgr, which set a lower bound of z-index.
set baseZ to 0 for zmgr to correct work with lower values.
- append(node): insert node in the base node of this cover.
- useful if this ldcover is created without root.
- destroy(opt): object destroyer. opt is an option object with following fields:
- removeNode: should ldcover remove DOM of this cover. default false
- by default, DOM of this cover will be inserted back in DOM after this ldcover object been destroyed.
- to also wipe out the DOM element, set removeNode to true.
- zmgr(zmgr): set a shared z-index manager. useful to manager widget z-index globally.
this manager should provide following methods:
- add(baseVal, size): return actual added value.
- baseVal: hint value for the z-index we'd like to use
- size: hint size about how large the object we added is
- remove(val): remove val ( returned by add ) from this manager.
as described above, baseZ will be used to call zmgr, which set a lower bound of z-index.
set baseZ to 0 in ldcover instance so zmgr can work correclty with lower values.
A simple ldcover popup are built with following html structure:
* .ldcv - topmost, fullscreen container
* .base - control the overall size and position for this box ( could be omit )
* .inner - dialog container. constraint size. transition animation goes here
one can decorate ldcover widgets by adding classes over the outmost element. following classes are defined by default:
* .ldcv.bare:
- no covered bk.
- custom position for .ldcv > .base
- overflow: visible for .ldcv > .base > .inner (why?)
* .ldcv.lg, .ldcv.md
- different size of panel. instead of using this, you could also set size directly on .base element.
* .ldcv.full - fullscreen modal.
* .ldcv.full-sm, .ldcv.full-md, .ldcv.full-lg - conditional fullscreen modal. break point:
- sm: < 576px
- md: < 768px
- lg: < 960px
* .ldcv.light - light overlay bk
* .ldcv.mini - non-blocking, float style dialog with following position available:
- .ldcv.mini.left
- .ldcv.mini.right
- .ldcv.mini.top
- .ldcv.mini.bottom
* .ldcv.inline - inline cover. Won't affect local layout
* centering
- by default .base is centered with vertical-align + ::after pseudo class. instead you can choose different methods, described below:
- .ldcv.margin-centered
- center with margin: auto + left/right/top/bottom: 0 and position: absolute. need width/height to be provided.
- .ldcv.transform-centered
- with transform-center, .base is centered with left: 50%, top: 50% + transform: translate(-50%,-50%), which don't need width/height to be provided anymore.
- NOTE: this might causes content to be blur, so use it carefully.
* .ldcv.scroll:
- add scroll class on the ldcv node when you expect the modal content to longer than a screen's height. It makes the modal scrollable by users.
* .ldcv.autogap:
- add autogap class on the ldcv node to automatically adjust cover padding and margin along with responsive scenario, with two additional classes:
- .outer-gap: only apply margin style. Used alone without autogap
- .autogap.nested-gap: apply padding style in nested div. Used along with autogap
* alternative transition
- you can use alternative transition by adding additional class in .ldcv, including following classes:
- ldcv-scale
- ldcv-zoom
- ldcv-vortex
- ldcv-slide-rtl
- ldcv-slide-ltr
- ldcv-slide-ttb
- ldcv-slide-btt
- ldcv-flip-h-left
- ldcv-flip-h-right
- ldcv-flip-v-top
- ldcv-flip-v-bottom
- ldcv-fade
- example of setting a alternative transition:
Simple popup could be configured with automatically set invocation to resolve promises waited by get. use data-ldcv-set attribute on elements to indicate what values to be passed into set:
use get function to wait for the return value:
ldcv.get!then -> if it == "1" => "OK" else "Cancel"
- implement all this nice transitional effect:
- https://tympanus.net/Development/ModalWindowEffects/
- https://tympanus.net/Development/PageTransitions/
MIT