Data Grid 2.0

From Daxipedia

Data Presentation
Part of a series on
4DAF v11.1
Data Grid · Field Editor
Bridge
Bridge
Reports & Dashboards
Dashboard · Chart
iPhone Dashboard
Supporting Objects
Calendar Picker

1 About
2 Dependencies
3 UI Notes
4 Commands
5 Events
6 Styling
- 6.1 Via CSS classes

[edit] About

Data grid.

[edit] Dependencies

Data grid is constructed using the following objects, making the API of those objects available to developer.

Object Name	API Access
Grid	myDashboard.commandName
Toolbar	myDashboard.toolbar.commandName
Viewport	myDashboard.viewport.commandName
Window	myDashboard.window.commandName

[edit] UI Notes

Holding Shift key while clicking on the "+" button on the toolbar will create a record via inline editor instead of regular editor.

[edit] Commands

[edit] Start with new Data Grid

[edit] Create Data Grid

var myDataGrid = new dax_dataGrid(selection, location, headerRows, lockedLeftColumns, useControlColumn);

selection - selection name
location - null to create Data Grid as a window, or node reference to embed the grid. Node must have width and height set in pixels.
headerRows - optional, number of header rows. First header row is automatically populated by titles and allows for column resizing, sorting, and selection. Default: 1 (title row counts as header).
lockedLeftColumns - optional, number of columns to lock on the left side.
useControlColumn - show control column on the left, true by default. Used for inline editing.

After creating the grid, use myDataGrid.go() call to run it.

[edit] Activate the Grid

myDataGrid.go();

Initializes and shows the data grid.

[edit] Embedded grid resizing

Embedded grid supports resizing of the parent element. Call:

myDataGrid.activate();

The Grid will resize to fit the element it is in.

Example:

// change the size of the div that holds the grid
$('myDataGridDiv').style.width = '600px';

// update grid to fit
myDataGrid.activate();

[edit] Headers and footers

[edit] Add footers and locked right column

myDataGrid.setFooterRows(number of footer rows);

myDataGrid.setRightLockedColumns(number of locked right columns);

Example:

myDataGrid = new dataGrid ('Employee', null);
myDataGrid.setFooterRows(2);
myDataGrid.go();

myDataGrid = new dataGrid ('Employee', null);
myDataGrid.setLockedRightColumn(1);
myDataGrid.go();

[edit] Get footer row number

To get footer row number:

var realRowNumber = myDataGrid.getFooterRowNumber(footerRowNumber);

[edit] Change header and footer row height

These calls must be made immediatelly after .go():

daDataGrid.setHeaderHeight(row number, height in units);
daDataGrid.setFooterHeight(row number, height in units);

Properties:

row number - starts from 0
height in units

Example that will create a grid with 2 header rows and 1 footer row, and all of them will have the height of 2 units:

// create grid with 2 header rows
daDataGrid = new dataGrid ('Employee', $('reportGoesHere'), 2, 0, false);

// add one footer row
daDataGrid.setFooterRows(1);

// initialize the grid
daDataGrid.go();

// set header & footer heights
daDataGrid.setHeaderHeight(0, 2);
daDataGrid.setHeaderHeight(1, 2);
daDataGrid.setFooterHeight(0, 2);

[edit] Data

[edit] Refresh

Refresh current data grid selection. Added in v11.2

myDataGrid.refresh();

[edit] Sort

[edit] Perform sort

myDataGrid.sort(field, order);

field - field name or id
order - asc or desc, optional

[edit] Enable / disable

myDataGrid.sortingAllowed(boolean);

[edit] Reference

var columnNumber = myDataGrid.getColumnByFieldId(fieldId);

Example:

// find out which column belongs to field [Employee]FirstName
var fieldId = dax_getField('Employee', 'FirstName').fieldid;
var employeeFirstNameColumn = myDataGrid.getColumnByFieldId(fieldId);

var rowNumber = myDataGrid.getRowByRecordId(recordId);

Example:

// check which row, if any, has the record with id '[3][4]'
var recordRow = myDataGrid.getRowByRecordId('[3][4]');

[edit] Auto refresh

myDataGrid.setRefreshInterval(seconds);
myDataGrid.enableAutoRefresh();
myDataGrid.disableAutoRefresh();

Example:

// refresh grid every 10 minutes
myDataGrid.setRefreshInterval(600);

[edit] Query

[edit] New, add, and run query

.newQuery();

.addQuery(field name, operator, value, and/or flag);

Operator can be: =, #, <, >, <=, >=

