repository·master·Indexed 23 days ago
https://github.com/tiberiuzuld/angular-gridster2An Angular implementation of the angular-gridster library that provides a dashboard-style grid system for arranging and resizing widgets. It features configurable layout types (Fit, fixed, scrollVertical, etc.), draggable and resizable items, and a comprehensive GridsterConfig for managing constraints, responsiveness, and lifecycle callbacks. The library includes a GridsterApi for programmatic control and supports custom drag handles and item validation.
To interact with the grid programmatically (e.g., for resizing or layout calculations), you must first obtain the GridsterApi instance. You can do this in two ways:
viewChild(Gridster).api in your component.options.initCallback(gridster, gridsterApi) function after the grid has finished initializing.Install the package using npm to add it to your project dependencies.
npm install angular-gridster2 --saveNgComponentOutlet directive. This allows you to pass a component class directly to the directive to instantiate it dynamically within the grid item.A simple way to handle dynamic widget content is to create a wrapper component (e.g., parentDynamicComponent) that is placed inside every widget. Inside this wrapper, use *ngIf to conditionally initialize and render the specific widget component based on a type property.
To allow the dynamic content to communicate with the grid (such as reporting resize or drag events), use EventEmitters within the wrapper component to bubble these events up to the grid controller.
By default, clicking or interacting with content inside a gridster-item might trigger a drag event. To allow users to interact with content (like buttons or text selection) without moving the widget, use one of these two patterns:
Stop the event propagation on mousedown and touchstart for the content container. This is useful for clickable elements that don't require text selection.
Wrap your content in a container with a specific class (e.g., .gridster-item-content) to allow standard text selection behavior while still allowing interaction.
<!-- Option 1: Without text selection -->
<gridster-item>
<div (mousedown)="$event.stopPropagation()" (touchstart)="$event.stopPropagation()">Some content to click without dragging the widget</div
<div class="item-buttons">
<button class="drag-handler">
<md-icon>open_with</md-icon>
</button>
<button class="remove-button" (click)="removeItem($event, item)" (touchstart)="removeItem($event, item)">
<md-icon>clear</md-icon>
</button>
</div
</gridster-item>
<!-- Option 2: With text selection -->
<gridster-item>
<div class="gridster-item-content">Some content to select and click without dragging the widget</div
<div class="item-buttons">
<button class="drag-handler">
<md-icon>open_with</md-icon>
</button>
<button class="remove-button" (click)="removeItem($event, item)" (touchstart)="removeItem($event, item)">
<md-icon>clear</md-icon>
</button>
</div
</gridster-item>To implement a gridster dashboard, import Gridster and GridsterItem into your standalone component. Use the <gridster> component with an [options] input and iterate over a collection of items using <gridster-item> with an [item] input.
Important Note: The gridster component expands to fill all available space from its parent. It does not resize based on its content. Ensure the parent container has a defined size.
<gridster [options="options">
@for (item of dashboard; track item) {
<gridster-item [item="item">
<!-- your content here -->
</gridster-item>
}
</gridster>The resizable configuration object allows you to control how items within the grid can be resized. You can enable/disable resizing, define which edges/handles are available, set a delay for touch interactions, and hook into the start and stop events of a resize operation.
Key features:
resizable.enabled: Toggles the ability to resize items.resizable.handles: Defines which sides or corners of an item can be used to trigger a resize (e.g., s for south, ne for north-east).resizable.stop: A callback function triggered when resizing ends. If this function returns a Promise, the resize can be cancelled or approved based on the promise resolution.resizable.delayStart: Useful for touch devices to prevent accidental resizing while scrolling.| Option | Description | Type | Default |
| -------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| resizable.delayStart | milliseconds to delay the start of resize, useful for touch interaction | Number | 0 |
| resizable.enabled | enable/disable resizable items | Boolean | false |
| resizable.stop | callback when resizing an item stops. Accepts Promise return to cancel/approve resize | Function(item, gridsterItem, event) | undefined |
| resizable.start | callback when resizing an item starts | Function(item, gridsterItem, event) | undefined |
| resizable.handles | resizable edges of an item | Object | {s: true, e: true, n: true, w: true, se: true, ne:true, sw: true, nw: true} |The angular-gridster2 configuration supports two options for managing how items interact when moved or dropped onto one another:
swap: When set to true (default), items will switch positions if one is dropped on top of another.swapWhileDragging: When set to true, items will swap positions dynamically while the item is being dragged, and the new position will be saved.| Option | Description | Type | Default |
| --- | --- | --- | --- |
| swap | allow items to switch position if drop on top of another | Boolean | true |
| swapWhileDragging | swap items while dragging and save new position | Boolean | false |To enable items to be displayed in multiple layers (allowing them to overlap or exist at different depths), use the multi-layer configuration options. By default, multi-layering is disabled (allowMultiLayer: false).
When enabled, you can control the depth of items using the following properties:
allowMultiLayer: Enables or disables the ability for items to show in layers.defaultLayerIndex: Sets the starting layer index for an item.maxLayerIndex: Defines the maximum allowable layer index.baseLayerIndex: Sets the base index used to calculate the final z-index. The final z-index of an item is calculated as baseLayerIndex + layerIndex.| Option | Description | Type | Default |
| --- | --- | --- | --- |
| allowMultiLayer | allow items show in layers | Boolean | false |
| defaultLayerIndex | default layer index of an item in gridster | Number | 1 |
| maxLayerIndex | max layer index of an item in gridster | Number | 2 |
| baseLayerIndex | base layer index of an item in gridster, final z-index should be `baseLayerIndex + layerIndex` | Number | 1 |The dirType option controls how items behave when dropped on top of each other in a Right-to-Left (RTL) context. It determines if items are allowed to switch positions when one is dropped on top of another.
Available values are of type DirTypes:
DirTypes.LTR: Left-to-Right (default)DirTypes.RTL: Right-to-Left| Option | Description | Type | Default |
| ------- | -------------------------------------------------------- | -------- | ------------ |
| dirType | allow items to switch position if drop on top of another | DirTypes | DirTypes.LTR |The draggable configuration object allows you to control how items are moved within the grid. You can enable/disable dragging, set delays for touch interactions, define specific drag handles, and intercept the start or stop of a drag operation using callbacks.
Key features include:
ignoreContent and dragHandleClass to restrict dragging to specific elements (e.g., a header bar) rather than the entire item.start and stop to trigger logic when an item begins or ends movement. The stop callback can return a Promise to programmatically cancel or approve the drag operation.dropOverItems to allow items to be dropped onto others (provided swap and push are disabled).| Option | Description | Type | Default |
| ------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------- | ----------------------- |
| draggable.delayStart | milliseconds to delay the start of drag, useful for touch interaction | Number | 0 |
| draggable.enabled | enable/disable draggable items | Boolean | false |
| draggable.ignoreContent | if true drag will start only from elements from `dragHandleClass` | Boolean | false |
| draggable.dragHandleClass | drag event only from this class. If `ignoreContent` is true. | String | 'drag-handler' |
| draggable.ignoreContentClass | default content class to ignore the drag event from | String | 'gridster-item-content' |
| draggable.stop | callback when dragging an item stops. Accepts Promise return to cancel/approve drag | Function(item, gridsterItem, event) | undefined |
| draggable.start | callback when dragging an item starts | Function(item, gridsterItem, event) | undefined |
| draggable.dropOverItems | enable items drop over another, will work if swap and push is disabled | Boolean | false |
| draggable.dropOverItemsCallback | callback when dragging an item drops over another item | Function(sourceItem, targetItem, grid) | undefined |displayGrid option controls the visibility of the background grid (rows and columns) within the Angular Gridster component. You can choose to show the grid always, only during interaction, or not at all.