(Generically known as a JavaScript grid, or JavaScript tiling/tiles.)
- 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;}.
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.
});
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) {}
});
Removes Window resize event listener, and removes the styles from the document head.
fs.destroy();
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();
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.
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();
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);
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.
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.
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.
Elements with the flagstone-reset class on them will trigger a soft reset when clicked; or, when the enter or space keys are pressed.
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.
Add a flagstone-drag-handle class anywhere on or inside a stone to limit where the drag behavior is allowed.
Prevent one or more stones from dragging even when dragAndDrop is set to true by adding a flagstone-lock class to them.
flagstone-dragoverApplied when a stone is dragged over the bed, and not a another stone
flagstone-dragApplied when the drag startsflagstone-dragoverApplied to the stone that's under the dragging mouse/touchflagstone-leftApplied when the dragging mouse/touch is on the left side of a another stone; suggesting the future drop positionflagstone-rightApplied when the dragging mouse/touch is on the right side of a another stone; suggesting the future drop position
.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;
}
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.
Modern browsers (including IE10+) and mobile support.
The MIT License (MIT)
Copyright (c) 2014-2018 Depth Development