Modelling Lists with Bloqs Standard UI Components

Bloqs provides a set of standard UI components that allow you to declaratively model your user interface. One of the most common patterns is modelling list pages that display entity data in a structured way.

With the ListComponent, you can quickly configure a list that supports displaying, adding, and editing entities.

---

1. Defining a List Page

To create a list page, declare a Page in your app model and use a ListComponent inside the Area.

Example: Category List Page

var listComponent = new ListComponent
{
    EntityClassId = IdGen.GetEntityClassId<Category>(),
    AddPageId = AppConstants.Pages.CategoryAddPage,
    EditPageId = AppConstants.Pages.CategoryEditPage,
    Columns =
    [
        new ListColumn
        {
            PropertyId = IdGen.GetPropertyId<Category>(nameof(Category.Name)),
            Area = PageBuilderExtensions.VerticalContainer(
                PageBuilderExtensions.PropertyValue(
                    IdGen.GetPropertyId<Category>(nameof(Category.Name))
                )
            ),
        },
    ],
};

return appBuilder.AddPage(
    new Page
    {
        Id = AppConstants.Pages.CategoryListPage,
        Title = "List Categories",
        Name = "categories",
        Area = ContainerComponent.Create(
            ContainerComponent.Create(
                new GridComponent
                {
                    Items =
                    [
                        new GridItem
                        {
                            Size = 12,
                            Component = PageBuilderExtensions.Html(
                                "Simplicity is the ultimate sophistication. 🌼"
                            ),
                        },
                        new GridItem { Size = 12, Component = listComponent },
                    ],
                }
            )
        ),
    }
);

---

2. Key Elements Explained

Page

• Id: A unique identifier for the page, usually stored in AppConstants.Pages.

• Title: The page title shown in the UI.

• Name: The route segment for navigation (e.g., /categories).

---

GridComponent

• Provides a responsive grid layout for arranging components.

• Contains multiple GridItems, each defining a UI component and its size.

---

HtmlComponent

• Allows you to display static content such as headers, descriptions, or quotes.

• Useful for adding explanatory text or branding.

---

ListComponent

The ListComponent is the core of a list page.

• EntityClassId: Defines which entity type to display (e.g., CategoryEntityClass).

• AddPageId: The page to navigate to when creating a new entity.

• EditPageId: The page to navigate to when editing an existing entity.

• Columns: Defines which entity properties should be displayed in the list.

---

ListColumn

Each column in the list maps to a property of the entity.

• PropertyId: Defines which entity property is shown (e.g., CategoryNameProperty).

• Area: Defines the component used to render the column (commonly BoundLabelComponent).

Example Column:

new ListColumn
{
    PropertyId = IdGen.GetPropertyId<Category>(nameof(Category.Name)),
    Area = ContainerComponent.Create(
        new PropertyValueComponent
        {
            PropertyId = IdGen.GetPropertyId<Category>(nameof(Category.Name)),
        }
    ),
}

This will display the Category Name in the list.

---

3. Best Practices

• EntityClassId: Always use entity constants (from AppConstants.Classes) for maintainability.

• Separation of Concerns: Keep your add/edit pages separate (AddPageId / EditPageId).

• Consistent Columns: Reuse property constants (from AppConstants.Properties) to ensure consistent labels and bindings.

---

Key Points

1. ListComponent is used to display entity data in a list.

2. Each list supports Add and Edit actions through linked pages.

3. Use ListColumn to bind entity properties to list cells.

4. UI layout is controlled by the GridComponent and its GridItems.