@yuuvis/widget-grid

Library for creating custom dashboards. Applications can use the provided WidgetGridRegistry to register widgets that then could be configured and placed by the user.

Usage

Import YuvWidgetGridModule into your app module:

import { YuvWidgetGridModule } from "@yuuvis/widget-grid";

@NgModule({
  imports: [YuvWidgetGridModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

Add widget grid component to your template:

<!-- app.component.html -->
<yuv-widget-grid
  [gridItemConfig]="gridItemConfig"
  [editMode]="editMode"
  (gridItemEvent)="onGridEvent($event)"
  (gridChange)="onGridChange($event)"
></yuv-widget-grid>

| Input | Type | Description | | -------------- | ------------------------ | --------------------------------------------------------------------------------------------------- | | gridItemConfig | WidgetGridItemConfig[] | Array of widget grid items that will be rendered as tiles in the grid. | | editMode | boolean | Enables/disables widget grids edit mode where you can move widgets around, resize or configure them |

| Output | emits | Description | | ------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | gridChange | WidgetGridItemConfig[] | Emitted every time the configuration of the widget grid changes. If you for example enter edit mode and restructure your grid, those changes will be emitted here. You may then persist this config somewhere. | | gridItemEvent | GridItemEvent | Events emitted by the grids widgets. In order to communicate with your app, widgets can use those events. Fire them in the widget catch them here. |

Workspaces

Beside a 'standalone' grid you could also use yuv-widget-grid-workspaces. This component handles multiple widget grids in so called workspaces.

<yuv-widget-grid-workspaces
  [workspaceConfig]="workspaceConfig"
  (gridItemEvent)="onGridEvent($event)"
  (configChange)="onWorkspacesConfigChange($event)"
></yuv-widget-grid-workspaces>

| Input | Type | Description | | --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | workspaceConfig | WidgetGridWorkspaceConfig | Configuration describing the current workspaces setup. | | options | WidgetGridWorkspaceOptions | Options for setting up the workspaces component. May contain translations or custom labels as well as configurations for a workspace's widget grid. |

| Output | emits | Description | | ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | configChange | WidgetGridWorkspaceConfig | Emitted every time the workspace configuration changes. | | gridItemEvent | GridItemEvent | Events emitted by the grids widgets. In order to communicate with your app, widgets can use those events. Fire them in the widget catch them here. |

Interfaces

export interface WidgetGridWorkspaceConfig {
  currentWorkspace?: string;
  workspaces: Array<WidgetGridWorkspace>;
}

export interface WidgetGridWorkspace {
  id: string;
  label: string;
  grid: WidgetGridItemConfig[];
}

export interface WidgetGridWorkspaceOptions {
  gridConfig?: Partial<WidgetGridConfig>;
}

export interface WidgetGridConfig {
  rows?: number;
  columns?: number;
  gap?: number;
}

export interface WidgetGridItemConfig extends GridsterItem {
  id: string;
  widgetName: string;
  widgetConfig: any;
}

export interface GridItemEvent {
  action: string;
  data: any;
}

Batteries (almost) not included

The widget grid is designed to be filled with custom widgets that fit your personal needs. But there are two widgets that are coming with the library. One is a simple To-Do list and the other one is a Picture widget. When playing around with this library you may want to try them out and continue from there.

// register the two "baked in" widgets 
this.widgetGridRegistry.registerGridWidgets([
  {
    name: "yuv.widget.picture",
    label: "Just a picture",
    setupComponent: PictureWidgetSetupComponent,
    widgetComponent: PictureWidgetComponent,
  },
  {
    name: "yuv.widget.todo",
    label: "Todo list",
    setupComponent: TodoWidgetSetupComponent,
    widgetComponent: TodoWidgetComponent,
  },
]);

Register widgets

Widgets are components that implement the IWidgetComponent interface. They then have to be registered using the WidgetGridRegistry:

// app.component.ts
ngOnInit(): void {
    this.widgetGridRegistry.registerGridWidget({
      label: 'Widget One',
      name: 'app.custom.widget.one',
      widgetComponent: WidgetOneComponent,
    });
    // widget with setup component
    this.widgetGridRegistry.registerGridWidget({
      label: 'Widget Two (with setup)',
      name: 'app.custom.widget.two',
      widgetComponent: WidgetTwoComponent,
      setupComponent: WidgetTwoSetupComponent,
    });
}

As you see in the example, widgets could also have a setup component. If your widget needs some kind of configuration, you can provide the component to set this up.

i18n

Labels used by the widget grid library can be replaced by custom ones. This could be used for internationalization. Once the user changes the language in your app you can use the widgetGridRegistry service to setup new labels:

this.widgetGridRegistry.updateWidgetGridLabels({
  workspacesEmptyMessage: "Bisher gibt es keine Arbeitsbereiche",
  newWorkspaceDefaultLabel: "Neuer Arbeitsbereich",
  workspaceRemoveConfirmMessage:
    'Soll der Arbeitsbereich "{{name}}" wirklich gelöscht werden?',
  workspaceEditDone: "Fertig",
});

You could also use this function to manage the labels of your custom widgets. Just call updateWidgetGridLabels({...}) with your key/value pairs and you are done. Inside your widgets subscribe to the labels$ observable from the WidgetGridRegistry service and use the values emitted there.

those are the default labels:

// yuv-widget-grid
{
  // headline of the widget picker
  widgetPickerTitle: 'Widgets',
  // label for the noop component (the component rendered when the widget configured is not registered)
  noopWidgetLabel: 'Not found',
  save: 'Save',
  cancel: 'Cancel',
}

// yuv-widget-grid-workspaces also adds the following keys and labels
{
  // shown when no workspace has been created so far
  workspacesEmptyMessage: 'No workspace so far.',
  // label of a newly created workspace
  newWorkspaceDefaultLabel: 'New Workspace',
  // confirm message when a user tries to delete a workspace
  workspaceRemoveConfirmMessage: 'Are you sure you want to remove "{{name}}"?',
  // label of the button that ends editing a workspace
  workspaceEditDone: 'Apply',
  confirm: 'OK',
}

You might also want to change the labels of your registered widgets once the user changes the apps language. This could be done by calling updateRegisteredWidgetsLabels()on the WidgetGridRegistry service:

this.widgetGridRegistry.updateRegisteredWidgetsLabels({
  "app.custom.widget.one": "Widget Nr.1",
  "app.custom.widget.two": "Widget Nr.2 (mit Setup)",
});