Crud

Description #

<vaadin-crud> is a Web Component for CRUD operations.

Quick Start #

Assign an array to the items property.

A grid and an editor will be automatically generated and configured based on the data structure provided.

<vaadin-crud></vaadin-crud>

const crud = document.querySelector('vaadin-crud');

crud.items = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];

Data Provider Function #

Otherwise, you can provide a dataProvider function.

const crud = document.querySelector('vaadin-crud');

const users = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];

crud.dataProvider = (params, callback) => {
  const chunk = users.slice(params.page * params.pageSize, params.page * params.pageSize + params.pageSize);
  callback(chunk, people.length);
};

NOTE: The auto-generated editor only supports string types. If you need to handle special cases customizing the editor is discussed below.

Customization #

Alternatively you can fully configure the component by using slot names.

Slot name	Description
grid	To replace the auto-generated grid with a custom one.
form	To replace the auto-generated form.
save-button	To replace the "Save" button.
cancel-button	To replace the "Cancel" button.
delete-button	To replace the "Delete" button.
toolbar	To provide the toolbar content (by default, it's empty).
new-button	To replace the "New item" button.

Example: #

<vaadin-crud id="crud">
  <vaadin-grid slot="grid">
    <vaadin-crud-edit-column></vaadin-crud-edit-column>
    <vaadin-grid-column id="column1"></vaadin-grid-column>
    <vaadin-grid-column id="column2"></vaadin-grid-column>
  </vaadin-grid>

  <vaadin-form-layout slot="form">
    <vaadin-text-field label="First" path="name"></vaadin-text-field>
    <vaadin-text-field label="Surname" path="surname"></vaadin-text-field>
  </vaadin-form-layout>

  <div slot="toolbar">Total singers: 2</div>
  <button slot="new-button">New singer</button>

  <button slot="save-button">Save changes</button>
  <button slot="cancel-button">Discard changes</button>
  <button slot="delete-button">Delete singer</button>
</vaadin-crud>

const crud = document.querySelector('#crud');

const column1 = document.querySelector('#column1');
column1.headerRenderer = (root, column) => {
  root.textContent = 'Name';
};
column1.renderer = (root, column, model) => {
  root.textContent = model.item.name;
};

const column2 = document.querySelector('#column2');
column2.headerRenderer = (root, column) => {
  root.textContent = 'Surname';
};
column2.renderer = (root, column, model) => {
  root.textContent = model.item.surname;
};

crud.items = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];

Helpers #

The following elements are used to auto-configure the grid and the editor

• <vaadin-crud-edit-column>
• <vaadin-crud-grid> - can be replaced with custom <vaadin-grid>
• <vaadin-crud-form> - can be replaced with custom <vaadin-form-layout>

Styling #

The following shadow DOM parts are available for styling when the editor is rendered next to, or below, the grid:

Part name	Description
toolbar	Toolbar container at the bottom of the grid. By default, it contains the new button
editor	The editor container
scroller	The wrapper for the header and the form
header	The header of the editor
footer	The footer of the editor

The following shadow DOM parts are available for styling when the editor renders as a dialog:

Part name	Description
toolbar	Toolbar container at the bottom of the grid. By default, it contains the new button
overlay	The dialog overlay
backdrop	The dialog backdrop
header	The header of the dialog
footer	The footer of the dialog
content	The wrapper for the form

The following custom properties are available:

Custom Property | Description | Default ----------------|---------------- --vaadin-crud-editor-max-height | max height of editor when opened on the bottom | 40% --vaadin-crud-editor-max-width | max width of editor when opened on the side | 40%

See Styling Components documentation.

Properties #

dataProvider #

Type: CrudDataProvider<any> | null | undefined

Function that provides items lazily. Receives arguments params, callback

params.page Requested page index params.pageSize Current page size params.filters Currently applied filters params.sortOrders Currently applied sorting orders

callback(items, size) Callback function with arguments:

• items Current page of items
• size Total number of items

See also: CrudDataProvider

editedItem #

Type: any

The item being edited in the dialog.

editOnClick #

Type: boolean

Enables user to click on row to edit it. Note: When enabled, auto-generated grid won't show the edit column.

editorOpened #

Type: boolean | null | undefined

Reflects the opened status of the editor.

editorPosition #

Type: CrudEditorPosition

Sets how editor will be presented on desktop screen.

Accepted values are:

• `` (default) - form will open as overlay
• bottom - form will open below the grid
• aside - form will open on the grid side (right, if lft and left if rtl)

See also: CrudEditorPosition

exclude #

Type: string | null | undefined

A comma-separated list of fields to be excluded from the generated grid and the generated editor.

When include is defined, this parameter is ignored.

Default is to exclude all private fields (those properties starting with underscore)

i18n #

Type: CrudI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following JSON structure and default values:

{
  newItem: 'New item',
  editItem: 'Edit item',
  saveItem: 'Save',
  cancel: 'Cancel',
  deleteItem: 'Delete...',
  editLabel: 'Edit',
  confirm: {
    delete: {
      title: 'Confirm delete',
      content: 'Are you sure you want to delete the selected item? This action cannot be undone.',
      button: {
        confirm: 'Delete',
        dismiss: 'Cancel'
      }
    },
    cancel: {
      title: 'Unsaved changes',
      content: 'There are unsaved modifications to the item.',
      button: {
        confirm: 'Discard',
        dismiss: 'Continue editing'
      }
    }
  }
}

