Getting started

Contents

1. Installation
2. Dashboard with drag and resize
3. Adding widgets by drag from outside
4. Dynamic dashboard configuration change
5. Responsive behaviour

Installation

npm install angular2gridster

Once installed you need to import our module:

...
import { GridsterModule } from 'angular2gridster';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    ...
    GridsterModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

The example it imports in AppModule, but it could also be imported in any other module - depends where you want to use it.

Additional steps for System.js

To make Angular2gridster works with System.js you need to provide dedicated configuration in systemjs.config.js. It requires change in map object and 'packages' as follows:

System.config({
  map: {
    // ...
    'rxjs':             'node_modules/rxjs',
    'angular2gridster': 'node_modules/angular2gridster'
  },
  packages: {
    // ...
    'rxjs':             { defaultExtension: 'js' },
    'angular2gridster': { main: 'dist/index.js', defaultExtension: 'js' }
  }
});

Dashboard with drag and resize

It's enough to place following code in component you want to render dashboard:

<gridster [options]="gridsterOptions" [draggableOptions]="{ handlerClass: 'panel-heading' }">

  <gridster-item *ngFor="let widget of widgets" 
                 [(x)]="widget.x" [(y)]="widget.y" [(w)]="widget.w" [(h)]="widget.h">
      <!--some content-->
  </gridster-item>

</gridster>

Gridster configuration can be defined as follows (more info here):

widgets: Array<any> = [...];
gridsterOptions = {
  lanes: 5, // how many lines (grid cells) dashboard has
  direction: 'vertical', // items floating direction: vertical/horizontal
  dragAndDrop: true, // possible to change items position by drag n drop
  resizable: true // possible to resize items by drag n drop by item edge/corner
  useCSSTransforms: true, // improves rendering performance by using CSS transform in place of left/top
};

DraggableOptions is optional configuration. In this example it defines that dragging widgets should be only possible by element with given class. By default drag is possible by any place of GridsterItemComponent.

Adding widgets by drag from outside

Angular2gridster module provide possibility to add new item to dashboard by drag n drop. By this solution user can by one gesture add widget and chose on which position he wants to place it. This function similar to one available on Android system - dragging widget from Widget Bar to Dashboard. Enabling this solution is as simple as creating set of elements that will be used as widget prototype and assign GridsterItemPrototype directive:

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

Config attribute has helper option that if set on true, element it self will not be dragged but clone that will be created on drag start.

Directive itself will not add any widget to Dashboard, so you have to do it manually. To do so, you should register listener on drop event that provide an $event.item object that contains all needed data for creating new widget (coords, size, etc.):

addWidget(event: any) {
    this.widgets.push({
      x: event.item.x,
      y: event.item.y,
      w: event.item.w,
      h: event.item.h,
      ...
    });
}

Dynamic dashboard configuration change

Changing configuration of Gridster after it's initialized is possible by using API of Gridster component. First we need to access GridsterComponent in our component then use setOption method and on the end reload. Maybe it is seams to be complicated, but it isn't:

import { Component, ViewChild } from '@angular/core';
import { GridsterComponent } from 'angular2gridster';

@Component({
  ...
})
export class MyDashboardComponent {
  @ViewChild(GridsterComponent) gridster: GridsterComponent;
  ...
  addLine () {
    this.gridster.setOption('lanes', ++this.gridsterOptions.lanes)
      .reload();
  }
  removeLine () {
    this.gridster.setOption('lanes', --this.gridsterOptions.lanes)
      .reload();
  }
  changeDirection(direction: string) {
    this.gridster.setOption('direction', direction)
      .reload();
  }
  toggleDraggable() {
    this.gridster.setOption('dragAndDrop', gridsterOptions.dragAndDrop)
      .reload();
  }
  toggleResizable() {
    this.gridster.setOption('resizable', gridsterOptions.dragAndDrop)
      .reload();
  }
}

You can update configuration directly in template as well:

  ...
  <input type="checkbox" [(ngModel)]="gridsterOptions.dragAndDrop" value="true"
         (change)="gridster.setOption('dragAndDrop', gridsterOptions.dragAndDrop).reload()"> Draggable

  <input type="checkbox" [(ngModel)]="gridsterOptions.resizable" value="true"
         (change)="gridster.setOption('resizable', gridsterOptions.resizable).reload()"> Resizable

  <input type="radio" [(ngModel)]="gridsterOptions.direction" value="horizontal"
           (change)="gridster.setOption('direction', 'horizontal').reload()"> Horizontal

  <input type="radio" [(ngModel)]="gridsterOptions.direction" value="vertical"
           (change)="gridster.setOption('direction', 'vertical').reload()"> Vertical

  ...

More info about GridsterComponent API in API documentation.

Responsive behaviour

First of all to make your Gridster adopt item sizes to window on resize event you just need to set responsiveView: true. It means that you don't need anymore onResize(event) { this.gridster.reload() }. Additional it's suggested to set debounce time on window resize by option: responsiveDebounce.

Dashboard should look good in all devices - smartphones, tablets laptops and big resolution screens. Angular2gridster takes care about this topic by providing you easly configurable responsiveOptions. responsiveOptions is a new property that is flat list of options that will extend "default" configuration when specific breakpoint will match. Angular2gridster uses Mobile first design, so "default" configuration is dedicated for the smallest view and every object in responsiveOptions is an extension for breakpoint defined by minWidth; The amount of breakpoints to configure is limited. You can use following: 'sm', 'md', 'lg', 'xl'.

And how to use this - the example will explain best:

    gridsterOptions = {
        // core configuration is default one - for smallest view. It has hidden minWidth: 0.
        lanes: 2, // amount of lanes (cells) in the grid
        direction: 'horizontal', // floating top - vertical, left - horizontal
        resizable: false, // enable/disable resizing by drag and drop for all items in grid

        // Responsive options:
        responsiveView: true, // turn on adopting items sizes on window resize and enable responsiveOptions
        responsiveDebounce: 500, // window resize debounce time
        // List of different gridster configurations for different breakpoints.
        // Each breakpoint is defined by name stored in "breakpoint" property. There is fixed set of breakpoints
        // available to use with default minWidth assign to each.
        // - sm: 576 - Small devices
        // - md: 768 - Medium devices
        // - lg: 992 - Large devices
        // - xl: 1200 - Extra large
        // MinWidth for each breakpoint can be overwritten like it's visible below.
        // ResponsiveOptions can overwrite default configuration with any option available.
        responsiveOptions: [
            {
                breakpoint: 'sm',
                direction: 'vertical',
                lanes: 3
            },
            {
                breakpoint: 'md',
                minWidth: 768,
                direction: 'vertical',
                lanes: 4,
                resizable: true
            },
            {
                breakpoint: 'lg',
                minWidth: 1250,
                direction: 'vertical',
                lanes: 6,
                resizable: true
            },
            {
                breakpoint: 'xl',
                minWidth: 1800,
                direction: 'vertical',
                lanes: 8,
                resizable: true
            }
        ]
    }