`type_="scroll"`

Using <widget class_="grid" type_="scroll"> produces a grid widget that can scroll smoothly through the rows of data in a table.

Syntax

<dynamic>
    <widget class_="grid" type_="scroll">
        [1010data_QUERY]
    </widget>
</dynamic>

The [1010data_QUERY] may be specified between the opening and closing tags of the <widget>. The results of the query provide data for the <widget> to display.

Attributes for `type_="scroll"`

The attributes in this list are specific to <widget class_="grid" type_="scroll">. See class_="grid" for attributes common to all grid widgets.

allowswitchview_

Accepts an integer value of 1 or 0 that specifies whether or not to provide an item in the right-click context menu that allows the user to switch to a one row view.

The default value is 1.

(Available as of version 10.12)

cellmenurangevalue_

Accepts a package representing the current state of the user-selected section of a grid, allowing users to highlight and store multiple rows of a grid. The package contains the following:

cols: A list of column names of the selected columns
rowmin: The (numeric, 1-indexed) index of the minimum row in the selection
rowmax: The maximum row in the selection

(Available as of version 14.00)

cellmenuselector_

When the user clicks an item from a customized right-click cell context menu, the column name of the associated cell is stored in the dynamic variable specified by the cellmenuselector_ attribute.

The variable must be declared in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="">).

cellmenuvalue_

When the user clicks an item from a customized right-click cell context menu, the value in the associated cell is stored in the dynamic variable specified by the cellmenuvalue_ attribute.

The variable must be declared in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="">).

clickablecolhead_

Accepts a comma-separated list of column names. Column headers of the columns specified to clickablecolhead_ are clickable. When any of these column headers are clicked, <do> clauses with an onsubmit_ attribute whose value matches any of the values in the list specified to submitcol_ are executed.

If clickablecolhead_="*", all of the column headers are clickable.

colbuffer_

Accepts an integer value that specifies the number of columns to the left and right of the current view that should be kept in memory for scrolling left and right.

The default value is 4.

colcopylimit_

Allows the user to select a value in the grid and right-click a context menu with a Copy option. The Copy submenu allows you to copy the entire column, as long as the values in the column are under the specified limit. The columns are copied with a newline column separator. This attribute accepts an integer value.

The default value is 1, meaning that the user cannot copy more than one column at a time.

(Available as of version 12.30)

coltooltips_

Accepts a boolean value determining whether tooltips are enabled or disabled for column headers.

When coltooltips_="1", tooltips are enabled. The default tooltip displays Name and Type metadata.

When coltooltips_="0", tooltips are disabled.

The default value is 0.

(Available as of version 12.11)

Alternatively, you can provide coltooltips_ with a comma-separated list of any combination of the following strings representing metadata fields:

name
label
type
origin
desc

Fields appear in the order you specify in the list.

(Available as of version 14.25)

colwidthref_

Accepts an integer value that specifies how many rows should be used to calculate the width of a column if no width is specified for the column or the data it contains.

The default is 3.

colwidthdef_

When colwidthref_="0", accepts an integer value that specifies the width of all columns.

The default value is 10.

(Available as of version 10.10)

editcols_

editcols_="list,of,cols" limits editing of cells to specific columns. An empty list/string (the default value) means that you can edit any column.

(Available as of version 13.33)

editvalue_

editvalue_="@var" enables editing of any cell in the grid, unless editcols_ is specified to limit editing to specific columns. When a cell's value is changed, @var is set to a package with the keys row, col, type, and value. The values at each index in the lists specify the row number, the column name, the column type, and the value that the cell was changed to respectively.

(Available as of version 12.22)

height_

Accepts either an integer value describing the fixed height of the container or a percentage value relative to the parent container.

If the height_ attribute is specified as a percentage value (e.g., height_="50%"), the scroll grid will initially render with a height corresponding to the specified value. If the browser window is resized, the scroll grid will resize proportionally. If the scroll grid is contained in a splitter layout, it will initially render correctly but will not resize if the splitter layout is resized.

