REST Grid Widget

This topic describes REST Grid widget settings. For details on using the widget, refer to Using the REST Grid Widget.

General Tab

Field Description
Name Type the name by which the widget is uniquely identified. No other widget or control on this form can have the same name.
Caption Type the text to appear in the title bar above the widget.

If you leave this field blank, the widget will not have a title bar.

URL Displays a URL to a configured REST service. If none has been configured, click Configure URL. Complete the dialog box that opens as described in REST Service Configuration Dialog Box.

Click the Clear button to remove the URL and start over.

Paging Select paging options to include buttons at the top of the widget that let users navigate between pages in the result set. Select from the following paging options:

Off: No buttons for paging.

On (Server-Side): Paging is done on the server side, so that there is never more data returned to users' machines than they are currently viewing. If this option is selected, the configured REST service must support paging and users cannot click on column headers to sort data in ascending or descending order. For information on configuring the REST service to support this, refer to Query Tab Parameters/Values entry.

On (Client-Side): Paging is done on the client side, and the returned results are stored in the browser. When you select this option, the Results per page option is also enabled, where you specify the number of records to return per page. For example, if Results per page is set to 10, at runtime the REST service might return 100 records to the browser, and user would use the paging buttons to page through 10 at a time.

Note: When using the client-side option, you must properly filter your data before returning it so that the number of results returned is not so large that it impacts browser performance.
Options Border: Select this check box to draw a thin line around the widget.

Scroll bars: Select this check box to include scroll bars in the widget. This provides more content than the allotted space.

Include lower page bar: Select this check box if you want to include paging buttons at both the top and the bottom of the widget.

Description Type an optional description of the widget.
Note: This widget uses the grid style. You can customize the colors and text in the Styles Editor.

Query Tab

Use this tab to override the parameters and values for the REST service.

Field Description
URL Indicates the base REST URL. During deployment, the endpoint is generated using this URL.
Parameters/Values

URL parameters are listed below the URL. Values can be static values or be bound to other field or control values.

Important:

If Server-Side paging is selected on the General tab, you must map a parameter to keep track of the paging to the RESTGridWidget._currentPage or RESTGridWidget._currentIndex parameter.

Otherwise, during validation, you receive a warning message, and when the user pages, the previous results are displayed. (See Using the String Builder Tool for instructions.)

This parameter mapping is not necessary for Client-Side paging.

Result Tab

Note: During widget configuration, you will receive a warning message if the amount of data in the result set exceeds 100 rows. The message includes ways to limit the result set.
Field Description
Render as
  • Grid: Select this option if you want the search results to be presented as an HTML table in which each row contains one returned item, with a titled column for each data element you select under Grid columns.
  • Tiles: Select this option if you want the search results to be presented as an HTML table in which each table cell contains all the content for a single item, and each row contains the number of cells you specify in the per row list.
    N per row: This list is enabled if you selected the Tiles option. Specify the number of tiles, or table cells, that you want on each row. For example, if you specify 2, there are will be five rows in the initial presentation (assuming that there are at least ten items to be returned).
    Note: If you specify a number other than 1, 2, 5, or 10 (that is, a number evenly divisible by ten), the last row will contain fewer tiles than the other rows.

Enable row selection: Lets users populate a control such as a text box with the data from a selected row. If this check box is cleared, the Columns the grid will display table contains an additional Action on click column.

Enable multi-selection: Lets users select multiple rows in the REST grid by pressing Ctrl+click or Shift+click. If you map this to a single text field, the field will be populated with a comma-separated list (for example, "value1,value2,value3").

Autoselect first row: Select this option to automatically select the first row of the grid on refresh.

Output: Available Data Shows the data elements you can include in the result set. Bold nodes indicate valid elements that you can move to the Grid columns or to the Tile content pane.

As you type in the box above the list, SBM Composer filters the list to show only the data elements with names that contain the characters you typed.

Grid Columns
  • Value

    Shows the data elements from the widget that you can include in the result set.

  • Caption

    Accept the default column name or type another name.

  • Display as

    Select Text, Url, or Image.

  • Visibility

    Select Visible, Always Visible, Hidden, or Always Hidden.

    Columns set to Visible or Hidden are available for end users to show or hide at runtime. (To show or hide columns, the end users click the down arrow on the right side of the column headings and select or deselect check boxes beside the available columns. The columns they choose to show or hide will persist when they view the widget instance again in the same browser. They can click Show All to select all columns for display.)

    Columns set to Always Hidden are not selectable to display, but the data is still available to be mapped as input to other fields or used in JavaScript code.

    Columns set to Always Visible cannot be removed from the display by end users.

The Action on click column is not available if you are binding to widget data, because when you bind to widget data, there are other links, and users would find it difficult to determine what they are clicking.

Tile Content Type or paste the content for each tile in the result set.

Alternatively, you can use the string builder tool to insert references to table fields and form controls.

For example, you could use the following code to put a small HTML table in each tile:

<table width='100%'>
  <tr>
    <td rowspan='2' width='80px'>{SmallImage}</td>
    <td>{ItemAttributes.Title}</td>
  </tr>
  <tr>
    <td>{OfferSummary.LowestNewPrice}</td>
  </tr>
</table>

Refresh Tab

See Widget Refresh Tab.