State persistence of grids

Official Content
This documentation is valid for:

This article explains different mechanisms to persist, or not, information related to the state of a grid.

State information such as pagination position, filtering, and sorting can be read, changed, and also handled automatically by the programs.

Several properties and methods allow this in design- or runtime.

Design-time configuration

Grid's Save State property 

This property allows choosing, at design-time, whether the programs should save and load the grid's session state automatically or not.

Programming state persistence

The following methods and properties can be used in Events of a Web Panel objectWeb Component object, and Web Master Panel object:

Grid's LoadSessionState method

This method allows loading the Grid's state from the session, programmatically.

Note: Variables that are the input for the grid's orders are only loaded if they are not empty

Grid's SaveSessionState method

This method allows saving the Grid's state to the session, programmatically.

What is saved:

  • Editable Variables that are the input for the grid's conditions and also are in the layout (eg.: &ClientId)
  • Variables that are the input for the grid's orders (eg.: &OrderedBy)

Grid's State property

The Grid State property can be accessed and changed at runtime. Its type is of an SDT, GeneXus.Common.GridState. You may use it to persist the state somewhere else; for example, to store it in the database, associated with your application user's preferences. The automatic assignment of the User Interface's state to the State property (and vice-versa) depends on the Save State Property.

Samples

Sample 1: Automation vs Flexibility

The following three cases are equivalent

A) Set Grid's Save State Property to True

B) Set Grid's Save State Property to False and write the following

Event Start
    //some other lines of code
    Grid.LoadSessionState()
EndEvent

Event Refresh
    Grid.SaveSessionState()
    // some other lines of code
EndEvent

Note: This is actually what the Work With Pattern writes by default.

C) Set Grid's Save State Property to False and write the following

Event Start
    // some other lines of code 
    Do 'LoadGridState'
EndEvent

Event Refresh
    Do 'SaveGridState'
    // some lines of code 
EndEvent

/*** Subroutines used to load and save the grid state. ***/

Sub 'LoadGridState'
    If (&HTTPRequest.Method = HttpMethod.Get)
        // Load grid state from session.
        &GridState.FromXml(&Session.Get(&PgmName + !"GridState"))

        If &GridState.FilterValues.Count >= 1
            &ClientName.FromString(&GridState.FilterValues.Item(1).Value)
        Endif

        If &GridState.CurrentPage > 0
            &GridPageCount = Grid.PageCount
            If (&GridPageCount > 0 and &GridPageCount < &GridState.CurrentPage)
                Grid.CurrentPage = &GridPageCount
            Else 
                Grid.CurrentPage = &GridState.CurrentPage
            Endif            
        Endif
    Endif    
EndSub

Sub 'SaveGridState'
    &GridState.FromXml(&Session.Get(&PgmName + !"GridState"))

    // Save grid state in session.
    &GridState.CurrentPage = Grid.CurrentPage
    &GridState.FilterValues.Clear()
    &GridStateFilterValue = new()
    &GridStateFilterValue.Value = &ClientName.ToString()
    &GridState.FilterValues.Add(&GridStateFilterValue)

    &Session.Set(&PgmName + !"GridState", &GridState.ToXml())
EndSub

Note: This is actually what the Work With Pattern wrote by default in GeneXus 16 Upgrade 11 or prior.

Sample 2: Persisting the Grid's state in the Database 

You can persist the state of the grid to places like the database or the cache, and load it from there afterward, using the State property.
The following two samples are equivalent:

A) Set Grid's Save State property to False and write the following

Event Start
    //some other lines of code
    Grid1.State = GridStateFromBD(&pgmname, !"Grid1") //Updates session and internal state
    Grid1.LoadSessionState() //Updates user interface
EndEvent
Event Refresh
    Grid1.SaveSessionState() //Reads user interface and updates session and internal state
    GridStateToDB(&pgmname, !"Grid1", Grid1.State) //Saves internal state to database
    //some other lines of code
EndEvent

B) Set Grid's Save State property to True and write the following

Event Start
    //some other lines of code
    Grid1.State = GridStateFromBD(&pgmname, !"Grid1") //Updates session and internal state
EndEvent
Event Refresh
   GridStateToDB(&pgmname, !"Grid1", Grid1.State) //Saves internal state to database
   //some other lines of code
EndEvent