.runQuery();

Example:

.newQuery();
.addQuery(‘Field1’, ‘=’, ‘Mike’);
.addQuery(‘Field2’, ‘>’, ‘200’);
.runQuery();

[edit] Send custom values to 4D

These values are retrieved by GET WEB FORM VALUES command in 4D. This is used to pass additional information to 4D, especially when query is created by developer's custom 4D function.

myDataGrid.addCustomValue(name, value);
myDataGrid.clearCustomValues();

Example:

Sent two values to the 4D when query is made. Both of these are retrieved from two input fields present on the page.

Javascript

// clear all existing values
myDataGrid.clearCustomValues();

// get values from input fields
var myCity = $('myCity').value;
var myState = $('myState').value;

// add values to the query
myDataGrid.addCustomValue('myCity', myCity);
myDataGrid.addCustomValue('myState', myState);

// run query with stored custom values to 4D
myDataGrid.runQuery();

HTML

My City: <input type="text" id="myCity" />
My State: <input type="text" id="myState" />

[edit] Get custom values from 4D

Values sent to 4D with query reply.

To get custom values object:

myCustomValues = myDataGrid.getCustomValuesFrom4D();

Object properties:

myCustomValues.length -> number of returned values

Name/value pair, where valueNumber is an integer starting from 0 and above:

myCustomValues[valueNumber].name
myCustomValues[valueNumber].value

[edit] Max number of characters per field

myDataGrid.querySetMaxChar(number of characters);

Example:

// all field values will be truncated at 50 characters
myDataGrid.querySetMaxChar(50);

[edit] Query for all records

myDataGrid.queryAllRecords();

[edit] Query initial selection

Added in v11.2.

This call will run a query that was executed when grid was opened the first time. This is most often 'all records' selection, or first preset selection if 'all records' is not enabled in control panel.

myDataGrid.queryInitialSelection();

[edit] Set and get cell contents

var cellValue = myGrid.getCellValue (row, col);
myGrid.setCellValue (row, col, content);

[edit] Rows, columns, and cells

[edit] Show & hide columns

These calls should be made after .go(); call, since columns are not initialized before then. Column numbers start from 0.

.showColumn(col number);
.hideColumn(col number);

[edit] Rows

[edit] Get row pointer

var myRow = myGrid.getRow(row)

[edit] Row properties

Accessible via myRow.property:

.cells - array of cells
recordId - string
rowHeight - integer, row height in units
type - string, 'header', 'footer', or 'default'

Example:

var myRow = myDataGrid.getRow(3); // get reference for 4th row
alert ('Record id for this row is' + myRow.recordId); // show record id via .recordId property

[edit] Columns

[edit] Get column pointer

var myColumn = myGrid.getColumn(column)

[edit] Column properties

Accessible via myColumn.property:

cells - array, pointers to cells
colWidth - integer, column width in pixels
field - field object, with subproperties .fieldname, .fieldtype, .fieldalias, .fieldid, and so on. For details, check getField documentation in Bridge.
isResizable - boolean, is column resizable
visible - boolean, is column visible

Example:

// check if 3rd column is visible
var myColumn = myDataGrid.getColumn(3);
var myColumnIsVisible = myColumn.visible;

[edit] Column width

Following commands get and set column width in pixels.

myGrid.setColumnWidth(colNum, width);

var myColumnWidth = myGrid.getColumnWidth(colNum);

[edit] Allow user resizing

This command allows or prohibits user resizing of columns with click & drag interface.

myGrid.allowColumnResize(allowColumnResize, column number);

allowColumnResize - boolean, allow column resizing.
column number - optional, if present setting is modified for only one column, if not it modifies entire grid settings

[edit] Cells

[edit] Get cell pointer

var myCell = myGrid.getCell(row, column)

[edit] Cell properties

Accessible via myCell.property:

allowDragDrop - boolean, does this cell accept drag & drop events?
allowDragOut - boolean, is this cell draggable?
column - integer, column number starting from 0
row - integer, row number starting from 0
value - string, last set value
grid - pointer back to grid object

Example:

// get cell value
var myCell = myGrid.getCell(3,4);
var cellValue = myCell.value;

[edit] Set row height in pixels

This will update base row height in pixels for all rows. Row height in units is preserved, so row with height of 2 units will have final height of (2 * new size in pixels).

myGrid.setRowHeightInPx(rowHeight);

rowHeight - new row height in pixels

[edit] Row click selection

Defines how many rows can be selected at a time with a row click.

