crud configuration

Doc URL

Content

Resource Configuration Object

The more advanced components in the CRUD library require a configuration object that provides various properties and methods necessary for customizing their functionality.

This configuration object is typically used for each API resource you want to manage with the CRUD system.

Generating CRUD Resource Config

Using the Dile CLI, you can quickly generate the configuration object for CRUD system components.

Install the CLI as indicated on this page
Run the command dile g-resource-config <resource>

Example:

dile g-resource-config country --endpoint https://example.com/api/countries

Find more information on g-resource-config configurations using the following help command:

dile g-resource-config --help

Default Configuration

There are default definitions for the configuration object, which can be found in the lib/defaultConfig.js file. See the default config file on GitHub.

It is entirely possible to follow the format defined in that file to create a custom configuration object. However, the library offers a class called CrudConfigBuilder that simplifies this task.

CrudConfigBuilder Class

This class allows you to build a configuration object more easily. By invoking the class constructor, you can define specific configuration values for a resource. The constructor accepts two arguments:

The URL of the resource's API endpoint
The custom configuration object

import { CrudConfigBuilder } from '@dile/crud/lib/CrudConfigBuilder';
const countryConfig = new CrudConfigBuilder('https://example.com/api/countries', {});

These two argument values will be merged with the default configurations, so if you do not specify any value in the second argument, the default values will always be set.

Additionally, any value in the configuration object provided as the second argument will override the values in the default configuration object.

Once the CrudConfigBuilder instance is created, you can call the getConfig() method to obtain the configuration object.

countryConfig.getConfig();

Creating a Configuration Module for Each Resource

Since the configuration object is usually the same for each resource, it may be useful to create an independent module for each resource. This same configuration object can be used across different components, such as the listing component, the item detail component, or a complete CRUD component.

Here is an example of creating a configuration module that exports the object to access the configuration of a resource:

import { html } from 'lit';
import { CrudConfigBuilder } from '@dile/crud/lib/CrudConfigBuilder';

export const countryConfig = new CrudConfigBuilder('https://timer.escuelait.com/api/countries', {
  templates: {
    item: (country) => html`<demo-country-item .country=${country}></demo-country-item>`,
    insertForm: () => html`<demo-country-form id="insertform"></demo-country-form>`,
    updateForm: () => html`<demo-country-form id="updateform"></demo-country-form>`,
  },
  customization: {
    disablePagination: true,
  },
  sort: {
    options: [
      {
        name: 'name',
        label: 'Name',
        direction: 'desc'
      },
    ],
    initialSortField: 'name',
  },
  availableFilters: [
    {
      name: 'essential',
      label: 'Is essential',
      active: false,
      value: false,
      type: 'boolean',
    },
    {
      name: 'continent',
      label: 'Continent',
      active: false,
      value: false,
      type: 'select',
      options: [
        {
          value: 'Europe',
          label: 'Europe'
        },
        {
          value: 'Africa',
          label: 'Africa'
        },
        {
          value: 'Asia',
          label: 'Asia'
        },
      ]
    },
  ],
});

This module can be used to define configurations specific to the countries resource, including templates for items and forms, pagination settings, sorting options, and filters.

Adapting to API Responses

The responseAdapter property in the configuration object is an object that defines how the CRUD system will extract data from the REST API responses.

The default configuration object for the resource provides a responseAdapter that works with typical REST API responses. However, you can create a custom version of this object by extending the base ResponseApiAdapter class.

For more information, refer to the page dedicated to the responseAdapter object.

Configuration properties

Here is a complete list of the configuration object properties that can be supplied for the resource.

Quick Reference

Property	Type	Description
`availableFilters`	Array	Configure filters to narrow down the list of items
`sort`	Object	Define sorting options and initial sort field
`pageSize`	Object	Configure pagination options for list views
`insertOperation`	Object	Customize the behavior of the insert button
`updateOperation`	Object	Customize the behavior of the edit/update operation
`actions`	Object	Define batch actions for lists and individual actions for single items
`maxBatchActionItems`	Number	Set the maximum number of items for batch actions
`customization`	Object	Customize the behavior and visibility of UI elements
`templates`	Object	Define template functions for rendering different parts of the CRUD interface
`labels`	Object	Customize labels for buttons, titles, and other UI text
`formIds`	Object	Define HTML id attributes for form elements
`requestAdapter`	Object	Adapt requests sent to API endpoints
`responseAdapter`	Object	Adapt API responses to the CRUD system
`computeItemId`	Function	Determine the identifier value for each resource element
`isItemEditable`	Function	Determine if a specific item can be edited
`isItemDeletable`	Function	Determine if a specific item can be deleted
`destructiveActionNames`	Array	List of action names that are destructive and prevent component refresh
`onActionListSuccess`	Function	Handle successful completion of batch actions in dile-crud
`onActionSingleSuccess`	Function	Handle successful completion of actions in dile-crud-single

