Basic concepts in Flutter Artist

Shelf
Storage
Block
FormModel
FilterModel
Scalar
Activity

FlutterArtist envisions a scene where you step into a warehouse (storage) with numerous shelves (shelves) filled with goods. This imagery serves as the foundation for the concepts of Storage, Shelf, Block, Scalar, FilterModel, FormModel,... in FlutterArtist.

1. Shelf

Semantically, a Shelf is a rack where you can place various items. However, in the world of FlutterArtist, it is the place where Block(s), Scalar(s), FilterModel(s), and FormModel(s) are situated.

class CatProductShelf extends Shelf {

  @override
  ShelfStructure defineShelfStructure() {
    return ShelfStructure(
      description: "",
      filterModels: {
        "category-filter-model": CategoryFilterModel(),
      },
      blocks: [
        CategoryBlock(
          name: "category-block",
          description: null,
          filterModelName: "category-filter-model",
          formModel: CategoryFormModel(),
          childBlocks: [ 
              ProductBlock(
                name: "product-block",
                description: null,
                filterModelName: null,
                formModel: ProductFormModel(),
                childBlocks: null,
              ),
          ],
        ),
      ],
      scalars: [],
    );
  } 
  ....
}

A Shelf is a unit within your application. A Shelf will include FilterModel(s), Block(s), Scalar(s), and FormModel(s) that are interrelated to create a specific functional feature of the app. For instance, in your application, the supplier declaration feature would include a SupplierBlock and a SupplierFormModel combined together within a SupplierShelf.

SupplierShelf

class SupplierShelf extends Shelf {

  @override
  ShelfStructure defineShelfStructure() {
    return ShelfStructure(
      description: "",
      filterModels: {},
      blocks: [
        SupplierBlock(
          name: "supplier-block",
          description: null,
          filterModelName: null,
          formModel: SupplierFormModel(),
          childBlocks: null,
        ),
      ],
      scalars: [],
    );
  } 
  ....
}

Slightly more complex, CategoryBlock, CategoryFormModel, ProductBlock, and ProductFormModel combine within a CatProductShelf to create a feature that allows for the creation and modification of both Category and Product.

2. Storage

After creating your YourShelf class, you need to register it with the FlutterArtist Storage. This process is similar to purchasing a new Shelf and placing it inside the Storage warehouse.

my_storage_structure.dart (*)

class MyStorageStructure extends StorageStructure { 

  @override
  void registerShelves() {
    FlutterArtist.storage.registerShelf(() => CatProduct13aShelf()); 
    ...
  }
  ...
}

Once the Shelf is placed in the Storage, you can easily locate it and the items it contains.

CatProduct13aShelf shelf = FlutterArtist.storage.findShelf();

var categoryBlock = shelf.findBlock("category-block") as Category13aBlock;
var productBlock = shelf.findBlock("product-block") as Product13aBlock;

var categoryFormModel = categoryBlock.formModel as Category13aFormModel;
var productFormModel = productBlock.formModel as Product13aFormModel;

Debug Storage Viewer is a visual tool that allows you to view the list of Shelf(s) registered with FlutterArtist Storage and inspect their structure.

3. Block

Block is one of the most critical concepts in FlutterArtist, functioning much like a table in a database. A Block is declared as a component of a Shelf. These Block(s) can be independent or maintain parent-child relationships, mirroring the relational structure between database tables.

A Block is not a UI component; it is a Data Model.

A Block contains a list of ITEM(s), where an ITEM is a Dart object. BlockItemsView is used to render this list on the user interface.
When a user selects an ITEM as the current element, this ITEM is reloaded with more comprehensive data (ITEM_DETAIL) and displayed via the BlockItemDetailView.

performQuery	This abstract method is used to load a list of ITEM(s) from the Backend, much like querying a database table to retrieve records.
performLoadItemDetailById	This abstract method is used to fetch the complete information of an ITEM and return an ITEM_DETAIL.
performDeleteItemById	This abstract method is used to delete an ITEM.

FlutterArtist Block ex1

4. FormModel

FormModel acts as the core data model for forms, optionally configured within each Block to manage input states. The distinct separation between FormModel and FormView allows FlutterArtist to maintain a streamlined and consistent two-way data binding mechanism.