myGrid.setSelectionMode(selectionMode);

selectionMode - 'multi', 'single', or 'none'. 'multi' by default.
- Multi - emulates OS-like selection, where CTRL or CMD key add or remove records from selection.
- Single - same as Multi, but doesn't allow for more than one record selected at the time.
- None - no selection is allowed.

[edit] Grid

[edit] Redraw and refresh

Grid will perform visual refresh after every function that requires it. To disable this temporarily for quick grid building, use commands below:

myGrid.disableVisualRefresh;
myGrid.enableVisualRefresh(doRefresh);

doRefresh if set to true, full visual refresh will be performed with enabling visual refresh.

[edit] Drag & drop

[edit] Events

myGrid.ondragover(targetCell); → return CSS style class name to visually indicate which cell is mouse hovering over, or null to skip visual indication. 
myGrid.ondragout(targetCell);
myGrid.ondragrelease(targetCell);

[edit] Set cells as drop zone

myGrid.setDropCells(row, column, isDroppable);

Combination of row and col will select cell, row, column, or everything.

All cells are set as drop zone by default.

[edit] Set cell as draggable

myGrid.setDragCells(row, column, isDraggable);

Draggable cells will not support mouse hover and selection mechanics.

No cells are set as draggable by default.

During the drag & drop process, the source cell is accessible through:

dax_bridge.hoverDragging.dragObjectSource

[edit] Set draggable object

To make any object draggable, call:

dax_setDraggable(draggableObject);

This will not move the actual object.

[edit] Multi-grid drag & drop example

Javascript portion:

	var gridOne;
	var gridTwo;
	
	function dax_loginSuccess() {

		// create first grid, this will be the target for drag & drop action
		gridOne = new dax_dataGrid ('Employee', $('gridOne'), 1, 0, false);
		gridOne.setSelectionMode('none');
		gridOne.ondragover = onDragOverEvent;			// give custom CSS class to visually show if cell is selectable
		gridOne.ondragrelease = onDragReleaseEvent;		// process drag & drpo
		gridOne.go();
		
		// create second grid, cells will be dragged from here
		gridTwo = new dax_dataGrid ('Branch', $('gridTwo'), 1, 0, false);
		gridTwo.setSelectionMode('none');				// disable selection
		gridTwo.go();
		gridTwo.setDragCells(null, 5, true);			// make 6th column draggable
		
	}

	// set css class for cell over which mouse is hovering
	// returning null means that there will be no visual indication
	function onDragOverEvent(cellRef, event) {
		return 'dragdrop_style';
	}
	
	// mouse is let go over the cellRef cell, display cell row, column, and value on success
	function onDragReleaseEvent(cellRef, event) {
		var originCell = dax_bridge.hoverDragging.dragObjectSource;

		var targetCellInfo = 'Cell(' + cellRef.row + ',' + cellRef.column + ') has value ' + cellRef.value;
		var originCellInfo = 'Cell(' + originCell.row + ',' + originCell.column + ') has value ' + originCell.value;
	}

CSS portion:

	.dax_datagrid .dragdrop_style {
		background-color: red;
	}

HTML portion:

	<div id="gridOne" style="width: 500px; height: 300px;"></div>
	<div id="gridTwo" style="width: 500px; height: 150px;"></div>

[edit] Sleep

Pause all periodic updates (data refresh, unique query refresh).

myGrid.sleep();

This is useful when object is in background or hidden, and resources shouldn't be used to update the object. Use .wake() to resume updates.

Example:

myDataGrid.sleep();

// hide grid
$('myGridDiv').style.visibility = 'hidden';

[edit] Wake

Resume all periodic updates (data refresh, unique query refresh) paused with .sleep().

myGrid.wake();

Example:

// show grid
$('myGridDiv').style.visibility = 'visible';

myDataGrid.wake();

[edit] Destroy

Removes the object completely.

myGrid.destroy();

[edit] Selection

[edit] Select row by record id

myDataGrid.selectRowByRecordId(recordId);

[edit] Select row by number

myDataGrid.selectRow(rowNumber);

[edit] Add, remove, and clear

Records currently selected in the browser.

myDataGrid.addRecordToSelection(recordId);
myDataGrid.removeRecordFromSelection(recordId);
myDataGrid.removeAllRecordsFromSelection();

Examples:

myDataGrid.addRecordToSelection('[3][4]');

myDataGrid.removeRecordFromSelection('[3][4]');

[edit] Delete selection

myDataGrid.deleteSelectedRecords(skipConfirmation);

