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

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>

main.js

function tableStateChange(tableState){
    // tableState contains the table's current state
    console.log(JSON.stringify(tableState));
}

The internal structure of $state is as follows:

The validationErrors field is available from Runtime 4.90.9+. It is handled internally and therefore cannot be set by the developer via the setState or init-state logic.

main.ts

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;
  }>
  /**
   * Validation errors currently present on the table
   * (Available from Runtime 4.90.9+)
   */  
  validationErrors: Array<{
    message: 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

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 ignore column fields (it only uses column key information)

<object-table init-state="$:initState()">
  ...
</object-table>

main.ts

function initState(){
    /**
     * @type ReturnState
     */ 
    return { page: 1, scroll: 100, ... }
}

The internal structure of $state is as follows:

main.ts

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;
}

Note: The validationErrors field is handled internally and cannot be set by the developer.

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().

Note: The setState() method takes the exact same payload as init-state="".

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=""

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.

Tip: Implementing setState() can slow down your view if done frequently. Use it only where init-state="" is not feasible.

---