(Available as of version 10.11)

initview_

Specifies how the grid widget renders when initialized.

Valid values are:

multirows: Display multiple rows when initially rendered
onerow: Only display the first row when initially rendered

The default value is multirows.

(Available as of version 10.12)

naorder_

Specifies where to place N/A values in relation to valid values after a sort.

Valid values are:

first: Places N/A values before valid values after a sort
last: Places N/A values after valid values after a sort

Works with the postsort_ attribute.

negativecolor_

If set to a non-empty string, specifies a CSS color to apply as a foreground color to any cells of the grid which contain data in the form of a negative number.

(Available as of version 15.23)

pastable_

If set to 1, enables pasting of tabular data into the standard grid. Data is pasted when the cell is selected in the grid and the system paste shortcut (Ctrl+V, Command+V, or the Paste command in the browser menu) is used.

Specify one or more of the following variable bindings with pastable_:

editvalue_: Set editvalue_="@evar". Upon a paste event, if @evar is bound, it is set to a package with the keys row (row number), col (column name), type (column type), and value (the new value for the cell at that row and column).
pastevalue_: Set pastevalue_="@pvar". Similar to @var, @pvar is set to a package with the keys row (row number), col (name of the cell), and tablevalue (the table value with the parsed data in its entirety).
If either editvalue_= or pastevalue_= is specified and the pasted text cannot be parsed into values corresponding to the appropriate column types, or cannot be parsed as a delimiter-separated table at all (such as unequal numbers of delimiters across lines), then @evar and/or @pvar are not set.
rawpastevalue_: Set rawpastevalue_="@rvar". If @rvar is bound, it receives a package with the keys row (row number), col (name of the cell), and text (raw text that was pasted).
pastefailvalue_: Set pastefailvalue_="@fvar". If @fvar is bound and the pasted text cannot be parsed as a delimiter-separated table, it is set to the text of an error message. If the paste is successful, @fvar is set to an empty string.
(Available as of version 12.34)

pinnedrowbgcolor_

Specifies the background color of the pinned rows.

(Available as of version 12.33)

pinnedrows_

Specifies a comma-separated list of row numbers to pin at the top of the data area of the grid and remain there even when the grid is scrolled vertically.

The attribute may also be specified as pinnedrows_="[BOOLEAN_EXPRESSION]". Rows where the [BOOLEAN_EXPRESSION] is true are pinned. Note that pinnedrows_="1" is treated as a row number, not "pin all rows."

The optional attribute pinnedrowbgcolor_ can be used to change the background color of the pinned rows.

(Available as of version 12.33)

pkgcolvalue_

When the user clicks the header of a column specified in the clickablecolhead_ attribute, information about that column is stored as a package in the dynamic variable associated with the pkgcolvalue_ attribute.

The package consists of the following attributes:

name: The name of the column
label: The label of the column
type: The data type of the column
description: The column description
format: The column format

The variable must be declared as a package in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="{pkg(;)}">).

pkgstatevalue_

Accepts a dynamic variable that stores state information related to the grid as key/value pairs in a package. The variable must be declared as a package in the opening <dynamic> tag of the QuickApp in which the grid widget exists. It should be initialized as

<dynamic
              var_name="{pkg('startrowvalue' 'startcolvalue' 'sortcols'
              'sortdirs' 'reordercols';'' '' lst() lst() lst())}">

The dynamic variable associated with pkgstatevalue_ contains five attributes related to the grid widget's state:

startrowvalue

An integer that represents the number of the row that is at the top of the grid after it has been scrolled vertically.

This can also be set to a particular value to position the grid widget to a particular row number.

startcolvalue

An integer that represents the index of the column that is at the left-most position in the grid after it has been scrolled horizontally. The value corresponds to the index of the column relative to all the scrollable columns in the grid.

This can also be set to a particular value to position the grid widget to a particular column.

sortcols

A list-value that contains a list of the columns that have been sorted.

