Skip to main content

Entity Manager

The entity-management micro front-end provides a seamless way to interact with back-end resources, enabling users to manage entities directly from the front-end. It features two core components: a grid for displaying and managing entity data and a form for creating or updating entities.

Below are some of its standout capabilities that streamline entity interaction and enhance user experience:

  • Event Handlers:

    • Configure Create, Edit, and Delete events for seamless resource management.
    • Automatically adds buttons to the grid, allowing users to perform actions such as creating, editing, or deleting records.

  • Automatic Form Generation:

    • Forms are dynamically generated from the back-end resource metadata.
    • Simplifies the process of creating or updating entities.

  • Dynamic Grid Configuration:

    • Displays entities as rows with attributes in columns for a clear and structured overview.
    • Integrates with back-end data sources like Data Server queries or Request Server requests to populate data dynamically.

  • Streamlined Workflow:

    • Combines the grid and form seamlessly to allow quick navigation between viewing, creating, and editing entities.
    • Reduces development time by leveraging pre-built components.

Adding the Entity Management component to the template​

Below is a simple example of how to configure the Entity Management component. This example demonstrates not only the basic setup but also how the component interacts with back-end resources, showing the grid and the form for creating new records. The configuration is straightforward, allowing for quick integration into your template.

Declaration:

<entity-management></entity-management>

Usage:

@customElement({
  name: 'entity-management-example',
  template: html`
   <entity-management
      design-system-prefix="rapid"
      resourceName="ALL_COUNTERPARTYS"
      title="Counterparty Management"
      createEvent="EVENT_COUNTERPARTY_INSERT"
    ></entity-management>
  `,
})
export class EntityManagementExample extends GenesisElement {}
Entity Management Counterparty Server Model

The following example is based on the following kotlin code snippets.

In your app-name-tables-dictionary.kts add:

tables {
  table(name = "COUNTERPARTY", id = 11_001) {
    field("COUNTERPARTY_ID", STRING).sequence("CP")
    field("COUNTERPARTY_LEI", STRING(100)).metadata {
      maxLength = 100
      minLength = 0
    }
    field("ENABLED", BOOLEAN).default(false).notNull()
    field("NAME", STRING(100)).notNull().metadata {
      maxLength = 100
      minLength = 0
    }
    primaryKey("COUNTERPARTY_ID")
  }
}

In your app-name-dataserver.kts add:

  query("ALL_COUNTERPARTYS", COUNTERPARTY) {
    fields {
      COUNTERPARTY_ID
      COUNTERPARTY_LEI
      ENABLED
      NAME
    }
  }

In this example, we configure the entity-management using three key attributes:

  1. design-system-prefix="rapid" - Ensures that all UI elements are styled according to the rapid design system.
  2. resourceName="ALL_COUNTERPARTYS" - Defines the source of the data for the grid: a Data Server query called ALL_COUNTERPARTYS.
  3. title="Counterparty Management" - Displays "Counterparty Management" as the title of the grid.
  4. createEvent="EVENT_COUNTERPARTY_INSERT" - Generates a form with all the fields from the metadata of the EVENT_COUNTERPARTY_INSERT event and adds a button at the top of the grid so that the user can access this form to create new entities.

With these attributes in place, the grid will appear on your page when the application is run locally, provided the back-end resources are correctly configured.

And you can click on the Add button to view the form.

Configuring the Entity Management Component for Counterparty Management​

Below is a simple example of how to configure the Entity Management component. This example demonstrates not only the basic setup but also how the component interacts with back-end resources, showing the grid and the form for creating new records. The configuration is straightforward, allowing for quick integration into your template.

Declaration:

<entity-management></entity-management>

Usage:

const counterpartyUIschema = {
  type: 'VerticalLayout',
  elements: [
    { type: 'Control', scope: '#/properties/COUNTERPARTY_ID', label: 'Id' },
    {
      type: 'Control',
      label: 'Counterparty Lei',
      scope: '#/properties/COUNTERPARTY_LEI',
    },
    { type: 'Control', scope: '#/properties/ENABLED', label: 'Enabled' },
    { type: 'Control', scope: '#/properties/NAME', label: 'Counterparty Name' },
  ],
};

