Skip to content

API Documentation

Jump to bottom
Damian Wajdlich edited this page Dec 10, 2019 · 41 revisions

Contents

  1. GridsterComponent
  2. GridsterItemComponent
  3. GridsterItemPrototypeDirective
  4. GridListItem

GridsterComponent

Inputs

  • options - object literal with Gridster options. Object accepts following options:
Option type Default Description
direction string 'horizontal' Indicates gridster items floating direction. Possible options: 'horizonatal' / 'vertical' / 'none'. When direction 'none' will be set, items will not be floated in any direction and other items will not adjust its position while dragging one.
floating boolean true (gravity) If it's true, gridster will move item to very top or left (according to direction) to reduce space between items. If set to false gridster will allow to place an item in any position.
lanes number 5 Amount of grid cells dashboard is divided on.
lines Object { visible: false, always: false, color: '#d8d8d8', width: 1, backgroundColor: 'pink'} Indicate the width (in px), color and visibility of one lines.
widthHeightRatio number 1 What is the cell ration between width and height (e.g. if ratio will be 0.5 and widget will have size w=1, h=1 with item width=100px then height=50px).
cellWidth number Indicate the width (in px) of one lane item. Alternative to "widthHeightRatio" option. Valid for direction="horizontal".
cellHeight number Indicate the height (in px) of one lane item. Alternative to "widthHeightRatio" option. Valid for direction="vertical".
dragAndDrop boolean true Indicate whether user can reposition gridster items on board by drag n drop.
resizable boolean false Indicate whether user can resize items by drag n drop by edge or corner.
resizeHandles Object { s: true, e: true, n: true, w: true, se: true, ne: true, sw: true, nw: true } Defines in which direction resize is allowed.
shrink boolean false If true, Gridster element size fits all items and does not add additional space for dragging new elements. The size is increased only when item is dragged.
responsiveView boolean false If true, Gridster items will automatically adopt its sizes on window resize to fit available space.
responsiveDebounce number 0 Debounce time (ms) applied on window resize when responsiveView is set to true. Because of performance it is suggested to set it.
useCSSTransforms boolean false Uses CSS3 translate() instead of position top/left. This makes about 6x faster render performance.
tolerance string "pointer" Specifies which mode to use for checking whether a prototype item is hovering over a gridster. Possible values: "pointer" - mouse pointer overlaps the gridster, "fit" - prototype item overlaps the gridster entirely, "intersect" - prototype item overlaps the gridster at least 50% in both directions, "touch" - prototype item overlaps the droppable any amount.
responsiveSizes boolean false If set to false, item size are the same for all breakpoints. When set to true, item size can be different for different breakpoints. In this case size will be binded to following attributes: w, h, wSm, hSm, wMd, hMd, wLg, hLg, wXl, hXl
responsiveToParent boolean false By default responsiveness uses window width. If this option is set to true then it uses Gridster element width to match the Gridster breakpoint.
responsiveOptions Array List of options that will extend default options when browser window will match specific breakpoint. In responsive options are two additional options: breakpoint - name of breakpoint to configure ('sm', 'md', 'lg', 'xl), minWidth - (optional) the pixel window min width to match breakpoint. More info here.
  • draggableOptions - object literal with Gridster draggable options. Object accepts following options:
Option type Default Description
handlerClass string Class name as a selector for drag handler in gridster item.
scroll boolean true If set to true, container auto-scrolls while dragging.
scrollEdge number 36 Distance in pixels from the edge of the viewport after which the viewport should scroll. Distance is relative to pointer, not the dragged item. Ignored if the scroll option is false.

Outputs

  • optionsChange - event fired on match a breakpoint defined by responsiveOptions. $event is an object literal that delivers all options used to render gridster for current breakpoint.
  • reflow - event fired each time when Gridster recalculates and renders items. $event is an object literal with two properties:
    • isInit - indicates if it is initial gridster rendering
    • gridsterComponent - GridsterComponent instance that fires event

Component API

GridsterComponent can directly be access by @ViewChild decorator and used for dynamically changing options. It provides following methods:

  • setOption - expects two params to be given: optionName and value. Should be used when we want to dynamically change Gridster option. The method can be chained when we need to set many options at once. To apply changed options we should call reload method. Example:
    this.gridster
      .setOption('lanes', 6)
      .setOption('direction', 'horizontal')
      .reload();
  • reload - method responsible for recalculating all items positions and sizes and applying them on dashboard. It should be called after each Gridster configuration change in run time.

HTML Example

Here is an example how template with all these attribute would look:

<gridster [options]="gridsterOptions" [draggableOptions]="gridsterDraggableOptions"
          (gridsterPositionChange)="positionsChanged($event)" (resize)="itemResize($event)">
  ...
</gridster>

GridsterItemComponent

Inputs

  • x - horizontal item position (counted in cell amount)
  • y - vertical item position (counted in cell amount)
  • w - item width (counted in cell amount). This also work with two way binding.
  • h - item height (counted in cell amount). This also work with two way binding.
  • options - object literal defining item options. Possible properties:
    • minWidth - (default=1) minimal item width (in lanes) - it restricts resizing by drag n drop.
    • minHeight - (default=1) minimal item height (in lanes) - it restricts resizing by drag n drop.
    • maxWidth - (default=Infinity) maximal item width (in lanes) - it restricts resizing by drag n drop.
    • maxHeight - (default=Infinity) maximal item height (in lanes) - it restricts resizing by drag n drop.
    • defaultWidth - (default=1) default item width (in lanes) when new item is pushed to gridster items list without width assign.
    • defaultHeight - (default=1) default item height (in lanes) when new item is pushed to gridster items list without height assign.
  • dragAndDrop - if false, prevents item to be movable - by dragging or by pulling items by dragging other item.
  • resizable - if false, prevents item to be resizable by drag n drop.

Outputs

  • xChange - fired on x position changed. $event is x position after change.
  • yChange - fired on y position changed. $event is y position after change.
  • xSmChange - fired on x position changed in sm breakpoint. $event is x position after change.
  • ySmChange - fired on y position changed in sm breakpoint. $event is y position after change.
  • xMdChange - fired on x position changed in md breakpoint. $event is x position after change.
  • yMdChange - fired on y position changed in md breakpoint. $event is y position after change.
  • xLgChange - fired on x position changed in lg breakpoint. $event is x position after change.
  • yLgChange - fired on y position changed in lg breakpoint. $event is y position after change.
  • xXlChange - fired on x position changed in xl breakpoint. $event is x position after change.
  • yXlChange - fired on y position changed in xl breakpoint. $event is y position after change.
  • wChange - fired on width changed. $event is w position after change.
  • hChange - fired on height changed. $event is h position after change.
  • change - fired on each item change (reposition or resize). $event is an object with following properties:
    • item: GridListItem - item that has changed
    • isNew: true if item is newlly added
    • oldValues: Object with old values of props that has changed. Possible props: 'x', 'y', 'w', 'h'
    • changes: Array - list of properties that has changed: 'x', 'y', 'w', 'h'
    • breakpoint: string|null - name of breakpoint in which event was fired. If smallest view or when no responsive options is defined it passes null.
  • start - fired on start dragging/resizing event in gridster item. $event is an object with following properties:
    • item: GridListItem - item that has changed
    • action: string - resize when resize event, drag when drag event
  • end - fired on stop dragging/resizing event in gridster item. $event is an object with following properties:
    • item: GridListItem - item that has changed
    • action: string - resize when resize event, drag when drag event

HTML Example

<gridster-item *ngFor="let item of items" (change)="itemChanged($event)"
               [(x)]="widget.z" // or: [x]="widget.x" (xChange)="reposition(item, $event)"
               [(y)]="widget.y"
               [(w)]="widget.w" [(h)]="widget.h"
               [(xSm)]="widget.xSm" [(ySm)]="widget.ySm"
               [(xMd)]="widget.xMd" [(yMd)]="widget.yMd"
               [(xLg)]="widget.xLg" [(yLg)]="widget.yLg"
               [(xXl)]="widget.xXl" [(yXl)]="widget.yXl"
>
</gridster-item>

GridsterItemPrototypeDirective

Inputs

  • w - (optional) item width (counted in cell amount). If not given Gridster will try to find most suitable place automatically.
  • h - (optional) item height (counted in cell amount). If not given Gridster will try to find most suitable place automatically.
  • w, h, wSm, hSm, wMd, hMd, wLg, hLg, wXl, hXl - item width/height for different breakpoints, if gridster uses responsiveSizes: true. If any size is not set, gridster uses w and h as a fallback.
  • config - object literal with GridsterItemPrototype configuration. Object accepts following options:
Option type Default Description
helper boolean false If set on true, element it self will not be dragged but clone that will be created on drag start.

Outputs

  • drop - fires when user drops element over Gridster dashboard. This is an event on which you should push new item on items list. $event object provides following properties:
  • start - fires when user starts dragging element. $event object provides following properties:
  • cancel - fires when user drops element outside of Gridster dashboard. $event object provides following properties:
  • enter - fires when user by dragging enters Gridster area. $event object provides following properties:
  • out - fires when user by dragging leaves Gridster area. $event object provides following properties:

HTML Example

Here is an example how template with all these attribute would look:

    <div gridsterItemPrototype [config]="{helper: true}" [w]="1" [h]="1"
         (drop)="addWidget($event)" (enter)="over($event)" (out)="out($event)"></div>

GridListItem

GridListItem is an adapter method for different kind of objects (GridsterItemComponent, GridsterItemPrototypeComponent, Object) and it provides core information about item.

Object API

Properties:

  • itemComponent - (nullable) reference to original GridsterItemComponent that item was build from.
  • itemPrototype - (nullable) reference to original GridsterItemPrototypeDirective that item was build from.
  • itemObject - (nullable) reference to original object literal that item was build from.
  • $element - DOMElement representation
  • x - (nullable) item horizontal position (cells amount)
  • y - (nullable) item vertical position (cells amount)
  • w - item width (cells amount)
  • h - item height (cells amount)
  • dragAndDrop - (getter) informs if item is draggable
  • resizable - (getter) informs if item is resizable

Methods:

  • copy(): GridListItem - method that creates new instance of GridListItem with the same data.
  • copyForBreakpoint(breakpoint?): GridListItem - method that creates new instance of GridListItem with the same data taken from config for given breakpoint.
  • getValueX(breakpoint?): number
  • setValueX(breakpoint?)
  • getValueY(breakpoint?): number
  • setValueY(breakpoint?)
  • hasPositions(breakpoint?): boolean
  • applyPosition(gridster?: GridsterService) - apply coords (px) to item in DOM for given Gridster
  • calculatePosition(gridster?: GridsterService): {left: number, top: number} - calculate item DOM coords (px) for given Gridster
  • applySize(gridster?: GridsterService) - apply width and height (px) to item in DOM for given Gridster
  • calculateSize(gridster?: GridsterService): {width: number, height: number} - calculate item DOM width and height (px) for given Gridster
Clone this wiki locally