Each time the table is sorted, the column name of the sort column is appended to this list-value.

The direction in which the column has been sorted is appended to the sortdirs list-value.

sortdirs

A list-value that contains the sort directions for each of the columns in the sortcols list.

Each time the table is sorted, the direction in which the column is sorted is appended to this list-value.

reordercols

A list-value that contains a list of the indices of the columns in the order after they have been rearranged.

The indices are relative to the original position of the columns.

The only works when reorderable_="1".

If the value of any of these attributes are changed, the grid widget will update itself.

postsort_

Accepts a comma-separated list of column names. Sort operations on the columns specified will be applied after a sort is performed on the grid.

Sorting direction is up, and sorts are applied to columns in postsort_ in the ordered the are specified (first column is first sort).

If naorder_ is specified, N/A values will be placed either before or after valid values.

reordercols_

When reorderable_="1", the order of the columns after they have been rearranged is stored in the dynamic variable specified by the reordercols_ attribute. The value of this dynamic variable is a list of indices relative to the original position of the columns.

The variable must be declared as a list-value in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="{lst()}">).

rowbuffer_

Accepts an integer value that specifies the number of rows above and below the current grid that should be kept in memory for scrolling up and down.

The default value is 12.

rowcopylimit_

Allows the user to select a value in the grid and right-click a context menu with a Copy option. The Copy submenu allows you to copy the entire row, as long as the values in the row are under the specified limit. The row is copied with a tab character between values. This attribute accepts an integer value.

The default value is 1, meaning that the user cannot copy more than one row at a time.

(Available as of version 12.30)

span_headers_

Accepts an integer value that specifies the number of levels of spanned headers to display across columns resulting from a tabulation. The spanned headers are created from the common portions of multi-line label attributes of <tcol> elements.

The default value is 0.

submitcol_

Accepts a comma-separated list of text values.

When a clickable column header is clicked, <do> clauses with an onsubmit_ attribute whose value matches any of the values in the list specified to submitcol_ are executed. Clickable column headers are specified by the clickablecolhead_ attribute.

tablecopylimit_

Allows the user to select a rectangular area in the grid (highlighted with an orange rectangle) and right-click a context menu with a Copy option. The Copy submenu allows you to copy the selected values as formatted or unformatted values. The selected values are copied with the tab character separating fields within a row and the newline character separating rows.

The default value is 1, meaning that the user cannot copy more than one cell at a time.

(Available as of version 12.30)

width_

Accepts either an integer value describing the fixed width of the container or a percentage value relative to the parent container.

If the width_ attribute is specified as a percentage value (e.g., width_="50%"), the scroll grid will initially render with a width corresponding to the specified value. If the browser window is resized, the scroll grid will resize proportionally. If the scroll grid is contained in a splitter layout, it will initially render correctly but will not resize if the splitter layout is resized.

(Available as of version 10.11)

Example: Scrolling grid

In the following example a simple selection query is executed within the <widget> element. Note that the <widget> is contained within a <dynamic> element. This example also utilizes the clickable_ option, so two variables are defined in the <dynamic> element. When a value in the Transaction ID column is clicked, the value will be stored in the @val variable, and the column name will stored in the @col variable.

<dynamic col="" val="">
  <widget class_="grid" type_="scroll" base_="pub.demo.retail.item" 
   label_="Store Selection" rowcol_="1" clickable_="transid" 
   value_="@val" selector_="@col">
    <sel value="store=1"/>
  </widget>
</dynamic>

The results appear as follows:

Example: Clickable column heads

