Skip to content

Latest commit

 

History

History
179 lines (137 loc) · 8.08 KB

README.md

File metadata and controls

179 lines (137 loc) · 8.08 KB

ldcover

vanilla popup / dialog library.

Usage

install with npm:

npm install ldcover

include required files ( index.js and index.css ), and create a ldcover object:

var ldcv = new ldcover({ ... });

Constructor Options

  • 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.

Object Methods

  • 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.

Class Method

  • 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.

Spec. and structure

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.
  • 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:
    ...

Action

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:

<div class="ldcv">
  <button data-ldcv-set="1"> OK </button>
  <button data-ldcv-set="0"> Cancel </button>
</div>

use get function to wait for the return value:

ldcv.get!then -> if it == "1" => "OK" else "Cancel"

Todo

License

MIT