1.Prepare the Domain Model (IMPORTANT)
You need 3 entities minimum.
Example:
- RowEntity → e.g.
User - ColumnEntity → e.g.
Role - LinkEntity (association table) → e.g.
UserRole
Structure:
User 1---* UserRole *---1 Role
UserRole can have extra attributes (Boolean, Date, etc.)
2.Add Matrix Widget to the Page
- Open the page
- Drag Matrix widget from Toolbox
- Place it inside a Data View (important)
3.Configure Data Sources
a) Context (Data View)
- Data View entity → RowEntity (or a parent entity)
b) Rows
- Row data source → XPath or Microflow
- Entity →
User - This becomes the vertical axis
c) Columns
- Column data source → XPath or Microflow
- Entity →
Role - This becomes the horizontal axis
4.Configure the Cell (Core Logic)
This is the key part.
Cell Entity
- Set Cell entity →
UserRole - This entity must connect RowEntity + ColumnEntity
Association settings
- Row association →
UserRole/User - Column association →
UserRole/Role
5.Define Cell Content
Inside the Matrix cell:
- Add a Check box, Text, or Button
- Bind it to an attribute in
UserRole- Example:
IsAssigned (Boolean)
This decides what shows in each cell.
6.Enable Editing (Optional)
If you want interaction:
- Allow create/delete on
UserRole - Use:
- Checkbox → toggles association
- Button → triggers microflow (create/delete link)
7.Permissions (Very Important)
Make sure:
- Read access → RowEntity, ColumnEntity
- Create/Delete access → LinkEntity (
UserRole) - Otherwise matrix will look empty or non-editable
8.Test the Matrix
Expected behavior:
- Rows = Users
- Columns = Roles
- Cell shows whether User ↔ Role exists
- Changing a cell updates the association
Common Mistakes (Avoid This)
Missing link entity
Wrong associations selected
Matrix outside Data View
No create/delete rights on link entity
Expecting Matrix to work without many-to-many model
When to Use Matrix Widget
✔ Role vs User assignment
✔ Feature vs Permission mapping
✔ Product vs Attribute comparison
✔ Availability / selection grids
❌ Not for simple lists
❌ Not for single-entity data