Tutorial 47: How to Save, Restore Grid State

This tutorial explains how to save the current state of a Grid component and restore it at a later point in time. This feature can be used to help users to store and later re-run the custom reports they prepare using the built-in features of the Grid component such as resizing, locking and moving Grid columns.

The Application

To demonstrate the feature, create an application named “GridStateDemo” and make “HR” its datasource schema. Add the application a Datasource Definition based on the “Employees” table. Enable all the features like filtering, functions, column show/hide, locking, moving columns, resizing and sorting in the Grid.

Next, edit the mainPanel and create a Grid named “EmpGrid” that is bound to the “EMPLOYEES1″ datasource and shows the First Name, Last Name, Salary, Hire Date and Email fields.

Add a button labeled “Save Grid State” and another one labeled “Restore Last Saved Grid State” to the mainPanel.

Create two actions named “saveGridState” and “restoreGridState” with the following PL/SQL code:

procedure saveGridState is
  v_gridState_cl clob;
begin
  v_gridState_cl:=api_component.getgridstate('mainPanel.EmpGrid');
  api_session.add('lastSavedGridState',v_gridState_cl);
end;
procedure restoreGridState is
  v_gridState_cl clob;
begin
  v_gridState_cl:=api_session.getvaluecl('lastSavedGridState');
  api_component.setgridstate('mainPanel.EmpGrid',v_gridState_cl);
end;

Call these actions from the appropriate button events.

The final Panel XML markup looks like this:

<panel>
  <borderLayout>
    <cell docking="North" height="40">
      <button label="Save Grid State">
        <events>
          <buttonPress action="saveGridState"/>
        </events>
      </button>
    </cell>
    <cell docking="Center">
      <grid name="EmpGrid" dataSource="EMPLOYEES1" enableColumnFilter="Y"
             enableColumnFunctions="Y" enableColumnHide="Y" enableColumnLock="Y"
             enableColumnMove="Y" enableColumnResize="Y" enableColumnSort="Y">
        <column headerLabel="First Name">
          <textField column="FIRST_NAME"/>
        </column>
        <column headerLabel="Last Name">
          <textField column="LAST_NAME"/>
        </column>
        <column headerLabel="Salary">
          <textField column="SALARY"/>
        </column>
        <column headerLabel="Hire Date">
          <dateField column="HIRE_DATE"/>
        </column>
        <column headerLabel="Email">
          <textField column="EMAIL"/>
        </column>
      </grid>
    </cell>
    <cell docking="South" height="40">
      <button label="Restore Last Saved Grid State">
        <events>
          <buttonPress action="restoreGridState"/>
        </events>
      </button>
    </cell>
  </borderLayout>
</panel>

The Demo

Run the application. Edit the Grid by moving columns, applying functions, sorting the data etc…

At any point, click the “Save Grid State” button to capture the current state of the Grid. Next, continue modifying the Grid. Note that the Grid will go back to the state you saved when you click the “Restore Last Saved Grid State” button.

Final Words

The api_component.getGridState API returns a CLOB which contains an XML markup that defines the grid’s state. You can edit this XML using the PL/SQL XML API’s. This way, you can remove the parts of the state that you do not want to save or add new state information to the XML.

The api_component.setGridState API by default queries the datasource the grid is bound to. You can change this behavior by setting the third parameter of the API in_reloaddata_yn to N.

This sample application uses session variables to save and restore the Grid state to keep the tutorial simple and short. The state information of a Grid can similarly be stored in a table along with a user name to give a user the ability to save and run the custom reports he prepares.