Property `availableFilters`

This property is used to define the filters that the dile-crud component will offer.

Filter configuration allows two types of filters that generate different query interfaces, either with checkboxes or select boxes. In the following example, you can see a filter configuration:

availableFilters: [
  {
    type: 'boolean',
    name: 'column',
    label: 'Column',
    active: false,
    value: false,
  },
  {
    type: 'select',
    name: 'column2',
    label: 'Column 2',
    active: false,
    value: false,
    options: [
      {
        value: '1',
        label: 'Value 1'
      },
      {
        value: '2',
        label: 'Value 2'
      },
    ]
  },
],

When filters are enabled in the CRUD component, requests are made to the API sending the filter state through the query string.

Default `availableFilters` value

By default, availableFilters is an empty array.

availableFilters: []

Property `sort`

This property configures the sorting options available in the CRUD component, allowing users to sort items by different fields and in different directions (ascending or descending).

The sort property is an object with two main configurations:

`options` (Array)

An array of available sort options. Each option should be an object with the following properties:

name (string): The name of the field to sort by. This should match the field name in your API response.
label (string): The human-readable label that will be displayed in the UI for this sort option.
direction (string): The sort direction - either 'asc' for ascending or 'desc' for descending.

`initialSortField` (string | null)

The name of the sort field that should be initially selected when the component loads. This value must match one of the name values in the options array.

Example usage

sort: {
  options: [
    {
      name: 'name',
      label: 'Name',
      direction: 'asc'
    },
    {
      name: 'year',
      label: 'Year',
      direction: 'desc'
    },
  ],
  initialSortField: 'year',
},

In this example, two sort options are defined: "Name" (ascending) and "Year" (descending). When the component first loads, it will be sorted by the "year" field in descending order.

Default value

By default, no sort options are available and no initial sort field is set:

sort: {
  options: [],
  initialSortField: null,
},

This means sorting will be disabled unless you provide custom sort options in your resource configuration.

Property `pageSize`

This property allows you to configure the pagination settings for list views in the CRUD component.

The pageSize property is an object with two main configurations:

`available` (Array)

An array of page size options that users can select from. These numbers represent how many items should be displayed per page.

`initial` (Number)

The initial page size that will be selected when the component first loads. This value must be one of the values in the available array.

Example usage

pageSize: {
  available: [10, 25, 50, 100],
  initial: 25,
},

In this example, users can choose to display 10, 25, 50, or 100 items per page, and by default, the component will show 25 items per page.

Default value

By default, the page size configuration includes common pagination options:

pageSize: {
  available: [10, 25, 50],
  initial: 25,
},

Property `insertOperation`

This property defines how the insert button behaves in the dile-crud component. By default, when the insert button is clicked, a modal opens with the form for inserting the entity being managed. However, you can define any other behavior you wish, such as navigating to another page where the insert content is displayed.

To do this, insertOperation accepts an object with a property called type. By setting the type value to handler, you can define a handler to execute custom code when the Insert button is pressed. Here's an example:

insertOperation: {
  type: "handler",
  handler: (crudComponent) => {
    navigateService.goToUrl('/create-invoice');
  }
},

Note that the handler function receives the dile-crud component itself, allowing you to interact with the panel if needed.

Default value

The default value of insertOperation causes a modal window to open when the insert button is clicked.

insertOperation: {
  type: 'modal'
},

Property `updateOperation`

The updateOperation property allows you to customize how the CRUD system handles the edit/update operation when a user clicks the edit button on an item.

Default Behavior

By default, the updateOperation is configured to open the update form in a modal dialog:

updateOperation: {
  type: 'modal'
}

Custom Handler

You can override this behavior by providing a custom handler function. This is useful when you want to:

Navigate to a different page for editing
Use a different interface based on item properties
Trigger custom logic before opening the edit form

To use a custom handler, configure updateOperation like this:

updateOperation: {
  type: 'handler',
  handler: (itemId, crudComponent, item) => {
    // Your custom logic here
  }
}

Handler Parameters

itemId: String or Number. The unique identifier of the item being edited.
crudComponent: LitElement. Reference to the CRUD component instance.
item: Object. The complete item data object.

Handler Example

Here's a practical example that navigates to different edit pages based on the item's type:

import { navigateService } from '@your-app/services';

