Opening a Page with a Grid Component and Showing Selected Records

Description

A common requirement when building a grid is to have a hyperlink field in the grid that, when clicked, will open a second page. The second page contains a grid that is filtered based on parameters from the first page. These examples show how to do this. The URL that opens the second page has query parameters that contain one or more of the _filter, _order, and _link keywords. These keywords allow you to specify a filter, order and/or linking parameters for the grid in the target page.

The difference between filtering and linking is described below.

 Grid Based on .DBF Files

These examples show how to use the _filter and _order keywords.

  •  (a)

    CustomerInfo.A5w?customers_filter=customer_id="{customerID}"

  •  (b)

    CustomerInfo.A5w?customers_filter=firstname="{firstname}".and.lastname="{lastname}"&customers_order="{lastname}"

  •  (c)

    OrderInfo.A5w?orders_filter=orderid={orderid}&orders_order=quantity

 Grid Based on a SQL Data Source

These examples show how to use the _filter and _order keywords.

  •  (d)

    CustomerInfo.A5w?customers_filter=customer_id='{customerID}'

  •  (e)

    CustomerInfo.A5w?customers_filter=firstname='{firstname}' AND lastname='{lastname}'&customers_order={lastname}

  •  (f)

    OrderInfo.A5w?orders_filter=orderid={orderid}&orders_order=quantity

  •  (g)

    CustomerInfo.A5w?customers_link_1c=customer_id={customerID}

  •  (h)

    CustomerInfo.A5w?customers_link_1c=firstname={firstname}&customers_link_2c=lastname={lastname}

  •  (i)

    InvoiceItems.A5w?Items_link_1n=InvoiceNumber={Invno}

 Grid Based on .DBF Files

This example shows how to combine the _filter, _order, and _link keywords.

  •  (j)

    InvoiceItems.A5w?Items_link_1n=InvoiceNumber={Invno}&Items_Filter=quantity>10&Items_Order=quantity

 Comments

  1. Example (a) opens a page called CustomerInfo. This page has a grid called customers. Assuming that for a given row in the parent grid that the customerID field (and hence the {customerID} placeholder) is 00001, the filter that is applied to the records in the target grid is customer_id = "00001".

  2. The query parameter is constructed by prefixing the _filter, _order, or _link_ keyword with the component alias. In (a) for example, the CustomerInfo.a5w page contains a component whose alias is customers. If a page contains multiple grid components, you can specify a filter for each of the components on the page because each component has a unique alias.

  3. The component alias is not necessarily the name of the component as shown in the Web Projects Control Panel. The component alias is defined when you place the Grid on the .A5W page. If you are not sure what the component"s alias is, open the .A5W page, and switch to Source view. You will see Xbasic code like this: componentName = someValue. The component alias is someValue.

  4. In example (a), the value {customerID} is quoted because the syntax requirement for strings in filter expressions on .DBF tables is that values are double quoted. Contrast this with example (d), where the value is in single quotes because the syntax requirement for SQL is to single quote strings.

  5. In examples (c) and (f), the value is not quoted because the orderid field in these examples is assumed to be a numeric field.

  6. In example (b), the filter expression for a .DBF table has two clauses joined by the .AND. operator, whereas in example (e), the clauses (which are for SQL tables) are joined by the AND operator (no periods on either side of the word).

 Contrasting Filtering and Linking

With filtering, you can enter an arbitrarily complex filter expression using any functions that are understood by the database upon which the grid is based. An example for a .DBF. table:

Customer_Filter=left(name,1)<"d"

An example for a Microsoft Access table:

Customer_Filter=left(firstname,1)="J" AND left(lastname,1)="s"

With linking, you are limited to simple filters of the type fieldname=value. You can"t include functions in the link definition, although you can have as many fieldname=value pairs as you want. See example (h). With linking, you do not have to know anything about the syntax of the database you are querying. There is no difference between link query parameter for a .DBF table, or a SQL database. Note that in the link query parameter, character values are not quoted. (e.g. the query parameter in example (h) is:

firstname={firstname}

With linking, when the user enters data or edits data in the grid, the value(s) in the linking field(s) is automatically set to the value(s) specified in the query string. So new records that are added to the grid are automatically linked to grid on the source page because they automatically have their linking field(s) set to the value(s) specified in the query string. For example, if a page is opened with the URL:

invoice_items.a5w?items_link_1n=invoiceNumber=3

all records added to the Grid will automatically have their InvoiceNumber field set to 3. The user will not be able to manually override this by typing a different value into the InvoiceNumber field. In fact, the InvoiceNumber field does not even have to be displayed on the target grid.

Limitations

Web publishing applications only.

See Also