# Box-matrix

Box-matrix is another view of list.

The list filter would work on the fly with box-matrix since both will be sharing the same datasource, that is the same entityset.

This works as a readonly view of the list control and supports two views; the list view and the avatar view. Figure 1 - Box-matrix Control Figure 2 - Box-matrix - Avatar View Figure 3 - Box-matrix - List View

## Variations

Box-matrix is a variation of the list control.

## When to use

Use the box-matrix control when the data can be plotted on an X and Y axis. That is where data could be mapped on to each axis under different categories.

## Limitations

Since this control is a variation of the list control, it can only be used along with a list.

## How to use

### 1. Define a box-matrix

To use the box-matrix you must first define it for an entity.

``````
boxmatrix <box_matrix_name> for <box_matrix_entity> {
...
}

``````

`<box_matrix_name>` - Box-matrix identifier, use a meaningful name.

``````
//Example Code
//------------
boxmatrix EmployeesMatrix for TstEmployee {
...
}

``````

### 2. Add the box-matrix to the list

Next, the defined box-matrix must be added to the relevant list control.

``````
list <list_name> using <entity> {
boxmatrix <box_matrix_name>;
}

``````

``````
//Example Code
//------------
list EmployeesList for TstEmployee {
boxmatrix EmployeesMatrix;
...
}

``````

### 3. Populate the axis of the box-matrix

Since its a variation of the list, it will be sharing the same entityset. But data for the axis should be populated either through an enumeration or from a separate datasource.

Note: The `xaxis` is a mandatory property, while `yaxis` is not mandatory.

#### Populate the axis using an enumeration

``````
boxmatrix <box_matrix_name> for <box_matrix_entity> {
xaxis <enumeration_attribute_name> {
...
}
yaxis <enumeration_attribute_name> {
...
}
...
}

``````

`<enumeration_attribute_name>` - `<box_matrix_entity>` should contain the respective enumeration attribute.

``````
//Example Code

boxmatrix EmployeesMatrix for TstEmployee {
xaxis PotentialCategoryEnumeration {
label = "Any custom axis label";
}
yaxis PerformanceCategoryEnumeration {
label = "Any custom axis label";
}
...
}

``````

`label` - Sets the axis label

#### Populate the axis using a separate datasource

``````
boxmatrix <box_matrix_name> for <box_matrix_entity> {
xaxis <Column which contains value of xaxis in box_matrix_entity> from <x_entity> using <x_entityset> {
label = "Any custom axis label";
map <Column which contains value of xaxis in x_entity>;
orderby <Columns in x_entity>;
...
}
yaxis <Column which contains value of yaxis in box_matrix_entity> from <y_entity> using <y_entityset> {
label = "Any custom axis label";
map <Column which contains value of yaxis in y_entity>;
orderby <Columns in y_entity>;
...
}
...
}

``````

The column name given just after `xaxis`/`yaxis` should be a column which exist in the `<box_matrix_entity>`, followed by the respective entity and entityset name of `xaxis` & `yaxis`.

`map` - This is going to be the value column which maps to the `<box_matrix_entity>`. Hence values in the column given for `xaxis` and `yaxis` should exist in the column specified here. Values in the map column will be used as labels for axis points.

`orderby` - If required it is possible to set a default ordering for the axis. The columns should be from respective axis entity.

``````
//Example Code
//------------
boxmatrix EmployeesMatrix for TstEmployee {
xaxis PotentialCategory from TstPotential using TstPotentialSet {
map PotentialCategory;
...
}
yaxis PerformanceCategory from TstPerformance using TstPerformanceSet {
map PerformanceCategory;
orderby = Ranking desc;
...
}
...
}

``````

A card reference can be connected to an item in the box-matrix to open a popup card to display extra information of the record. Both the box-matrix and card would share the same record.

``````
//Example Code
//------------
boxmatrix EmployeesMatrix for TstEmployee {
card BoxMatrixCard;
//Box matrix content
...
}
card BoxMatrixCard for TstEmployee {
//Card content
...
}

``````

for

## Properties

Below is a list of properties that can be used to customize the control.

## Example

Below is an example of a box-matrix with multiple settings.

``````
//Example Code
//------------
page CompanyEmployees using TstCompanySet {
selector CompanySelector;
group CompanyGroup;
list EmployeesList(EmployeeArray);
}
list EmployeesList for TstEmployee {
boxmatrix EmployeesMatrix;
card EmployeeCard;
field Company;
field EmployeeId;
field FirstName;
field LastName;
field ColorCategory;
field PotentialCategory;
field PerformanceCategory;
}
boxmatrix EmployeesMatrix for TstEmployee {
description = "Displaying \${shownCount} of \${totalCount} employee";
card EmployeeCard;
count = [true];
initialview = AvatarView;
boxcolor ColorCategory;
boximage EmployeeImage {
emphasis Complementary2 = [PerformanceCategory = "Meets"];
emphasis Complementary8 = [PerformanceCategory = "Below"];
emphasis Complementary9 = [PerformanceCategory = "Exceeds" and PotentialCategory = "High"];
}
boxvalue FirstName;
xaxis PotentialCategory from TstPotential using TstPotentialSet {
label = "Potential";
map PotentialCategory;
}
yaxis PerformanceCategory from TstPerformance using TstPerformanceSet {
label = "Performance";
orderby = Ranking desc;
map PerformanceCategory;
}
}
card EmployeeCard for TstEmployee {
imagefield {
imagedata EmployeeImage;
}
field FirstName;
field LastName; 