Metadata Matrix field
The Matrix field renders structured data as an interactive table. Depending on the type, rows can be predefined or added dynamically at runtime, and columns can hold text inputs, checkboxes, or other supported field types.
The Matrix field is available from OpenKM 8.2.6 onwards.
| Attribute | Description | Required |
|---|---|---|
| label |
The text shown as a label in the user interface. |
true |
| name |
Unique field identifier. Two metadata fields can't have the same name. The name must be unique. The name must start with "okp:". Using the metadata group name as a basis for the metadata field name is good practice. For example, if "okg:contracts" has been used as the group name, use "okp:contracts.matrix" by changing "okg" to "okp". That helps to find the metadata group based on the metadata field name. Please use only letters, numbers, and underscores: "0-9a-zA-Z_". |
true |
| type |
Defines the structure and interaction mode of the matrix table. Allowed values:
|
false |
| value |
Default value for the field. The value is stored internally as a JSON array of row objects. |
false |
| placeholder |
Placeholder text displayed in editable cells before the user enters a value. |
false |
| width |
The width of the matrix table element. Default: In the KCenter UI, width values must be specified as percentages, for example:
|
false |
| height |
The height of the matrix table element. Accepts CSS size values (e.g. |
false |
| readonly |
When set to true, the matrix cannot be modified in the user interface. Default: false. |
false |
| description |
General description of the field. |
false |
|
dbColumnSize |
Set the size of the database column where the matrix value is stored. Matrix values are serialized as JSON and can be substantially larger than single-value fields. The default column size is 512 characters. Increase this value if the expected data volume exceeds that limit. Take a look at the Metadata XML definition documentation section for a detailed explanation of how metadata is stored in the OpenKM database. |
|
|
defaultAccess |
Default security access policy. By default, it is set to grant so all users will see the field. |
|
|
Child elements:
|
||
Dynamic matrix
In dynamic mode the table has no predefined rows. Columns are fixed, and users can add as many rows as needed at runtime. This is the default type when type is omitted.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
"http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
<property-group label="Purchase Order" name="okg:purchase">
<matrix label="Line Items" name="okp:purchase.line_items" type="dynamic" width="100%">
<input label="Product Description" name="description" type="text"></input>
<input label="Unit Price" name="unit_price" type="text"></input>
<input label="Quantity" name="quantity" type="text"></input>
</matrix>
</property-group>
</property-groups>Multi-select matrix
In multi-select mode both rows and columns are predefined. The table structure is fixed, and users fill in the cell values. Any supported column field type can be used.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
"http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
<property-group label="Sales Planning" name="okg:sales">
<matrix label="Quarterly Targets" name="okp:sales.quarterly_targets" type="multi-select" width="100%">
<row label="Q1"/>
<row label="Q2"/>
<row label="Q3"/>
<row label="Q4"/>
<input label="Revenue Target" name="revenue_target" type="text"></input>
<input label="New Clients" name="new_clients" type="text"></input>
<input label="Region" name="region" type="text"></input>
</matrix>
</property-group>
</property-groups>Single-select matrix
In single-select mode the table has fixed rows and checkbox columns. The user must select exactly one checkbox per row. If any row is left without a selection, a validation warning is displayed.
Column elements in a single-select matrix must be of type checkbox. Only one checkbox may be selected per row; leaving a row empty triggers a validation warning.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
"http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
<property-group label="Risk Management" name="okg:risk">
<matrix label="Risk Assessment" name="okp:risk.assessment" type="single-select" width="100%">
<row label="Security Risk"/>
<row label="Operational Risk"/>
<row label="Compliance Risk"/>
<checkbox label="Acceptable" name="acceptable"></checkbox>
<checkbox label="Moderate" name="moderate"></checkbox>
<checkbox label="Critical" name="critical"></checkbox>
</matrix>
</property-group>
</property-groups>