@customElement({
  name: 'entity-management-example',
  template: html`
   <entity-management
        enable-search-bar
        design-system-prefix="rapid"
        resourceName="ALL_COUNTERPARTYS"
        title="Counterparty Management"
        :createFormUiSchema=${(x) => counterpartyUIschema}
        updateEvent="EVENT_COUNTERPARTY_MODIFY"
        deleteEvent="EVENT_COUNTERPARTY_DELETE"
        createEvent="EVENT_COUNTERPARTY_INSERT"
    ></entity-management>
  `,
})
export class EntityManagementExample extends GenesisElement {}

In this example, we configure the entity-management using the following attributes:

  1. design-system-prefix="rapid" - Ensures that all UI elements are styled according to the rapid design system.
  2. resourceName="ALL_COUNTERPARTYS" - Defines the source of the data for the grid: a Data Server query called ALL_COUNTERPARTYS.
  3. title="Counterparty Management" - Displays "Counterparty Management" as the title of the grid.
  4. :createFormUiSchema=${(x) => counterpartyUIschema} - Specifies the UI schema for the create form. It dynamically loads the schema for the counterparty form from a predefined JavaScript object or function, ensuring that the form fields align with the data structure of the entity.
  5. updateEvent="EVENT_COUNTERPARTY_UPDATE" - Defines the event used for updating existing counterparty records. This triggers the form to populate with the data of the selected entity for editing.
  6. deleteEvent="EVENT_COUNTERPARTY_DELETE" - Defines the event used for deleting counterparty records. A button will be displayed for users to delete the selected entity from the grid.
  7. createEvent="EVENT_COUNTERPARTY_INSERT" - Generates a form with all the fields from the metadata of the EVENT_COUNTERPARTY_INSERT event and adds a button at the top of the grid so that the user can access this form to create new entities.
  8. enable-search-bar - Enables the search bar functionality within the grid, allowing users to search for specific entities.

With these attributes in place, the grid will appear on your page when the application is run locally, provided the back-end resources are correctly configured.

And you can click on the Add or Edit button to view/edit the form.

Common attributes & properties​

The most common attributes and properties you can configure for entity-management are listed below.

AttributeDescriptionMandatory
titlecustomises the title of the entity list so that the user can see what resource they are managing.Yes
resourceNamespecifies the name of a resource on the server: a query in the Data Server, a ReqRep in the Request Server.Yes
createEventspecifies an event on the back end for adding a record to the table; once specified, this displays an Add button above the grid.No
updateEventspecifies an event on the back end for modifying a record in the table; once specified, this displays an Edit button to the right of every record in the grid.No
deleteEventspecifies an event on the back end for deleting a record in the table; once specified, this displays a Delete button to the right of every record in the grid.No
persist-column-state-keythe user can change columns (the width, for example); if you want the column states to be persisted when the user navigates away from the page, specify a unique string value. By default, changes are not persisted, and the grid returns to its default state every time the user navigates away from it.No
crud-menu-positionspecifies the position of the CRUD action buttons (Add, Edit, Delete) within the grid. Possible values are: column, top, bottom, none (no menu displayed)No
crud-menu-styledefines the visual style of the CRUD action buttons. Possible values are default (displays the buttons side by side), actions-vertical (displays a small button with three vertical dots; when the user clicks on this small button, the available CRUD options are displayed vertically), actions-horizontal (displays a small button with three vertical dots; when the user clicks on this small button, the available CRUD buttons are displayed horizontally)No
crud-action-menu-namedefines the label used for the CRUD action menu.No
info

Note that it is not mandatory to specify an event, but if you don't specify a createEvent or an updateEvent, then you won't have a form created - which defeats the point of using this micro front-end. It would be simpler to use a grid-pro or grid-tabulator.

warning

The persist-column-state-key string defines the key where the serialised state of the columns is stored, as an object in local storage.

If you set multiple entity-management components in your application, you must use unique keys to persist the state - otherwise, the user experience will be unpredictable.

PropertyDescriptionMandatory
datasourceConfigconfigures the interaction with the back-end resource.No
defaultEntityValuesan object that contains default values to populate the form when the user is adding an entity.No
columnsenables you to supply an array of ColDef[] properties to customise the grid.No
createFormUiSchemaenables you to supply a schema to configure an insert form.No
updateFormUiSchemaenables you to supply a schema to configure an update form.No
info

For a full list of attributes and properties with examples, see the Entity Manager declarative HTML or API documents.