State
Data displayed in an object-table
is controlled by its state. The objects provided below list all of the properties which can be safely accessed and mutated from JavaScript/TypeScript.
Advanced topic
Managing state is considered an advanced topic. In most cases an object-table
can be used effectively without directly managing state.
on-state-change
on-state-change
The function specified in on-state-change
is called when the state of the table is changed due to a UX/UI interaction such as changing to the next page or applying a column filter. The function should contain a $state
object which contains a simplified JavaScript/TypeScript object of the table's state.
<object-table on-state-change="$:tableStateChange($state)">
...
</object-table>
function tableStateChange(tableState){
// tableState contains the table's current state
console.log(JSON.stringify(tableState));
}
The internal structure of $state
is as follows:
interface State{
filters: {
/**
* Contains the payloads for the filters that are applied. Note that each type of filter is unique, and is identified
* using the `factory` variable
*/
[key: string]: {
factory: string;
/**
* current evaluated title of the column
*/
column: string;
}
};
/**
* the global search applied on the table
*/
search: string | null;
/**
* current limit applied to the table (might be user-adjustable in the future which is why it is available here)
*/
limit: number;
/**
* Current page of the table, starts at 1
*/
page: number;
/**
* All the columns being sorted, and in the sort order.
*/
sorting: Array<{
/**
* current evaluated title of the column
*/
column: string;
key: string;
type: 'asc' | 'desc' | 'none';
}>;
/**
* Which cell is currently in edit mode, or null otherwise
*/
editing: {
id: string;
column: string;
} | null;
/**
* An array of cells which are currently selected (which can include clusters of selected cells)
*/
selected: Array<{
id: string;
column: string;
}>;
/**
* Indicates if the table is in full screen mode or not
*/
fullscreen: boolean;
/**
* Callouts which are currently visible in the table.
*/
callouts: Array<{
message: string;
color: string;
id: string;
column: string;
}>
}
column properties: The state payload will in contain column
properties which refer to the current name of the column. This is provided as convenience data to make working with the state easier, but it is not used when initializing state since the value can change dynamically. Using the column
data to initialize the state is therefore considered unsafe and should not be relied on.
init-state
init-state
A table can initialize its internal state after the table is loaded using a similar structure as on-state-change
.
How init-state
differs from on-state-change
:
init-state
will ignorecolumn
fields (it only uses columnkey
information)
<object-table init-state="$:initState()">
...
</object-table>
function initState(){
/**
* @type ReturnState
*/
return { page: 1, scroll: 100, ... }
}
The internal structure of $state
is as follows:
interface ReturnState{
filters: {
/**
* Will contain the payloads for the filters that are applied. Note that each type of filter is unique, and is identified
* using the `factory` variable
*/
[key: string]: {
factory: string;
}
};
/**
* the global search applied on the table
*/
search: string | null;
/**
* current limit applied to the table (might be user-adjustable in the future which is why it is available here)
*/
limit: number;
/**
* Current page of the table, starts at 1
*/
page: number;
/**
* All the columns being sorted, and in the sort order.
*/
sorting: {
key: string;
type: 'asc' | 'desc' | 'none';
}[];
/**
* Indicates whether the table is in a full screen state or not
*/
fullscreen: boolean;
}
Changing the state from JavaScript/TypeScript
To change the state of the table using JavaScript/TypeScript, make use of the component.objectTable({ id: "my-id" }).setState({ ... })
method. This method requires an id=""
attribute to be present on the object-table
that matches the id
used in above component.objectTable()
.
For example:
function updateState(){
component.objectTable({ id: "my-table" }).setState({ page: 1, scroll: 100});
}
<object-table id="my-table">
...
</object-table>
When to use setState()
vs init-state=""
setState()
vs init-state=""
Since both of these methods do the same thing but in different parts of an application, it is important to understand why and when you should use one over the other. In most JourneyApps applications, init-state=""
is the easiest to use because it is called only once when the view loads. This is particularly useful when users navigate using a table, and when they return to the table they expect it to look exactly the same as before.
setState()
is useful when a developer needs to control or manipulate the table after the view has loaded. Actions such as changing the page and updating the select cell are events that should not fire on every update on a view, but rather when very specific events occur, such as pressing a particular button.
Last updated