Grid Control 3.0

Grid Control 3.0 API Reference

This API reference page contains the following main sections:

File Structure

Control files are in the schema\ab-core\controls\grid folder.

File

Description

schema\ab-core\controls\grid\ab-grid-control.js

The grid control. Exposes the public API. Is not coupled with the ARCHIBUS view framework, due to the createControl API.

schema\ab-core\controls\grid\ab-grid-control-view.js

Classes that implement grid features. Used from the grid control, are not directly used from application code.

schema\ab-core\controls\grid\ab-grid-control-view-columns.js

Classes that implement the columns for the grid. Converts user data to columns in the data columns to display correctly in the grid.

schema\ab-core\controls\grid\ab-grid-control-view-datasource.js

Classes that implement the datasource for the grid. Loads data from the server and creates the necessary data structure to display in the grid.

schema\ab-core\controls\grid\ab-grid-control-view-rows-selected.js

Classes that implement the selected rows in grid. Contains functions for managing the selected rows and correctly displaying the selected checkboxes in the grid.

Note: The base class for each JavaScript file is Base.

Add Grid Control to a View

This section contains the following subsections:

Using HTML and JavaScript

To add grid control to a view using HTML and JavaScript:

  1. Add a data source for the grid, as usual.

  2. Add an HTML panel and a DIV element that will contain the grid:

    <panel type="html" id="projectsGrid"> <html> <div id="projectsGridContainer"></div> </html> </panel>

  3. Include the grid control file:

    <panel type="view" id="gridControl" fileName="grid-control.axvw">

  4. Initialize the grid object with configuration properties:

    var grid = View.createControl({ control: 'DataGrid', panel: 'projectsGrid', container: 'projectsGridContainer', columns: [ {column definition}, {column definition}, ... ], events: { event, event, ... } dataSource: 'projectsDataSource', ... other configuration options ... });

Grid Configuration Properties

Property

Description

Example value

Comment

panel

The ID of the HTML panel in the view.

'projectsGrid'

 

container

The ID of the DOM element that contains the grid.

'projectsGridContainer'

 

dataSource

The ID of the data source object in the view.

'projectsDataSource'

 

title

The localized grid title.

'Projects'

 

actions

The list of actions displayed in the grid header.

[{

id: 'refresh', text: 'Refresh', commands: [...]

}]

 

events

The map of grid event listeners.

{

afterRefresh: function

}

 

Columns

columns

An array of objects that contain column definitions, see below.

 

 

lastLeftFixedColumn

The ID of the last column in the left fixed set of columns.

'project.description'

Optional. By default all columns except the multiple selection checkbox column and the edit controls column are scrollable.

firstRightFixedColumn

The ID of the first column in the right fixed set of columns.

 

Layout

layoutRegion

The ID of the layout region that contains the control.

'projectsRegion'

Optional. If not specified, the control is displayed in the main view content area.

width

The grid width in pixels.

800

Optional. If not specified, the control occupies 100% of the available height and width.

height

The grid height in pixels.

400

Behavior

hidden

Whether to display the grid after the view calls the grid constructor.

false

Optional. By default the grid is visible.

showOnLoad

Whether to perform initial data fetch when the view calls the grid's initialDataFetch method.

true

Optional. By default the grid performs initial data fetch.

showFilter

Whether to display the filter bar. When false, the user will not be able to see the filter bar.

true

Optional. Default is true.

pageSize

The maximum number of records to display on one page.

100

Optional. By default the server-side data source sets the record limit.

Set to 0 to display all records on one page.

multipleSelectionEnabled

Specifies that the grid displays multiple selection checkboxes.

true

Optional.

Column definitions specify column properties that are specific to each view, and are not controlled by ARCHIBUS field metadata:

Property

Description

Example value

Comment

id

The unique ID of the column within the grid.

'project_id'

 

fieldName

The full name of the data source field displayed in the column.

'project.project_id'

Optional. Virtual columns do not display database fields.

title

The localized column title.

