Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/depthdev/flagstonejs

Dynamic & responsive tiling, with drag & drop, and touch support. Generically known as a JavaScript grid, or JavaScript tiling/tiles.
https://github.com/depthdev/flagstonejs

Last synced: 5 days ago
JSON representation

Dynamic & responsive tiling, with drag & drop, and touch support. Generically known as a JavaScript grid, or JavaScript tiling/tiles.

Awesome Lists containing this project

README 

        
# FlagstoneJS

Dynamic & responsive tiling, with drag & drop, and touch support.

(Generically known as a JavaScript grid, or JavaScript tiling/tiles.)



[Demo](http://depthdev.com/modules)






## Docs



### Download the ES5 minified version, or ES6 expanded version.



---



### Optional Recommended Actions

* For instances with large amounts of "stones," it's recommended that you hard code this attribute and style to the Flagstone element: `style="visibility:hidden;"`.  

* For a quicker visual setup, make sure the webpage *always* or *never* has a scrollbar. An "always" CSS suggestion would be `body{min-height:101vh;}`.



---



### Instantiate 1 or more Flagstone instances

NOTE: Calling `flagstone()` returns a new Flagstone instance.



`const fs = flagstone(); // Requires the "bed" element to have a class of ".flagstone" on it.`



OR



`const fs = flagstone(element || 'querySelector string'); // Pass in the "bed" element to bootstrap or a querySelector string`



OR with one or more options



**const fs = flagstone(element** */\* The "bed" element \*/*, **{**  

      **bedPadding:** 10, *// The padding around the area edge*  

      **stonesMargin:** 10, *// Margin between stones*  

      **margin:** 10, *// This overrides bedPadding & stonesMargin and is equivalent to setting them both to this value*  

      **minWidth:** 280, *// Minimum width you want an element to be*  

      **maxColumns:** 5, *// Maximum number of columns to display*  

      **flow:** false, *// Flows the stone widths on resize; but, harder to read flowing text during animation*  

      **direction:** 'left', *// Alternative is "right"*  

      **assignReverseZIndexes:** false, *// Auto DOM order z-indexing, or `true` for each stone to have a higher z-index than the next stone*  

      **random:** false, *// Display stones in a random order*  

      **square:** false, *// Makes each flagstone square*  

      **space:** false, *// Spaces out stones randomly*  

      **spaceFrequency:** 0.4, *// Adjusts the frequency of the amount of spaces (as a float 0.0 - 1.0)*  

      **animationDuration:** 0, *// Animation duration (milliseconds)*  

      **animationTimingFunction:** 'linear', *// CSS animation timing function as a string*  

      **heightAnimationDuration:** 0, *// Height animation duration (milliseconds)*  

      **heightAnimationTimingFunction:** 'linear', *// Height CSS animation timing function as a string*  

      **resizeDelay:** 250, *// Delay to run resize/reset function after resizing the window (milliseconds)*  

      **imagesLoadedQueryDuration:** 2500, *// Duration to check for images that have finished loading after instantiation (milliseconds).*  

      **imagesLoadedQueryFrequency:** 100, *// Frequency to check for images that have loaded within the imagesLoadedQueryDuration (milliseconds)*  

      **dragAndDrop:** false, *// Enable drag n' drop*  

      **dragAndDropAutoDelay:** 0, *// Enable automatic/previewing drag n' drop by setting a delay (milliseconds)*  

      **dropCallback:** function(dragElem, targetElem) { return true; }, *// Drag and drop callback to manipulate the drag and target elements as well as accept or reject the drop with a return boolean*  

      **eventResetDelay:** 0, *// Delay to call reset when an element with the "flagstone-reset" class is triggered (important when resizing CSS animations are used)*  

      **eventResizeHeightDuration:** 0, *// Animation duration when an element with the "flagstone-resize-height" class is triggered. (Important when resizing CSS animations are used and you don't want a reset to be called) (milliseconds). Increase time slightly if needed to compensate for event binding order.*  

      **callback:** function(elem, index) {}, *// Callback to run against every element every time a soft reset is called. WARNING: If attaching listeners, you'll need to remove the listeners first to avoid stacks of listeners!*  

      **watch:** true, *// Calls a hard reset when a stone is added or removed*  

      **watchAll:** false, *// Calls a hard reset when any element in the Flagstone bed is added or removed (not supported in <= IE10)*  

      **watchImages:** true // Calls a soft reset when images have loaded. Browser will catch a src being set for the first time or changing after the fact if `watchAll` is set to `true` as well.  

**});**



---