ShelfStructure(
  description: "",
  filterModels: {},
  blocks: [
    CategoryBlock(
      name: "category-block",
      description: null,
      formModel: CategoryFormModel(), // ***
      childBlocks: [ 
          ProductBlock(
            name: "product-block",
            description: null,
            formModel: ProductFormModel(), // ***
            childBlocks: null,
          ),
      ],
    ),
  ],
  scalars: [],
)

The data within the FormModel is displayed through the FormView. As users modify data on the FormView, these changes are synchronously updated back into the FormModel.

Every user interaction on the UI is instantly reflected in the underlying data model. To make this process transparent, Debug Form Model View allows you to monitor and analyze every change in the data structure without the need for manual logging operations.

FlutterArtist Form - Ví dụ 1

5. FilterModel

FilterModel is a data model used to manage filtering criteria. In FlutterArtist, a FilterModel can be shared by multiple Block(s) or Scalar(s) within the same Shelf. This means that when a user enters a search keyword (for example, "love"), the criterion is immediately applied to filter data across all components connected to that FilterModel.

ShelfStructure

ShelfStructure(
  filterModels: {
    "category-filter-model": CategoryFilterModel(), 
    "product-filter-model": ProductFilterModel(),
  },
  blocks: [
    CategoryBlock(
      name: "category-block",
      filterModelName: "category-filter-model", 
      ...
    ),
    ProductBlock(
      name: "product-block",
      filterModelName: "product-filter-model", 
      ...
    ),
  ],
  scalars: [
    CategoryScalar(
      name: "category-scalar",
      filterModelName: "category-filter-model", 
      ...
    ),
  ]
)

ShelfStructure(
  filterModels: {
    "song2a-filter-model": Song02aFilterModel(), // <---
  },
  blocks: [
    Song02aBlock(
      name: "song2a-block",
      description: null,
      filterModelName: "song2a-filter-model", // <---
      formModel: null,
      childBlocks: [],
    ),
  ],
)

For example, you can use CategoryFilterModel to coordinate searching for CategoryBlock and CategoryScalar, while ProductFilterModel is dedicated to managing filtering criteria for ProductBlock.

The data in FilterModel is displayed through FilterPanel. When the user enters text or selects options on the FilterPanel, those changes are updated directly in the FilterModel.

Debug Form Model Viewer is a tool that allows you to visually inspect the criteria defined in the FilterModel. Through this tool, you can view the data types, the relationships between the criteria, as well as their initial values and current values,...

FlutterArtist Filter - Ví dụ 1

6. Scalar

A Scalar is a data model consisting of only a single value, which is consistent and immutable by nature. It is typically used to manage data for a report, a summary, or Dashboard information.

ShelfStructure(
  description: "",
  filterModels: {
    "best-selling-filter-model": BestSellingFilterModel(),
  },
  blocks: [],
  scalars: [
    BestSellingScalar(
      name: "best-selling-scalar",
      description: null,
      filterModelName: "best-selling-filter-model",  
    ),
  ],
);

Imagine a report on the top 10 best-selling products in Q1: the entire list of those 10 products, along with their quantities sold and total revenue, are all encapsulated into a single data block within a Scalar.

A value of a BestSellingScalar

{
  "timeFrame": "Q1/2025",
  "bestSellings": [
     {
       "productId": 1,
       "productName": "Cocacola",
       "qty": 1000,
       "amount": 10000,
     },
     {
       "productId": 2,
       "productName": "Pepsi", 
       "qty": 1200,
       "amount": 12000,
     }
  ]
}

Below is a table comparing the core differences between a Block and a Scalar:

Block	Scalar
Contains a list of multiple ITEM(s).	Consists of only a single value (can be a complex object).
Allows managing the lifecycle of each record (Add, delete, edit).	Cannot be directly modified; it is immutable.
Similar to a data table with multiple rows.	Similar to a summary report or Dashboard data.
Changes through CRUD actions on each ITEM.	Self-refreshes by re-querying the entire value when the source data changes.

FlutterArtist Scalar ex.1

7. Activity

While Block and Scalar follow a template-based approach to optimize operations around data, Activity serves as a flexible component for more general use cases. Logic that is not purely about displaying or querying data, such as login flows, authentication, or complex navigation processes, is where Activity truly comes into play.

In other words, an Activity acts as a free-form controller, allowing you to define custom states and behaviors without being constrained by the predefined data structures of FlutterArtist. It can be said that Block and Scalar are the two most specialized and common components; however, if they do not fit your specific purpose, use an Activity.

FlutterArtist Activity ex1 (***)

No ADS