[edit] Status bar

[edit] Show or hide status bar

myDataGrid.showStatusBar(boolean);

Example:

// create new grid
myDataGrid = new dax_dataGrid ('Employee');

// don't show status bar
//
// status bar is hideable/showable even after grid is drawn,
// but hiding it before .go() phase is more efficient since no redraw is required
myDataGrid.showStatusBar(false);

// draw the grid
myDataGrid.go();

[edit] Show message

myDataGrid.showStatusMessage(message);

[edit] Sidebar

[edit] Preset queries

Preset queries are created in the control panel or via 4D 4DAF calls.

Field(s) used for unique value queries must have at least one of the visibility checkboxes turned on in the control panel.

Once sidebar is created, position and width are locked and not modifiable.

[edit] Show and hide

myDataGrid.showQuerySidebar(position, width);
myDataGrid.hideSidebar();

position - 'left' or 'right', optional
width - in pixels, 160px is default if not specified

[edit] Tabs

Tabs display preset queries, which are created in the control panel or via 4D 4DAF calls.

[edit] Show and hide

myDataGrid.showQueryTabs();
myDataGrid.hideQueryTabs();

[edit] Preset queries

To allow user to select preset queries via UI, check out the preset query sidebar and tabs. Preset queries are created in the control panel.

[edit] Run by name

myDataGrid.runPresetQuery (name, field);

name - runs preset query by name
field - field name, needed only for unique value queries

[edit] Editor

[edit] New record

Opens editor sheet with blank fields to create a new record.

myDataGrid.editorNewRecord();

[edit] Edit record

myDataGrid.editorEditRecord(recordId);

Example:

// open editor with record with id [3][4] loaded
myDataGrid.editorEditRecord('[3][4]');

[edit] Allow editor

Disables or enables record editor when double clicking on the row. Enabled by default.

myDataGrid.allowEditor(boolean);

[edit] Toolbar

[edit] Show toolbar

Example:

myDataGrid.showToolbar(['createrecord','deleterecords','search']);

[edit] Hide toolbar

myDataGrid.hideToolbar();

[edit] Search and advanced search toolbar

Update the fields displayed in the list.

Example:

myDataGrid.updateSearchFieldList([ '[3][3]', '[3][4]']);

Reminder you can use getField and the attribute fieldid to find field IDs. Ex:

myDataGrid.updateSearchFieldList([ myDataGrid.getField(“Employee”,”FirstName”).fieldid, myDataGrid.getField(“Employee”,”LastName”).fieldid]);

[edit] Inline editing

[edit] Allow inline editing

myDataGrid.allowInlineEditing(boolean);

[edit] Initiate inline editing

myDataGrid.inlineEdit(row, recordId);

Pass one or none of the parameters:

row - row number to edit, starts from 0
recordId - record id to edit

If no parameters are passed, inline edit will be blank and save a new record.

Examples:

// edit 4th row
myDataGrid.inlineEdit(3);

// edit record id [3][4]
myDataGrid.inlineEdit(null, '[3][4]');

// create new record via inline editing
myDataGrid.inlineEdit();

[edit] Save edited record

myDataGrid.inlineEditSave();

Save currently inline edited record.

[edit] Cancel inline editing

myDataGrid.inlineEditClear();

Clear currently inline edited record.

[edit] Events

[edit] On cell, row, column click and double click

To assign custom functions to the column, row, or cell click events, assign them to the respective grid functions:

myGrid.onDataColumnClick = function myFunction(column, fieldReference);
myGrid.onDataRowClick = function myFunction(row, recordId);
myGrid.onDataCellClick = function myFunction(row, column, recordId, fieldReference);

Added in v11.2:

myGrid.onDataRowDblClick = function myFunction(row, recordId);
myGrid.onDataCellDblClick = function myFunction(row, column, recordId, fieldReference);

Parameters:

column and row are integers, starting from 0.
fieldReference is field object, with fieldid, fieldalias, etc attributes.
recordId is record in [x][y] format

Returning false will prevent default data grid actions (selection, for example).

Example:

function myDataCellClickEvent(row, column, recordId, fieldRef) {

// update clicked cell value
this.setCellValue(row, column, 'Clicked');

}

myDataGrid.onDataCellClick = myDataCellClickEvent;

[edit] Sorting

myGrid.onBeforeSort = function() { };
myGrid.onAfterSort = function() { };

[edit] Data

[edit] Before data display

Data arrived from 4D, but it's not displayed yet.

myGrid.onBeforeDataDisplay = function() { };

