Grids based on data providers

GridIcon | LayoutGrid | FreeStyleGridIcon Description

This page explains the general aspects of grids based on Data Providers. These nodes are a particular case of Grid node and Grid (SD) nodes, so bear in mind that this page contains information only about things specific to this type of grid. If you can't find information about a certain functionality that may be a generic grid functionality, check the Grid node or Grid (SD) page.

A grid is defined to be "based on a Data Provider" when it doesn't contain attributes and has a data provider set in the "Data Provider" property. To simplify the process of creating this type of grid, the "Add Grid From Data Provider" action was created. 

Data Providers allow the developer to encapsulate a navigation, to make a dataset independent from its source, and to have a better performance when retrieving this data. GeneXus documentation on Data Providers is available here. In a Data Provider the developer can specify any navigation. Ex: Breaks, obtaining data from external sources, etc.

If the Data Provider used in a grid defines parameters to control filtering, changing of the resulting order, or paging, K2BWebPanelDesigner will try to map its own variables relating to filters, orders and paging when invoking it.

Runtime appearance

The runtime appearance of a grid "based on a Data Provider" is equal to the appearance of a generic Grid node or  Grid (SD)

Properties

In this section only properties specific to grids based on Data Providers are shown. Generic properties for grids can be found on the generic grid documentation. 

Category Name Value
General DataProvider Indicates the data provider from which grid data is loaded

Events associated to this node

Ir order to understand  how Data Provider grids work, let's take a look at an example. Below, rules and code for a Data Provider named ProductDataProvider are shown.

DataProviderRulesExample DataProviderSourceExample
Rules Source

As you can see this dataprovider has parameters that allow changing the order of the returned items, filtering by the item's description, and manage paging.

PageNumber contains the index of the page that should be returned, and PageSize is the size of each page. This is acomplished inside the Data Provider by including the code shown at the top of the source code included above.

The output of this dataprovider is the SDT shown below.

DataProviderGridOutputSDT
Output SDT

In K2BWebPanelDesigner, the following structure was generated to include a grid based on this Data Provider.

WebPanelDesginerDataProviderGrid
Web Panel Designer

As you can see, the grid defined has variables, filters and orders. The load code K2BWebPanelDesigner generated for this grid is shown below.

GridDataProviderLoadCodeWithPagging
Data Provider Load Code

Data Provider Parameter Mapping

The most important part of this source code is when it invokes the DataProvider. Data Provider's parameters receive values based on the mappings defined below.

OrderBy Mapping:

To map K2BWebPanelDesigner's "OrderBy" variable with a Data Provider parameter, the first DataProvider parameter must be named "OrderBy" or  "OrderedBy".

Filter mapping:

For each parameter in the Data Provider's definition, K2BWebPanelDesigner adds a variable named "DP_Filter_{parameterName}_{GridName}" to the web panel. After that, K2BWebPanelDesigner will try to map this variable to one of the filters defined for the grid.

Automatically filter mapping occurs when:

  • Data Provider parameter has the name equal to a filter variable.
  • Data Provider parameter has the name equal to a filter variable plus a "_Filter" literal.

In this case, before the invocation K2BWebPanelDesigner automatically matches the "DP_Filter_ProductDescription_GridGetProducts" with "&ProductDescription_Filter" filter variable.

In the event of not being able to automatically map a parameter a subroutine named "U_PrepareDataProvider({GridName})"  is called before data provider invocation in order to manually map Data Provider parameters to their values.

Paging mapping:

K2BWebPanelDesigner determines that a Data Provide has built-in paging when one of the following occurs:

Option 1: Available from K2BTools 10 onwards

The DataProvider's parm contains:

  • A parameter called "&Count".
  • A parameter called "&Skip".

Option 2: Deprecated from K2BTools 10 onwards (only supported in Web Panel Designer)

The DataProvider's parm follows this rules:

  • The next to last parameter is called "&PageNumber".
  • The last parameter is called "&PageSize".

Data load

After invoking the Data Provider, the code generated by K2BWebPanelDesigner iterates through the resulting SDT and matches each K2BWebPanelDesigner variable with its corresponding field. 

To automatically match a variable to a field from the SDT the following rules must be followed:

  • Variable must have "Load From Data Provider" property set to true.
  • Variable's name must be equal to the name of the desired field in the sdt.

You can load other variables extending the user subroutine U_LoadRowVars{InternalName}

The load code depends upon wether the dataprovider has paging or not. In the example above  a grid is loaded from a Data Provider that manages paging.

Let's take a look at another case, using a Data Provider that does not handle paging, as shown below.

DataProviderNoPagingRulesExample DataProviderNoPagingSourceExample
Rules Source

The generated Load Code in this case is:

GridDataProviderLoadCodeNoPagging
Data Provider Load Code

In this case, paging is managed by K2BWebPanelDesigner, who retrieves all records but only loads the ones specified in the current page. 

The &LoadRow_{InternalName} variable can be used  to prevent a row from being loaded.

Variables associated to this node

In the following table, {InternalName} should be replaced with the value of the property "Name (Id)" of the grid. Only subroutines specific to this type of grid are shown. To see generic grid subroutines, check the Grid node page.

Name Description
'I_LoadCount_{InternalName}' Number of records loaded. Should not be modified by the developer.
'HasNextPage_{InternalName}' Set to true means that grid has a next page, false if it's the last page. Should not be modified by the developer.
'LoadRow_{InternalName}' This variable determines if the current row should be loaded. Can be changed by the developer inside 'U_LoadRowsVar{InternalName}' event. This variable is not avaiable in grids based on Data Providers that handle paging.
'DP_Filter_{ParameterName}_{InternalName}' This variable is associated with a dataprovider parameter. The variable value can be changed by the developer in order to decide what value the parameter should have when invoking the Data Provider. The purpose of this variable is to map K2BWebPanelDesigner filters with the Data Provider's parameters. This mapping can be done by the developper in the U_PrepareDataProvider{InternalName} subroutine. K2BWebPanelDesigner will try to automatically map filters with Data Provider parameters. For more information see "Data Provider Parameter Mapping" above.

User subroutines associated to this node

In the following table, {InternalName} should be replaced with the value of the property "Name (Id)" of the grid. Only subroutines specific to this type of grid are shown. To see generic grid subroutines, check the Grid node page.

Name Moment of execution Detailed description and possible uses
'U_LoadRowVars({InternalName})' This subroutine is invoked inside load event.

The prupose of this subroutine is to load grid variables or actions. Also in grids based on Data Providers which do not manage paging it can be used to determine whether to load a record or not. For this prupose a global variable named &LoadRow_Grid{InternalName} can be set to false ir order not to load that record.

 

'U_PrepareDataProvider({InternalName})' This subroutine is invoked inside load event when there are no records to load.

The prupose of this subroutine is to map the Data Provider's parameters to its desired values. The most commun use is to map these with K2BWebPanelDesigner filter variables.