Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/loadingio/ldcover

popup / dialog library
https://github.com/loadingio/ldcover

Last synced: 19 days ago
JSON representation

popup / dialog library

Awesome Lists containing this project

README 

          
# 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, `root`is 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.



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



    
 ... 



## 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:



    


       OK 

       Cancel 

    



use get function to wait for the return value:



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



## Todo



 - implement all this nice transitional effect:

   - https://tympanus.net/Development/ModalWindowEffects/

   - https://tympanus.net/Development/PageTransitions/



## License



MIT