List management

Introduction

In DataWeb, the management of collections of predefined elements is facilitated by the data structure called List.

This class allows you to create and manage static lists, which can be used in various parts of the project without having to modify the existing storage system or implement additional classes. Lists are particularly useful for representing datasets that don't change frequently, such as states, object types, themes, or configuration options.

 

Characteristics of the List structure

Lists in DataWeb are designed to contain a maximum of about one hundred items and are static, although it is possible for them to be modified by users if permissions allow it. These lists are used in contexts such as:

 

  • Statuses (e.g. order or task status)
  • Types (e.g. categories of items or projects)
  • Default colors or themes
  • Configuration or setting options
  • Short, static or user-managed lists

 

Management in the DataWeb backend

The creation and management of lists takes place directly in the DataWeb backend, within a dedicated section. Management is initially reserved for developers, but can be extended to other roles through a permissions configuration. The default permission to manage lists is called Private_Lists, which allows you to view only lists that are explicitly associated with the roles you specify.

 

A key feature of lists is their Name, which must be unique and used to call the list in the project code. By convention, all list names begin with the prefix List_ and are declined in the plural, e.g. List_ProjectImage_Types.

 

Lists can also be empty, but generally contain a series of elements defined by:

  • Title: The label that appears in the user interfaces, localized according to the language you set.
  • Value: The actual data used in association storage, which is title-independent and respects specific formatting (uppercase initial, no spaces or special characters).
  • Additional values: Additional properties consisting of key and value can be specified for each element, which can be used to add additional information. For example, a Color property can define an associated color for the element in the UI.

 

 

Finally, you can define the roles that have permission to display the list in the backend. If no roles are specified, only the developer has access to manage the list.

 

Project Management: Using ListService

To use a list within a DataWeb project, you use the ListService service, which provides an interface to retrieve list instances by specifying the name and, optionally, the culture for the title. Here is an example of use:

 

var listCultures = await listService.GetListAsync("List_Cultures");

foreach (var listItem in listCultures.Values)
{
    Console.WriteLine(listItem.Title, listItem.Value);

    foreach (var additionalValue in listItem.AdditionalValues)
    {
        Console.WriteLine(additionalValue.Name, additionalValue.Value);
    }
}

 

In this code, the GetListAsync method is used to retrieve the list named "List_Cultures". The Values property contains the main values of the list, while the AdditionalValues property provides access to the additional values defined for each element.

 

The retrieved lists are cached. This means that subsequent calls to retrieve the list do not impact the storage, improving system performance. The cache is automatically invalidated when a list is modified in the DataWeb backend.

Structure and creation of a form