<base table="pub.doc.retail.store"/>
<dynamic pkgcolval="{pkg(;)}" foocnt="0" barcnt="0" bazcnt="0">
  <do onsubmit_="foo">
    <set foocnt="{1+@foocnt}"/>
  </do>
  <do onsubmit_="bar">
    <set barcnt="{1+@barcnt}"/>
  </do>
  <do onsubmit_="baz">
    <set bazcnt="{1+@bazcnt}"/>
  </do>
  <layout>
    <widget class_="grid" type_="scroll" clickablecolhead_="state,zip" 
     clickable_="store" pkgcolvalue_="@pkgcolval" 
     submitcol_="foo,bar" submit_="baz"/>
    <widget class_="grid" base_="default.lonely" sortable_="">
      <foreach col="{pkg_names(@pkgcolval)}">
        <willbe name="{@col}" value="'{@pkgcolval[@col]}'"/>
      </foreach>
    </widget>
    <widget class_="text" text_="Submit col foo: {@foocnt}"/>
    <widget class_="text" text_="Submit col bar: {@barcnt}"/>
    <widget class_="text" text_="Submit row: {@bazcnt}"/>
  </layout>
</dynamic>

Example: Creating headers that span across multiple columns

The following example creates a grid widget that presents a tabulation of the data in pub.demo.weather.hourly90. The grid widget uses the span_headers_ attribute to display headers that span across groups of related columns. The spanned headers are created from the common portions of multi-line label attributes of <tcol> elements. The value assigned to span_headers_ determines the number of levels of the spanned headers.

<dynamic>
  <layout>
    <widget class_="grid" type_="scroll" 
     base_="pub.demo.weather.hourly90" 
     width_="1050" height_="300" total_="1" 
     span_headers_="2">
      <sel value="tsky<>99"/>
      <sel value="temp<>999.9"/>
      <sel value="hum<>999"/>
      <sel value="vis<>9999.9"/>
      <tabu label="Tabulation on 1990 Weather Data" breaks="id,date,hour">
        <tcol source="temp" fun="avg" 
         label="Average Dry Bulb Temp`(Celsius)"/>
        <tcol source="temp" fun="RGavg" 
         label="Average Dry Bulb Temp`(Celsius)`as Rank"/>
        <tcol source="hum" fun="avg" 
         label="Average Relative Humidity`(%)"/>
        <tcol source="hum" fun="RGavg" 
         label="Average Relative Humidity`(%)`as Rank"/>
        <tcol source="wdir" fun="avg" 
         label="Average Wind Direction`(degrees)"/>
        <tcol source="wdir" fun="RGavg" 
         label="Average Wind Direction`(degrees)`as Rank"/>
        <tcol source="wspd" fun="avg" 
         label="Average Wind Speed`(m/s)"/>
        <tcol source="wspd" fun="RGavg" 
         label="Average Wind Speed`(m/s)`as Rank"/>
        <tcol source="vis" fun="avg" 
         label="Average Visibility`(km)"/>
        <tcol source="vis" fun="RGavg" 
         label="Average Visibility`(km)`as Rank"/>
      </tabu>
    </widget>
  </layout>
</dynamic>

Since the label attributes of the first two <tcol> elements share Average Dry Bulb Temp as the first line of their multi-line column headings and (Celsius) as the second line, and span_headers_ is set to 2, a header consisting of the two common lines will span both resultant columns.

Example: Pinning rows

The following example pins all of the rows that are specified by what is entered in the expression editor. By default, in this example, the first two rows that contain state="'FL'" are pinned to the top. This example also uses pinnedrowbgcolor_ to add a background color to the pinned rows.

<base table="pub.demo.weather.stations"/>
<dynamic e="state='FL'" r="">
  <do when_="{@e<>''}" value_="@r" col_="1">
    <find value="{@e}" count="2"/>
  </do>
  <layout arrange_="v">
    <widget class_="expression" value_="@e"/>
    <widget class_="grid" type_="scroll" 
     pinnedrows_="{@r}" pinnedrowbgcolor_="#a0b0c0"/>
  </layout>
</dynamic>

This example uses the <find> operation to select the rows to pin. Modifying the count attribute changes how many entries are searched for.

type_="scroll"

Syntax

Attributes for type_="scroll"

Example: Scrolling grid

Example: Clickable column heads

Example: Creating headers that span across multiple columns

Example: Pinning rows

`type_="scroll"`

Attributes for `type_="scroll"`