'Project Code' 'Area, ft²' 

Optional. If not defined, the grid will use the title defined in the field definition.

width

The column width in pixels.

200

Optional. By default the grid set column width automatically depending on content. Use this property to set a fixed width for a column.

cssClass

The name of the CSS class used to render column data cells.

'projectStatus'

Optional. Use to add unique style to a column.

dataType

The ARCHIBUS data type of the column values.

'number'

Optional. By default, the grid obtains the data type from the data source based on the fieldName property. If the field does not exist in the data source, use this property. 

Supported values: 'text', 'number', 'date', 'time'.

dateTimeFormat

The format pattern used to format date and time values

'Y-m-d'

Optional. By default, the control uses the strDateShortFormal global variable. Used for date, time, and timestamp fields. Not used for other fields.

groupBy

Specifies that the grid should group records by unique values of this column.

true or false

Only one column can have groupBy: true.

sortBy

Specifies that the grid should sort records by values of this column.

'asc' or 'desc'

Specifies initial sort order. Users can sort the grid by any column.

groupColumnTitle

The column group title.

'Cost Fields'

Several columns can be grouped under a common title. Each column will still display its own title, and all columns in the group will also have the group title. A group contains columns that have the same groupColumnId value. One of the columns in the group must have the groupColumnTitle property.

groupColumnId

The ID of the column that provides the column group title.

'wr.cost_total'
groupBackgroundColor

The RGB color for group column headers.

'#90EE90'

listener

The listener function to call when the user clicks on the column value or button in any row.

function(row) { ... }

When the listener is specified for a column:

  • If the column has a corresponding data source field, field values in column cells for each row are displayed as hyperlinks.
  • If the column has no corresponding data source field, column cells for each row are displayed as buttons. The column title is the button text.

commands

Defines a list of commands to invoke when the user clicks on a button displayed in the column cell. Each command is a configuration object that is used to create an Ab.command.Command instance.

[{

type: 'showPanel', panelId: 'projectForm'

}] 

If the column has commands:

  • Database field columns display data values as hyperlinks.
  • Virtual columns display buttons. The column title is displayed as the button text.

showTotals

Specifies that that grid should display total values for this column. If the grid also groups records by another column value, it should display sub-totals for this column values in each group header.

true or false

Optional for numeric fields. Not used for other fields.

totalsFunction

Specifies the function used to calculate column totals and sub-totals.

'sum', 'avg', 'min', or 'max'

Optional. Default is 'sum'. Not used if showTotals=false.

Columns that display ARCHIBUS database fields can access field schema properties as follows:

var dataSourceDef = View.dataSources.get('projectsDataSource'); var fieldDef = dataSourceDef.fieldDefs.get('project.project_id');

Data Types

Data type

Description

Example raw value

Example displayed value

Comment

text

Displays a text value

'HQ'

HQ

 

date

Displays a date value in the localized format

'2013-09-14'

9/14/2014

Uses date format from field definition.

time

Displays a time value in the localized format

'18:45.46.000'

6:45PM

Uses time format from field definition.

number

Displays a real value

1073.30

1,073.30

Numeric values are right-aligned in column cells,  all other values are left-aligned.

integer

Displays an integer value

5

5

Event Types

Event type

Description

Parameters

beforeRefresh

Called before the grid loads data from the server.

 

afterGetData

Called after the grid loads data from the server

 

afterRefresh

Called after the grid displays data loaded from the server.

 

onClickItem

Called when the user clicks on any grid row cell.

Row: the Ab.datagrid. Row object.

onMultipleSelectionChange

Called when the user selects or unselects a row.

Row: the Ab.datagrid. Row object.

Selected: true if the row is selected.

Grid Methods

Method Description Parameters Return value Example

groupBy

Groups records by specified column, and re-displays the grid.

columnId: The ID of the groupBy column

None

grid.groupBy('wr.prob_type')

See also

Grid Control 3.0 Overview

Copyright © 1984-2019, ARCHIBUS, Inc. All rights reserved.