logo dile-components dile-components
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.

  1. Install the CLI as indicated on this page
  2. 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:

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
maxBatchActionItems Number Set the maximum number of items for batch actions
customization Object Customize the behavior and visibility of UI elements
requestAdapter Object Adapt requests sent to API endpoints
responseAdapter Object Adapt API responses to the CRUD system
isItemEditable Function Determine if a specific item can be edited
isItemDeletable Function Determine if a specific item can be deleted

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:

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:

To use a custom handler, configure updateOperation like this:

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

Handler Parameters

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

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 requestAdapter

This property allows adapting the requests sent from the CRUD system to the API endpoints, so that it can communicate with the web service in the required way.

There is a detailed page with explanations about the request adapter.

Default requestAdapter value

The default configuration creates a generic request adapter using an instance of the RequestApiAdapter class.

new RequestApiAdapter()

Property responseAdapter

This property allows adapting the API responses that the CRUD system communicates with. Thanks to this object, the components can work with any API, regardless of how its responses are structured.

On this site you can find a detailed page explaining how to create the response adapter.

Default responseAdapter value

The default configuration creates a generic response adapter using an instance of the ResponseApiAdapter class.

new ResponseApiAdapter()

Property isItemEditable

This property is a function that determines whether a specific item can be edited or not. It allows you to implement custom logic to enable or disable the edit action on a per-item basis.

The function receives the item element as a parameter and should return a boolean value:

This works in conjunction with the customization.disableEdit boolean property. An item is considered editable only if:

  1. customization.disableEdit is false (editing is globally enabled)
  2. AND isItemEditable(item) returns true (the specific item is editable)

Example usage

isItemEditable(item) {
  // Only allow editing of items with status 'active' or 'draft'
  return ['active', 'draft'].includes(item.status);
}

Default value

By default, the function always returns true, allowing all items to be edited (as long as customization.disableEdit is false).

isItemEditable(element) {
  return true;
}

Property isItemDeletable

This property is a function that determines whether a specific item can be deleted or not. It allows you to implement custom logic to enable or disable the delete action on a per-item basis.

The function receives the item element as a parameter and should return a boolean value:

This works in conjunction with the customization.disableDelete boolean property. An item is considered deletable only if:

  1. customization.disableDelete is false (deletion is globally enabled)
  2. AND isItemDeletable(item) returns true (the specific item is deletable)

Example usage

isItemDeletable(item) {
  // Prevent deletion of items that have child relationships
  return !item.hasChildren;
}

Default value

By default, the function always returns true, allowing all items to be deleted (as long as customization.disableDelete is false).

isItemDeletable(element) {
  return true;
}

Documentation in progress

This documentation is a work in progress.