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.
 |
| Grid views in runtime |
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.
To enable this feature the Allow Grid View Persistence property must be set to True.
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.
 |
| 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.
 |
| 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.
 |
| How to deletegrid view |
The UI for this feature may be customized using the Grid settings layout object.
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:
 |
| Persistence API |
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.
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.
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.
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.
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:
| Object Name |
WWInvoiceUsingGridViewById |
| Rules |
parm(&SavedViewId);
|
| Events |
Event Start
K2BTools.IntegrationProcedures.LoadGridView(&SavedViewId, !"", True, True)
WWInvoice()
EndEvent
|
| 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
|
K2BTools 13.0
|