### METHODS:



#### ADJUST

Allows the developer to provide options to the user to change settings on the fly.  

**fs.adjust({**  

    **margin:** 10,  

    **bedPadding:** 10,  

    **stonesMargin:** 10,  

    **minWidth:** 280,  

    **maxColumns:** 5,  

    **dragAndDrop:** true,  

    **dropCallback:** function(elem, index) {},  

    **callback:** function(elem, index) {}  

**});**



#### DESTROY

Removes Window resize event listener, and removes the styles from the document head.  

**fs.destroy();**



#### HIDE

Hides the flagstone wrapper until re-calculation is complete; great before new content is injected into the DOM. IMPORTANT: Generally speaking, most use cases are handled automatically.  

**fs.hide();**



#### RESET (Soft)

Re-calculates sizes and spacing of existing stones. This is handled automatically on resize, and when an element with a class of `flagstone-reset` is selected.  

**fs.reset();** // Good for adjusting static content.



#### RESET (Hard)

Finds stones anew, adds any applicable listeners, and resets all positions. IMPORTANT: In most cases, this will never be needed as DOM changes are being listened for already and will call this method automatically.  

**fs.hardReset();**



#### RESIZE HEIGHT

Runs a watcher to move the elements directly under the provided element's ancestor stone element. See the `flagstone-resize-height` class for more details.  

**fs.resizeHeight(*element*);**



---



### CLASSES



#### flagstone-drag-handle

Elements with the `flagstone-drag-handle` class on them designate the only drag-activating area. This can also be added to the stone itself if you want the entire stone to be draggable from anywhere on it. NOTE: This is required for drag and drop. This requires the `dragAndDrop` property to be set to `true` to function.



#### flagstone-lock

Stones with the `flagstone-lock` class on them will prevent them from being dragged, or from other stones being dragged over them—even if the `dragAndDrop` property is set to `true`.



#### flagstone-remove

Elements with the `flagstone-remove` class on them will cause the stone it's contained within to be removed from the DOM when *clicked*; or, when the *enter* or *space* keys are pressed.



#### flagstone-reset

Elements with the `flagstone-reset` class on them will trigger a soft reset when *clicked*; or, when the *enter* or *space* keys are pressed.



#### flagstone-resize-height

Elements with the `flagstone-resize-height` class on them will cause "stones" below it to move with the developer-provided height changes of this targeted stone when *clicked*; or, when the *enter* or *space* keys are pressed.  



IMPORTANT: Size changes cannot be read accurately if and when Flagstone listeners attach *after* your developer resize function listeners. To fix this issue, set your methods in a timeless `setTimeout` callback, and set the Flagstone `eventResizeHeightDuration` property to the animation duration your CSS or JS animation will be running for.



---



### DRAG AND DROP



#### Handle

Add a `flagstone-drag-handle` class anywhere on or inside a stone to limit where the drag behavior is allowed.



#### Lock

Prevent one or more stones from dragging even when `dragAndDrop` is set to `true` by adding a `flagstone-lock` class to them.



#### Classes conditionally added to the *bed* wrapper:

* `flagstone-dragover` *Applied when a stone is dragged over the bed, and not a another stone*



#### Classes conditionally added to the *stone* elements:

* `flagstone-drag` *Applied when the drag starts*

* `flagstone-dragover` *Applied to the stone that's under the dragging mouse/touch*

* `flagstone-left` *Applied when the dragging mouse/touch is on the left side of a another stone; suggesting the future drop position*

* `flagstone-right` *Applied when the dragging mouse/touch is on the right side of a another stone; suggesting the future drop position*



#### Example styling for drag and drop:

**.a-class-on-your-flagstone-bed.flagstone-dragover {**  

    box-shadow: inset 0 0 4px 4px #ff0;  

**}**  

**.flagstone-drag {**  

    filter: grayscale(1) blur(4px);  

    opacity: 0.25;  

**}**  

**.flagstone-left {**  

    box-shadow: -8px 0 4px -4px #ff0;  

**}**  

**.flagstone-right {**  

    box-shadow: 8px 0 4px -4px #ff0;  

**}**



---



### ADDITIONAL ANIMATION

Because of CSS cascading:

* Any of your transition styles declared before the injected Flagstone styles appended to the head element will be replaced.

* If adding transition styles *after* the Flagstone styles, you must also *re-add* the Flagstone generated styles.



---



### BROWSER SUPPORT

Modern browsers (including IE10+) and mobile support.



---



The MIT License (MIT)  

Copyright (c) 2014-2018 Depth Development