Skip to content

API Documentation

Jump to bottom
Damian Wajdlich edited this page Jul 3, 2017 · 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: 'horizonatl' / 'vertical'
lanes number 5 Amount of grid cells dashboard is divided on.
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).
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.
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.
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.

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.

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

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.
  • 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
  • BREAKPOINTS - static property = ['sm', 'md', 'lg', 'xl']

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