[edit] Check values before display

myGrid.getParsedDataValue(record (row), field (column));

where record and field are integers that start from 0. Record & field correspond to row & column number.

Example:

myValue = myGrid.getParsedDataValue(3,4);

[edit] Modify values before display

myGrid.setParsedDataValue(record (row), field (column), value);

where record and field are integers that start from 0. Record & field correspond to row & column number.

Example:

myGrid.setParsedDataValue(3,4, 'new value');

[edit] Get number of returned records

myGrid.getParsedDataRecordCount();

where row and column numbering starts from 0. This is equal to number of data rows.

[edit] On data load

myGrid.onDataLoad = function() { };

[edit] Styling

[edit] Via CSS classes

[edit] By data type

Following CSS classes are available based on the data type.

.datanumeric
.datatext
.datatime
.datadate
.databoolean
.dataheader

Remember to add .dax_datagrid prefix to these classes.

[edit] Assign classes

myDataGrid.setRowStyle(row, styleName, alternateRowStyleName, useAsDefault);
myDataGrid.setColumnStyle(column, styleName, alternateRowStyleName, useAsDefault);
myDataGrid.setCellStyle(row, column, styleName, alternateRowStyleName, useAsDefault);

alternateRowStyleName and useAsDefault are optional.

Remember to add .dax_datagrid prefix to these classes.

[edit] Set entire grid class

This command appends the class name to the grid. This makes any style that starts with .myClassName be applied only for this specific grid.

myGrid.setGridClass(className);

[edit] CSS prefixes

All data grid CSS styles must have .dax_datagrid prefix, like in the example below.

.dax_datagrid .myStyle {
...
}

Additional prefixes could be used to apply style only for specific grid elements. List of prefixes:

dax_grid_topleft_container	dax_grid_top_container	dax_grid_topright_container	Header rows
dax_grid_left_container	dax_grid_container	dax_grid_right_container	Scrollable rows
dax_grid_bottomleft_container	dax_grid_bottom_container	dax_grid_bottomright_container	Footer rows
Locked left columns	Scrollable columns	Locked right columns

Example that will only style rows in both locked and unlocked areas, excluding the header:

.dax_datagrid .dax_grid_container .myStyle, .dax_datagrid .dax_grid_lockedcol_container .myStyle {
...
}

Retrieved from "http://daxipedia.4d.com/index.php/Data_Grid_2.0"

Data Grid 2.0

From Daxipedia

Contents

[edit] About

[edit] Dependencies

[edit] UI Notes

[edit] Commands

[edit] Start with new Data Grid

[edit] Create Data Grid

[edit] Activate the Grid

[edit] Embedded grid resizing

[edit] Headers and footers

[edit] Add footers and locked right column

[edit] Get footer row number

[edit] Change header and footer row height

[edit] Data

[edit] Refresh

[edit] Sort

[edit] Perform sort

[edit] Enable / disable

[edit] Reference

[edit] Auto refresh

[edit] Query

[edit] New, add, and run query

[edit] Send custom values to 4D

[edit] Get custom values from 4D

[edit] Max number of characters per field

[edit] Query for all records

[edit] Query initial selection

[edit] Set and get cell contents

[edit] Rows, columns, and cells

[edit] Show & hide columns

[edit] Rows

[edit] Get row pointer

[edit] Row properties

[edit] Columns

[edit] Get column pointer

[edit] Column properties

[edit] Column width

[edit] Allow user resizing

[edit] Cells

[edit] Get cell pointer

[edit] Cell properties

[edit] Set row height in pixels

[edit] Row click selection

[edit] Grid

[edit] Redraw and refresh

[edit] Drag & drop

[edit] Events

[edit] Set cells as drop zone

[edit] Set cell as draggable

[edit] Set draggable object

[edit] Multi-grid drag & drop example

[edit] Sleep

[edit] Wake

[edit] Destroy

[edit] Selection

[edit] Select row by record id

[edit] Select row by number

[edit] Add, remove, and clear

[edit] Delete selection

[edit] Status bar

[edit] Show or hide status bar

[edit] Show message

[edit] Sidebar

[edit] Preset queries

[edit] Show and hide

[edit] Tabs

[edit] Show and hide

[edit] Preset queries

[edit] Run by name

[edit] Editor

[edit] New record

[edit] Edit record

[edit] Allow editor

[edit] Toolbar

[edit] Show toolbar

[edit] Hide toolbar

[edit] Search and advanced search toolbar

[edit] Inline editing