A Column transform means taking a value of a cell and transforming (without mutating the raw data).
There are 2 ways to transform the data:
This is just cell templating:
<div *pblNgridCellTypeDef="'numberTimes100'; value as value; row as row; col as col">
{{ value * 100 }}
</div>
We transform by providing a transformation function to the transform
property in the column definitions:
export interface PblColumnDefinition extends PblBaseColumnDefinition {
transform?: (value: any, row?: any, col?: PblColumn) => any;
}
Function parameters:
- value is the value of the cell your are transforming.
- row is the entire row.
- col is the
PblColumn
instance.
const PERCENT_TO_INTEGER = (value: any) => value * 100;
const COLUMNS = columnFactory()
.table(
{ prop: 'percent', transform: PERCENT_TO_INTEGER },
)
.build();
Never call
col.getValue(row)
from a
transform
function as it will loop indefinitely (read more below...)
When to use
When transforming, choosing how might be confusing. Template transformation is surely the easiest option but the necessarily the best one:
- Templates are slower than functions
- Template composition is more difficult
- Templates only live in the renderer and can not be used elsewhere.
That is,
- Rendering a template is more costly than invoking a method
- In most cases a template might already exists for the cell that you would want to use, how will you combine the 2?
- Templates are UI only, for example, they will not effect exporting (e.g. excel) but
transform
functions will
Use templates for UI related transformation (e.g. formatting, image from string, etc...).
As a general rule of thumb, if you can transform something using a function, use a function transformer and not a template transformer.
To render a cell template, the grid will first extract the value for the cell and provide it to the template.
For that it will use the column instance (col) and row instance (row) to get the value:
const value = col.getValue(row);
It will take the value and pass it to the template, along with the column instance and the row instance.
PblColumn.getValue
is, by the way, a public method that you can use if you have a column instance and a row object
Never call
PblColumn.getValue
inside a
transform
function!!!
Inside PblColumn.getValue
, the grid will:
- Extract the value from the row using the property this column points to
- If a
transform
function is provided
- Call the
transform
function with the extracted value, the column instance and row instance
- Return the value return from the
transform
function
- Else, return the extracted value
So the order is first calling the transform
function (if provided) and then rendering the cell template.
Because PblColumn.getValue
is calling the transform
function internally, providing the value, row and column,
it is possible to invoke col.getValue(row)
again from within the transform
function, which will cause
a recursive loop until an overflow exception is throw, please avoid it