The "Browser grid" is an output mechanism that is actually a mixture of a grid with two browsers. This presentation type uses a browser to expand rows, another browser to expand columns, and then displays information in the table that is formed by these rows and columns.
Browser grid expects four scripts with a special name, of which three are mandatory:
- "rowChildren' (mandatory): a script that, just like with the browser presentation type, returns the values the row browser has to show when a branch is expanded.
- "columnChildren" (mandatory): equivalent to the script named "rowChildren", returning the values the column browser has to show when a branch is expanded.
- "gridValues" (mandatory): this script should return at least three values with each output: the row value, the column value, and the value(s) to show in the cell positioned at that row and column.
- "initialise" (optional): this script enables you to influence the behavior of this presentation by setting one or more parameters.
In the Query tool, scripts can be named by right clicking the script's tab and choosing the Properties option. The properties dialog allows you to change the name.
In the following sections each type of script is described in the context of an example: a browser grid that on each row displays an object, on each column a view, and in each cell shows if the object is referenced on this view ("where used"). As a bonus, the schemes in which the objects are located are also among the rows, and for these, the cell shows the aggregated information of the objects below.
Row and column browsers
The scripts for the row and column browsers, which have to be named "rowChildren" and "columnChildren" respectively, work just like any browser script. The script gets the current location in the browser tree via the predefined variable path, which is a list containing the values from the root of the tree up to and including the value just expanded. Initially, when the browser tree needs to display its root(s), it will call the script once with an empty path.
In our example the row script should return the top level schemes when asked for roots, otherwise it should return all children of the object expanded, as long as they are semantic objects of a type we are interested in ((semantic) objects, schemes, and folders). The script "rowChildren" could be written like this:
The script "columnChildren" is very similar; except for the types of object we want it to return (views and folders this time):
The creation of one or more rows and one or more columns by expanding the row and column browser trees results in a grid of cells. These cells are empty by default, but can show values that are returned by a mandatory third script called "gridValues". Each output statement in this script must return at least 3 values: row value, column value, and cell value. A cell may contain multiple values simultaneously: When more than 3 values are specified, the third value and onward are all put into the cell. In the same manner, when other output statements specify the same row and column values, the cell value(s) of these statements are appended to the list of values already in the cell.
Please note that the number of cells handled by the "gridValues" script has no relation to the size of the actual grid: its maximum dimensions are determined entirely by the row and column browser scripts. The grid values script may handle only part of the row/column combinations in the grid (leaving the rest of the cells empty) or might output values outside the grid (leaving these values unused). The grid values script is executed once, and its output stored for retrieval when the browsers uncover new cells in the grid.
In the example, we want the "gridValues" script to let us know that a (semantic) object (the row value) is referenced on a view (the column value). We let the script output the string value "ref on", but we might as well have chosen any other value, like x, 158 or true. For the (semantic) schemes that contain one or more of such a referenced object we output "child ref on":
At the end, the output is sorted unique, to remove any duplicate cell values. The resulting browser grid looks like this:
Grid presentation options
The fourth (optional) script called "initialise" allows you to set some parameters that influence the manner in which the grid displays its information. The parameters supported are:
- "showLabels" (true or false): When set to true, the grid cells will show the text representation of its value(s). When false, no texts are shown. The default value of this parameter is true.
- "showColors" (true or false): When set to true, the background of the grid cells will contain a color for each of its values. When false, no colors are displayed. The default value of this parameter is false.
"ValueColor": Assigns a cell background color to a specific cell value. Like the equally named parameter used with the color view presentation type, it expects two values: the value to assign the color to, and a list of three integer values (in the range [0,255]) representing the red, green and blue portions of the color. When no colors are bound to a value this way, the grid uses a color from its own palettes, just like the color view filter does.
- "initialExpansionDepth": The number of levels the row and column browser trees are expanded initially. By default, the grid browsers are expanded to the depth of 1 level. Specify 0 to open the grid with the trees fully collapsed.
In our example, we want to color the cells with shades of green instead of displaying the "ref on" texts. To achieve this, we have to hide the labels, activate the coloring, and assign the colors to the two possible values. We also set a large expansion depth to force full expansion of the browsers:
The final result of these four scripts is the following grid: