Add a screen with metadata

This guide adds a new entity screen to an existing module app. You declare the entity in the module's metadata and add one sidebar section; the web app then shows a tab with a list, a create form, and a record card without any change in webapp/. Background is on metadata rendering. Writing the backend routes for the entity is covered by write a backend module.

Prerequisites¶

• The module exists and is loaded by the module registry; see module lifecycle.
• The entity has HTTP routes for list, get, create, update, and delete under the module's prefix /api/v1/<module> (src/cluster_erp/core/module_base.py:37-38).
• The module has an app in the app catalogue with screen: "module", so it opens as a module app (webapp/js/home.js:2429). The catalogue is src/cluster_erp/modules/app_store/catalog.json.

Steps¶

1. Declare an EntityMeta for the entity in the module's metadata.py. Give labels in English and Turkish, the entity_type, and the endpoint paths relative to the module prefix. Source: src/cluster_erp/core/metadata.py:553-649.

From src/cluster_erp/modules/currencies/metadata.py:302-313:

python PAYMENT_TERM_META = EntityMeta( label={"en": "Payment Term", "tr": "Ödeme Koşulu"}, label_plural={"en": "Payment Terms", "tr": "Ödeme Koşulları"}, entity_type="payment_term", is_settings_entity=True, endpoints={ "list": EndpointMeta(method="GET", path="/payment-terms/"), "create": EndpointMeta(method="POST", path="/payment-terms/"), "get": EndpointMeta(method="GET", path="/payment-terms/{id}"), "update": EndpointMeta(method="PUT", path="/payment-terms/{id}"), "delete": EndpointMeta(method="DELETE", path="/payment-terms/{id}"), },

2. Add a list_view with columns and filters. Set search_enabled=True if the list endpoint accepts search; the list then shows a search field and the entity becomes searchable in the command palette. Source: webapp/js/gen-list.js:582-597, webapp/js/home.js:1241-1243.

3. Add a form with field groups. Use field_type="decimal" for money so the value travels as a string. Source: webapp/js/gen-form.js:503-506, money and Decimal.

From src/cluster_erp/modules/currencies/metadata.py:365-373:

python FieldMeta( key="code", label={"en": "Code", "tr": "Kod"}, field_type="string", required=True, max_length=20, weight="hero", immutable_on_edit=True, ),

4. If the record needs a card with several sections, add a detail_view with tabs. Without one, a row opens a read-only record card built from the form. Source: webapp/js/gen-list.js:816-844.

5. Register the entity in ModuleMeta.entities and add a sidebar section with view_type="list" that names the entity key. Source: webapp/js/module-app.js:115-116.

From src/cluster_erp/modules/currencies/module.py:132-141:

python SidebarSectionMeta( key="payment_term_list", label={ "en": "Payment Terms", "tr": "Ödeme Koşulları", }, view_type="list", icon="payments", entity="payment_term", ),

6. If the screen needs a specific permission beyond the entity's own codes, set required_permission on the section. Source: webapp/js/module-app.js:106-108.

7. Restart the server. The metadata document is built once per process, and permission codes for each entity are seeded from metadata at start-up. Source: src/cluster_erp/server/app.py:1530-1543 and src/cluster_erp/server/app.py:634-858 at commit 92f8051.

8. Grant the new <entity_type>.read, .create, .update, and .delete codes to the roles that need them. The system admin role receives every code automatically. See roles and permissions.

Verify the result¶

• Open the module app. A new tab with the section label appears when the module has more than one tab (webapp/js/module-app.js:148-168).
• The tab shows Add New (common.add) for a user with <entity_type>.create, and the list rows for a user with read access (webapp/js/gen-list.js:396-406, webapp/js/gen-list.js:702-711).
• A row tap opens the card; Edit (common.edit) switches to the form (webapp/js/gen-form.js:2318-2346).
• The Turkish label shows when the language is Turkish (webapp/js/meta.js:284-288).

Troubleshooting¶

Terms introduced¶

Related pages¶

• Web app platform
• Metadata rendering
• Metadata model
• Generic list
• Generic form

Verified against commit 92f8051 on 2026-11-13.