@yuuvis/widget-grid v1.0.4

@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>

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>

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)",
});