See also: CrudI18n

include #

Type: string | null | undefined

A comma-separated list of fields to include in the generated grid and the generated editor.

It can be used to explicitly define the field order.

When it is defined exclude is ignored.

Default is undefined meaning that all properties in the object should be mapped to fields.

items #

Type: any[] | null | undefined

An array containing the items which will be stamped to the column template instances.

noFilter #

Type: boolean | null | undefined

Disable filtering when grid is autoconfigured.

noHead #

Type: boolean | null | undefined

Remove grid headers when it is autoconfigured.

noSort #

Type: boolean | null | undefined

Disable sorting when grid is autoconfigured.

noToolbar #

Type: boolean

Controls visibility state of toolbar. When set to false toolbar is hidden and shown when set to true.

size #

Type: number | null | undefined

Number of items in the data set which is reported by the grid. Typically it reflects the number of filtered items displayed in the grid.

Note: As with <vaadin-grid>, this property updates automatically only if items is used for data.

Events #

cancel #

Type: CrudCancelEvent

Fired when user discards edition. If the default is prevented, then no action is performed, user is responsible to close dialog and reset item and grid.

delete #

Type: CrudDeleteEvent

Fired when user wants to delete item. If the default is prevented, then no action is performed, items array is not modified nor dialog closed

edit #

Type: CrudEditEvent

Fired when user wants to edit an existing item. If the default is prevented, then a new item is not assigned to the form, giving that responsibility to the app, though dialog is always opened.

edited-item-changed #

Type: CrudEditedItemChangedEvent

Fired when the editedItem property changes.

editor-opened-changed #

Type: CrudEditorOpenedChangedEvent

Fired when the editorOpened property changes.

items-changed #

Type: CrudItemsChangedEvent

Fired when the items property changes.

new #

Type: CrudNewEvent

Fired when user wants to create a new item.

save #

Type: CrudSaveEvent

Fired when user wants to save a new or an existing item. If the default is prevented, then no action is performed, items array is not modified nor dialog closed

size-changed #

Type: CrudSizeChangedEvent

Fired when the size property changes.

Types #

CrudCancelEvent #

/**
 * Fired when user discards edition.
 */
export type CrudCancelEvent<T> = CustomEvent<{ item: T }>;

CrudDataProvider #

export type CrudDataProvider<T> = (params: CrudDataProviderParams, callback: CrudDataProviderCallback<T>) => void;

CrudDataProviderCallback #

export type CrudDataProviderCallback<T> = (items: T[], size?: number) => void;

CrudDataProviderParams #

export type CrudDataProviderParams = {
  page: number;
  pageSize: number;
  filters: GridFilterDefinition[];
  sortOrders: GridSorterDefinition[];
};

CrudDeleteEvent #

/**
 * Fired when user wants to delete item.
 */
export type CrudDeleteEvent<T> = CustomEvent<{ item: T }>;

CrudEditedItemChangedEvent #

/**
 * Fired when the `editedItem` property changes.
 */
export type CrudEditedItemChangedEvent<T> = CustomEvent<{ value: T }>;

CrudEditEvent #

/**
 * Fired when user wants to edit an existing item.
 */
export type CrudEditEvent<T> = CustomEvent<{ item: T; index: number }>;

CrudEditorOpenedChangedEvent #

/**
 * Fired when the `editorOpened` property changes.
 */
export type CrudEditorOpenedChangedEvent = CustomEvent<{ value: boolean }>;

CrudEditorPosition #

export type CrudEditorPosition = '' | 'aside' | 'bottom';

CrudI18n #

export interface CrudI18n {
  newItem?: string;
  editItem?: string;
  saveItem?: string;
  cancel?: string;
  deleteItem?: string;
  editLabel?: string;
  confirm?: {
    delete?: {
      title?: string;
      content?: string;
      button?: {
        confirm?: string;
        dismiss?: string;
      };
    };
    cancel?: {
      title?: string;
      content?: string;
      button?: {
        confirm?: string;
        dismiss?: string;
      };
    };
  };
}

CrudItemsChangedEvent #

/**
 * Fired when the `items` property changes.
 */
export type CrudItemsChangedEvent<T> = CustomEvent<{ value: T[] }>;

CrudNewEvent #

/**
 * Fired when user wants to create a new item.
 */
export type CrudNewEvent = CustomEvent<{ item: null }>;

CrudSaveEvent #

/**
 * Fired when user wants to save a new or an existing item.
 */
export type CrudSaveEvent<T> = CustomEvent<{ item: T; new: boolean }>;

CrudSizeChangedEvent #

/**
 * Fired when the `size` property changes.
 */
export type CrudSizeChangedEvent = CustomEvent<{ value: number }>;

GridFilterDefinition #

export interface GridFilterDefinition {
  path: string;
  value: string;
}

GridSorterDefinition #

export interface GridSorterDefinition {
  path: string;
  direction: GridSorterDirection;
}

GridSorterDirection #

export type GridSorterDirection = 'asc' | 'desc' | null;