const countryConfig = new CrudConfigBuilder('https://example.com/api/countries', {
  updateOperation: {
    type: 'handler',
    handler: (itemId, crudComponent, item) => {
      if (item.rectificative_type === 'S') {
        navigateService.goToUrl(`/rectificacion-wizard/${itemId}`);
      } else {
        navigateService.goToUrl(`/invoice-wizard/${itemId}`);
      }
    },
  },
});

Configuration Structure

Property	Type	Required	Description
`type`	String	Yes	Either `'modal'` or `'handler'`
`handler`	Function	Only if type is 'handler'	Custom function to handle the update operation

Property `actions`

The actions property defines the operations that can be performed on resources through the CRUD system. This object contains two types of actions:

actions.list: An array of batch actions that can be executed on multiple selected items in list views.
actions.single: An array of individual actions that can be executed on a single item in detail views.

Basic Structure

{
  actions: {
    list: [
      // Batch actions configuration
    ],
    single: [
      // Individual actions configuration
    ]
  }
}

Each action object must include a name (identifier) and a label (display text). Individual actions also support conditional display through the shouldAppear function.

For complete information about configuring actions, including all available properties and examples, see the Actions Configuration page.

Property `maxBatchActionItems`

This property sets the maximum number of items that can be selected for batch actions in the CRUD component.

It is used to show or hide the component that allows users to select all items in the current page or all items in a resource.

Note: The component itself does not check the number of items the user selects. This validation must be performed on the backend before processing the batch actions.

This is useful to prevent users from performing batch operations on an excessive number of items at once, which could impact performance.

Default value

By default, maxBatchActionItems is set to 100.

maxBatchActionItems: 100

You can override this value in your resource configuration object if you need a different limit for your use case.

Property `customization`

This property allows you to customize the behavior and visibility of various elements and features in the CRUD component.

The customization property is an object containing multiple boolean flags that control different aspects of the component's functionality and UI.

Available customization options

disableKeywordSearch (boolean): When set to true, disables the keyword search functionality. Default: true.
hideCountSummary (boolean): When set to true, hides the summary showing the total count of items. Default: false.
hidePageReport (boolean): When set to true, hides the page information (e.g., "Page 1 of 5"). Default: false.
hideCheckboxSelection (boolean): When set to true, hides checkboxes used for selecting multiple items. Default: true.
hideEmptyInsertButton (boolean): When set to true, hides the insert button when no items exist. Default: false.
disableInsert (boolean): When set to true, disables the ability to insert new items. Default: false.
disableEdit (boolean): When set to true, disables the ability to edit existing items. Can be overridden per-item using isItemEditable(). Default: false.
disableDelete (boolean): When set to true, disables the ability to delete items. Can be overridden per-item using isItemDeletable(). Default: false.
disableRestore (boolean): When set to true, disables the restore functionality for soft-deleted items. Default: false.
disablePagination (boolean): When set to true, disables pagination controls. Default: true.
disableSort (boolean): When set to true, disables sorting functionality. Default: true.
disableFilter (boolean): When set to true, disables filtering functionality. Default: true.
disableHelp (boolean): When set to true, hides the help information. Default: true.

Example usage

customization: {
  disableKeywordSearch: false,  // Enable keyword search
  hideCountSummary: false,      // Show total count
  hidePageReport: false,        // Show page information
  hideCheckboxSelection: false, // Show selection checkboxes
  disablePagination: false,     // Enable pagination
  disableSort: false,           // Enable sorting
  disableFilter: false,         // Enable filtering
  disableHelp: false,           // Show help
  disableEdit: false,           // Enable editing
  disableDelete: false,         // Enable deletion
},

Default value

The default configuration disables most features and hides selection UI elements:

customization: {
  disableKeywordSearch: true,
  hideCountSummary: false,
  hidePageReport: false,
  hideCheckboxSelection: true,
  hideEmptyInsertButton: false,
  disableInsert: false,
  disableEdit: false,
  disableDelete: false,
  disableRestore: false,
  disablePagination: true,
  disableSort: true,
  disableFilter: true,
  disableHelp: true,
},

Property `templates`

This property is an object that contains template functions for rendering different parts of the CRUD interface. Each template function uses Lit's html template literal to return the DOM structure for that specific part.

Type: Object

Default Value:

templates: {
  item: () => templatePlaceholder('item'),
  insertForm: (belongsTo, relationId) => templatePlaceholder('insertForm'),
  updateForm: () => templatePlaceholder('updateForm'),
  help: () => templatePlaceholder('help'),
  detail: () => templatePlaceholder('detail'),
  formActions: (actionName) => html`
    <dile-pages attrForSelected="action" selected="${actionName}">
      <dile-crud-delete-action  action="DeleteAction"></dile-crud-delete-action>
    </dile-pages>
  `,
  relations: () => '',
  formSingleActions: () => '',
}

Template Functions