Grid views

Grids can be used for multiple purposes. Say, for example, you develop a Subscriber grid with several columns and filters.

The application user may use that grid for different purposes by changing filters and orders and even the columns shown:

  • Subscribers with a red balance ordered by balance amount: To contact them to request payment.
  • Disconnected subscriptions in reverse cancelation date order: To try to renew subscriptions.
  • Middle age subscribers having children: To promote a given plan

Each grid usage is called a view.

Defining, changing and switching among views should be easy and configurable to help the application user. It also helps development as, sometimes, a single object can be developed to satisfy several user’s needs.

The grid views feature lets the application user to save and restore grid views (i.e. filters, order and columns). This feature can be added to any grid.

GridViewsRuntime
Grid views in runtime

Grid view definition

A grid view is defined by:

  • The values set in the grid filters.
  • The selected order.
  • The visible columns (when the grid is not a free style grid).

Grid views are identified by a name specified by the user.

Enabling grid view persistence

To enable this feature the Allow Grid View Persistence property must be set to True.

How it works at runtime

To define a view, the user must first set the filters, orders, and visible columns as desired for the view. Then, the user should go to the grid settings menu and grid views section inside it. There, it should enter a name for the view and click the save button.

GridViewsSaveGridView
How to save a grid view

To use a grid view, the user must open the grid settings menu and click on the name of the grid view.

GridViewsRestoreGridView
How to select grid view

To delete a view, the user must open the grid settings menu and click on the delete action next to the grid view name.

GridViewsDeleteGridView
How to deletegrid view

UI Customization

The UI for this feature may be customized using the Grid settings layout object.

Grid view persistence

The feature’s default persistence implementation saves the grid views to the web session and uses the User Preferences module to save them to the database.

The developer can also implement a custom persistence solution. To do so, the procedures implementing this API must be updated.

Those procedures are imported automatically by K2BTools, and initially contain a simple implementation that stores the grid views in the web session.

The developer may also include the User preference persistence module in the KB. This module implements this API storing the views in the database.

The procedures in this API are:

GridViewsAPIObjects
Persistence API

SaveCurrentGridView

Parameters (in):

  • ProgramName: The name of the web panel that contains the grid.
  • GridName: The name of the grid inside the web panel.
  • SessionStateParameter: This value is used to store the grid state in sub work withs, where the state is independent for each parent entity instance. Use this parameter to load the grid state prior to saving.
  • SavedGridViewName: The name chosen by the user for this grid view.
  • SaveGridState: Determines if the grid state is available and should be saved.
  • SaveColumns: Determines if columns may be selected in runtime and should be saved.

Expected behaviour:
The program should save the current grid view using the name specified in the “SavedGridViewName” parameter. The saved view should include the program and grid names, as in later calls the API must return the saved views for those values.

To get the current view the procedure should call the “K2BLoadGridState” and “K2BLoadGridColumns” procedures.

If the “SaveGridState” or the “SaveColumns” parameters are set to False, the grid state or the column state should be ignored respectively.

The rest of the API assumes that the grid view can be identified by a number, take this into account when storing the view.

GetGridViews

Parameters (in):

  • ProgramName: The name of the web panel that contains the grid.
  • GridName: The name of the grid inside the web panel.

Parameters (out):

  • SavedGridViews: a collection of the SavedGridViewSDT datatype, representing the saved views.

Expected behaviour:
The program should load the information about the views saved by the user for that program and grid name.

DeleteGridView

Parameter (in):

  • SavedViewId: The id of the view that should be deleted.

Expected behaviour:
If a grid view with that id exists it should be deleted.

LoadGridView

Parameters (in):

  • SavedViewId: The id of the view that should be loaded.
  • SessionStateParameter: This value is used to store the grid state in sub work withs, where the state is independent for each parent entity instance. Use this parameter to set the grid state.
  • LoadGridState: Determines if the grid state is available and should be loaded.
  • LoadColumns: Determines if columns may be selected in runtime and should be loaded.

Expected behaviour:
This program should restore the grid view identified by its Id (the first parameter). To restore the view, use the K2BSaveGridState and the K2BSaveGridColumns procedures. These procedures must be called only if the LoadGridState and LoadGridColumns indicate that those states must be loaded.

Note that grid views may be saved in one version of the application and restored in another. This may lead to differences in the grid’s properties. For example, the grid may have had the Runtime Column Selection feature enabled in the first version and disabled in the second one. Because of this, the grid state and the columns state must be loaded only if the grid view contains a definition for that state and the corresponding parameter indicates that the grid supports it.

Calling an object using a predefined view

In some cases application users want links to enter a web panel with a preselected grid view. This may be useful, for example, if users want a specific view to be callable from the application's menu.

To create these links the developer may create a web panel that receives the grid view's id or name. That web panel should load the grid view, and call the web panel containing the grid.

For example, to call a web panel called WWInvoice using a predefined grid view the developer can define these web panels:

Call using a view id.

Object Name WWInvoiceUsingGridViewById
Rules
parm(&SavedViewId);
Events
Event Start
   K2BTools.IntegrationProcedures.LoadGridView(&SavedViewId, !"", True, True)
   WWInvoice()
EndEvent

Call using a view name

Object Name WWInvoiceUsingGridViewByName
Rules
parm(&SavedViewName);
Events
Event Start
    LoadGridViewByName(!"WWInvoice", !"Grid", &SavedViewName, &Messages, &Success)
    If &Success
        WWInvoice()
    Else
        For &Message in &Messages
            K2BToolsMsg(&Message.Description, K2BToolsMessageType.Error)
            Log.Error(&Message.Description, !"WWInvoiceUsingViewName")
        EndFor
    EndIf
   WWInvoice.Call()
EndEvent

The above procedure (LoadGridViewByName) is available as of K2BTools 14.0. If you are working with earlier versions follow the example below.

Object Name WWInvoiceUsingGridViewByName
Rules
parm(&SavedViewName);
Events
Event Start
   K2BTools.IntegrationProcedures.GetGridViews(!"WWInvoice", !"Grid", &SavedGridViewsSDT)

   For &SavedGridViewSDT in &SavedGridViewsSDT
      If &SavedGridViewSDT.ViewName = &SavedViewName
         K2BTools.IntegrationProcedures.LoadGridView(&SavedGridViewSDT.Id, !"", True, True)
         Exit
      EndIf
   EndFor
   WWInvoice()
EndEvent

Availability

K2BTools 13.0