4D Ajax Framework

Data Grid API Reference

Windows®/Mac OS®

© 2008 4D SAS / 4D, Inc. All Rights Reserved.

4D Ajax Framework Data Grid API Reference
For Windows® and Mac OS®
Copyright© 2008 4D SAS / 4D, Inc.
All rights reserved.

The software described in this manual is governed by the grant of license provided in this package. The soft-
ware and the manual are copyrighted and may not be reproduced in whole or in part except for the personal
licensee’s use and solely in accordance with the contractual terms. This includes copying the electronic
media, archiving, or using the software in any manner other than that provided for in the Software license
Agreement.
4D, 4D Draw, 4D Write, 4D View, 4D Insider, 4D, 4D Server and the 4th Dimension and 4D logos are regis-
tered trademarks of 4D SAS.
Microsoft, Windows and Windows NT are registered trademarks of Microsoft Corporation.
Apple, Macintosh, Mac OS and QuickTime are trademarks or registered trademarks of Apple Computer Inc.
Mac2Win Software Copyright © 1990-2008 is a product of Altura Software, Inc.
ACROBAT © Copyright 1987-2008, Secret Commercial Adobe Systems Inc. All rights reserved. ACROBAT is a
registered trademark of Adobe Systems Inc.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
4D includes cryptographic software written by Eric Young ([email protected])
4D includes software written by Tim Hudson ([email protected]).
Spellchecker © Copyright SYNAPSE Développement, Toulouse, France, 1994-2005.
All other referenced trade names are trademarks, registered trademarks, or copyrights of their respective
holders.
Contents

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2 Data Grid API Reference . . . . . . . . . . . . . . . . . . . . . . 9

Create & Display Data Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Create a new Data Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Initialize the Data Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Add footers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Lock right columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Resizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Picture Preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Auto refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Set and get cell contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Wake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Destroy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Search and advanced search toolbar . . . . . . . . . . . . . . . . . . . . . 16
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Get Column number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Get Row number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Get footer row number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Get cell pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Get row pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Get column pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Set row height in pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Change header and footer row height . . . . . . . . . . . . . . . . . . . 22
Show & hide columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Get and Set Column width . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Allow user resizing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4D Ajax Framework Data Grid API Reference 3

Contents

Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
New Query, Add Query, and Run Query . . . . . . . . . . . . . . . . . . 26
Send custom values to 4D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Get custom values from 4D . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Query all records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Max number of characters per field . . . . . . . . . . . . . . . . . . . . . . 29
Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
On Before and On After Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Before data display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Check values before display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Modify values before display . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Get number of returned records. . . . . . . . . . . . . . . . . . . . . . . . . 31
Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Select row by record id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Select row by number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Add, remove, and clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Delete selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Selection Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Drag & drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Set cells as drop zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Set cell as draggable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Set draggable object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Show message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Preset queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Sidebar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Preset queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
New record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Edit record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Allow editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Inline editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Allow inline editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Initiate inline editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Save edited record. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Cancel inline editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
On cell, row, column click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
On data load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Before and After Hover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4 4D Ajax Framework Data Grid API Reference

 Contents

CSS Styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Override Styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Set entire grid class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Assign classes to Rows, Columns, and Cells . . . . . . . . . . . . . . . 49

4D Ajax Framework Data Grid API Reference 5

Contents

6 4D Ajax Framework Data Grid API Reference

1 Introduction

The new Data Grid introduced in 4D Ajax Framework v11 Release 1

(11.1) is a redesigned version of the existing Grid object built from the
ground up. With a re-worked core the Data Grid is now a more univer-
sal object with a more granular API for many of the 4D Ajax Frame-
work objects. It has a wealth of features such as the ability to:
„ Show and hide columns.

„ Select single records, multiple records at the same time, or none at all.

„ Lock columns, headers, and footers.

„ Fire events when rows or cells are selected, and when data arrives from
the back end.
„ Apply CSS styling.

„ And more…

4D Ajax Framework Data Grid API Reference 7

The Data Grid's Application Programming Interface (API) commands
are outlined in this document for when developers want to build the
Data Grid onto their Custom HTML pages.

4D Ajax Framework Data Grid API Reference 8

2 Data Grid API Reference

Create & Display Data Grid

Here are the commands associated with creating a Data Grid on your
custom page.

Create a new Data First, create the Data Grid using the following:
Grid var myGrid = new dax_dataGrid(selection, location,
headerRows, lockedLeftColumns, useControlColumn);
„ selection - Name of Table, View, or DCS the Data Grid will display.

„ location - Name of the <div> on the HTML page where the Data
Grid will be embedded. Pass null or no value to float the Data Grid
as a window.
„ headerRows - (optional) Number of rows the header is by height.
Default size is 1 row. The first header row automatically has the
capability of being populated by titles. Additional header rows are
blank and are up to the Developer to populate.
„ lockedLeftColumns - (optional) Number of columns to lock on the
left side.
„ useControlColumn - (optional) Show control column on the left.
Default value is 'True'. Used for inline editing.

Initialize the Data Then after creating the grid, use the .go() call to run and display it.
Grid myGrid.go();
At this point, a Data Grid will appear on your HTML page. The new
dax_dataGrid and the .go() commands are the minimum commands
necessary for displaying a Data Grid.

4D Ajax Framework Data Grid API Reference 9

Chapter 2 Data Grid API Reference

` A Data Grid embedded to the page:

var myGrid = new dax_dataGrid('People', $('DataGridDiv'));
myGrid.go();

Note In this example we have a <div> with an ID of "DataGridDiv". Notice

the notation used in this example when embedding the Data Grid into
a <div>.

` The same Data Grid as a floating window:

var myGrid = new dax_dataGrid('People', null);
myGrid.go();

10 4D Ajax Framework Data Grid API Reference

 Create & Display Data Grid

Note var myGrid = new dax_dataGrid('People'); also displays the Data Grid as
a floating window.

Add footers The following command can be used to set the number of footer rows.
myGrid.setFooterRows(number of footer rows);
Note It is recommended to call this command before the .go() command.

This command is not to be confused with the 3rd parameter in new

dax_dataGrid command, which defines the number of header rows.

` This example will build a Data Grid as a floating window with 2 footer
rows.
var myGrid = new dax_dataGrid('People', null);
// Add two footer rows
myGrid.setFooterRows(2);
myGrid.go();

Lock right columns The following command can be used to lock the number of right
columns.
myGrid.setRightLockedColumns(number of locked right
columns);
Note It is recommended to call this command before the .go() command.

4D Ajax Framework Data Grid API Reference 11

Chapter 2 Data Grid API Reference

This command is not to be confused with the 4th parameter in new

dax_dataGrid command, which defines the number of locked left
columns.

The number of right-most columns you specify here will always

display and remain locked in the Data Grid.

` This example will lock 1 column on the far right.

var myGrid = new dataGrid ('People', null);
// Lock 1 right column
myGrid.setLockedRightColumn(1);
myGrid.go();

Resizing <div> areas on an HTML page may resize. If that resized <div> contains
your Data Grid, you will need to resize the Data Grid so that it fits
appropriately. Call the following command so that the Data Grid is
correctly resized.
myGrid.activate();
The Data Grid will resize to fit in the <div> that contains it.

` In this example, first the <div> that holds the grid is resized to 600
pixels wide. Then, the .activate() command is called to resize the Data
Grid into the <div>.
// Change the size of the div that holds the Data Grid
$('myGridDiv').style.width = '600px';
// Update Data Grid to fit
myGrid.activate();

Picture Preview

12 4D Ajax Framework Data Grid API Reference

 Data

Every picture field in the Data Grid displays a 'View Image' link to load
it. When users mouse over this link a preview of the image appears.
Use the following command to turn Picture Preview on or off.
myGrid.enablePicturePreview(previewEnabled)
„ previewEnabled - Boolean. Set to true to enable Picture Preview. Set
to false otherwise. Picture Preview is set to true by default.

Note This command must be called before the .go() call.

To take this command to another level, think about using it

conjunction with some events such as .onBeforeHover and .onAfterHover.

` This example disables Picture Preview.

myGrid = new dax_dataGrid('People');
// Disable Picture Preview
myGrid.enablePicturePreview(false)
myGrid.go();

Data
Auto refresh Enable or disable the Auto Refresh feature using the commands below.
myGrid.enableAutoRefresh();
myGrid.disableAutoRefresh();
Auto Refresh is on by default. With Auto Refresh on, its default interval
is 3 minutes (180 seconds). Modify the refresh rate using the command
below.
myGrid.setRefreshInterval(seconds);
` In this example the Data Grid is set to refresh every 10 minutes (600
seconds).
// refresh grid every 10 minutes
myGrid.setRefreshInterval(600);

Set and get cell To get the contents of a cell use this command:
contents var cellValue = myGrid.getCellValue (row, col);
„ row - Specify the row of the cell in which you intend to get the
value from.
„ col - Specify the column of the cell in which you intend to get the
value from.

4D Ajax Framework Data Grid API Reference 13

Chapter 2 Data Grid API Reference

` In this example we will get the value of a cell and display it in the
Status Bar. We get the cell value during the onDataLoad event because
the Data Grid cells do not have values until this event occurs.
var myGrid = new dax_dataGrid('People', null);
myGrid.showStatusBar(true);
myGrid.go();

myGrid.onDataLoad = function() {
var cellValue = myGrid.getCellValue (2, 3);
myGrid.showStatusMessage(cellValue);
}

To overwrite the contents of a cell use this command:

myGrid.setCellValue (row, col, content);
„ row - Specify the row of the cell in which you intend to set the con-
tent into.
„ col - Specify the column of the cell in which you intend to set the
content into.
„ content - the content defined here will overwrite the cell.

` Here we will define a variable (myContents) as two lines of data. We will

change the value of two header cells with the value of myContents.
// Create Data Grid with 2 Header Rows
var myGrid = new dax_dataGrid('People', null,2);
myGrid.go();

// Set Header Row 1 to height of 2 units

myGrid.setHeaderHeight (1, 2)

// Define myContents which will overwrite specific cells.

myContents is 2 // units high.
var myContents = "First line <br/> Second line"

// Set content of Header Row 1 cells

myGrid.setCellValue(1, 1, myContents);

14 4D Ajax Framework Data Grid API Reference

 Data

myGrid.setCellValue(1, 2, myContents);

Sleep This command will cause the Data Grid to no longer automatically
communicate with 4D. Thus, periodic updates such as automatic data
refreshes and the refreshing of Data Driven Preset Queries will no
longer occur.

Note The user, however, still can manually interact with the Data Grid with
full functionality (except for automatic communication).

myGrid.sleep();
This command is useful when the Data Grid is hidden, and when
resources are not intended to be used to update it. Use .wake() to
resume automatic updates.

` This example puts the Data Grid to sleep and then hides it.
myGrid.sleep();

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

4D Ajax Framework Data Grid API Reference 15

Chapter 2 Data Grid API Reference

Wake This command will wake a Data Grid that was previously put to sleep.
It will resume all periodic updates (data refresh, unique query refresh)
that were paused with the .sleep() command.
myGrid.wake();
` This example sets a Data Grid that previously set to 'hidden' to be
'visible.' Then all periodic communication with 4D is resumed using
the .wake() command.
// show grid
$('myGridDiv').style.visibility = 'visible';

myGrid.wake();

Destroy This command removes the Data Grid object completely.

myGrid.destroy();
` Example
myGrid.destroy();

// After the Grid is destroyed clear the variable

myGrid = null;

Search and The Search Toolbar displays only the fields you specify as searchable in
advanced search the 4D Ajax Framework Client environment.
toolbar
Note To make a field searchable, in the Client go to Control Panel -> Access
Control tab. Select the table the field belongs to. For each field you
want searchable, check the 'S' checkbox.

To override these searchable fields with a new list, use the following
command.
myGrid.updateSearchFieldList(recordID);
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

16 4D Ajax Framework Data Grid API Reference

 Reference

` This example enables the fields Last and City as searchable based on
their Record IDs:
myGrid.updateSearchFieldList([ '[1][2]', '[1][4]']);

` Remember, you can also use dax_getField and the attribute fieldid to
retrieve field IDs, as seen in this example:
myGrid.updateSearchFieldList([
myGrid.dax_getField("Employee","FirstName").fieldid,
myGrid.dax_getField("Employee","LastName").fieldid]);

Reference
Use the commands in this section to reference specific areas on the
Data Grid such as rows, columns, or cells.

Get Column number Use this command to get a column number using a Field ID. It is best
to use 4D Ajax Framework Bridge command dax_getField beforehand to
get the Field ID in the first place.
var columnNumber = myGrid.getColumnByFieldId(fieldId);
` Example
// find out which column belongs to field [Employee]FirstName
var fieldId = dax_getField('Employee', 'FirstName').fieldid;
var employeeFirstNameColumn = myGrid.getColumnByFieldId(fieldId);

Get Row number Use this command to get a row number:

var rowNumber = myGrid.getRowByRecordId(recordId);
„ recordId - String, unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

4D Ajax Framework Data Grid API Reference 17

Chapter 2 Data Grid API Reference

` This example will get a row number based on record ID.

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

Get footer row To get footer row number:

number var realRowNumber =
myGrid.getFooterRowNumber(footerRowNumber);
„ footerRowNumber - Integer, representing the number of the footer
row. Numbering begins at 0 (zero) so the first footer row is 0 (zero).

` To get the first footer row:

var myRow = myGrid.getRow(myGrid.getFooterRowNumber(0));

Also see the example in section “Change header and footer row
height” on page 22.

Get cell pointer Use this command to get a cell reference based on its row and column
number.
var myCell = myGrid.getCell(row, column)

Cell Properties Here are the properties of a given cell. Use the getCell command to get
a reference to a cell and then use the properties listed below to get
more information on it.

Accessible via myCell.property:

„ allowDragDrop - Boolean, which returns true or false answering
whether or not this cell supports the Drag and Drop events.
„ allowDragOut - Boolean, which eturns true or false answering whe-
ther or not this cell is draggable.
„ column - Integer, which represents the column the cell resides in.
Note: Column numbering starts from 0 (zero).
„ row - Integer, which represents the row the cell resides in. Note:
Row numbering starts from 0 (zero).
„ value - String, which represents the value in the cell.
„ grid - Pointer to the Data Grid containing the cell.

18 4D Ajax Framework Data Grid API Reference

 Reference

` This example will get a reference to a cell. From there it will display the
cell's value in the Status Bar. We get the cell value during the
onDataLoad event because the Data Grid cells do not have values until
this event occurs.
var myGrid = new dax_dataGrid('People', null);
myGrid.showStatusBar(true);
myGrid.go();

myGrid.onDataLoad = function() {
// Get reference to cell in Row 3 and Column 4
var myCell = myGrid.getCell(3,4);
// Display cell's value in Status Bar
myGrid.showStatusMessage(myCell.value);
}

Get row pointer Use this command to get a reference to a row based on its row number.
Row numbering starts at 0 (zero).
var myRow = myGrid.getRow(row)

Row Properties Here are the properties of a given row. Use the .getRow command to get
a reference to a row and then use the properties listed below to get
more information on it.

Accessible via myRow.property:

„ cells - Array of cells. To access cell properties see the Cell Properties
section.
„ recordid - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.
„ rowHeight - integer, representing row height in units.

4D Ajax Framework Data Grid API Reference 19

Chapter 2 Data Grid API Reference

„ type - Possible values are: 'header', 'footer', or 'default', which indi-

cate row type.

` This example will get the reference for the 4th row and then display its
Record ID in the browser's Alert dialog. We get the row's Record ID
during the onDataLoad event because Record ID's are undefined before
this event occurs.
var myGrid = new dax_dataGrid('People', null);
myGrid.go();

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

Get column pointer Use this command to get a reference to a column based on its column
number. Column numbering starts at 0 (zero).
var myColumn = myGrid.getColumn(column)

Column properties Here are the properties of a given column. Use the .getColumn
command to get a reference to a column and then use the properties
listed below to get more information on it.

Accessible via myColumn.property:

„ cells - Array that has pointers to cells

20 4D Ajax Framework Data Grid API Reference

 Presentation

„ colWidth - Integer, representing the width of the column in pixels.

„ field - Field object, with subproperties .fieldname, .fieldtype,
.fieldalias, .fieldid, and so on.
„ isResizable - Boolean, representing if column is resizable.
„ visible - Boolean, representing if column is visible.

` This example will see if the 3rd column is visible and display its status
in the Status Bar.
var myGrid = new dax_dataGrid('People', null);
myGrid.showStatusBar(true);
myGrid.go();

// check if 3rd column is visible

var myColumn = myGrid.getColumn(3);
var myColumnIsVisible = myColumn.visible;

// Display column's visibility value in Status Bar

myGrid.showStatusMessage(myColumnIsVisible);

Presentation
Change the complexion of Data Grid with the following commands.

Set row height in This will change the base row height in pixels for all rows - this
pixels includes all rows as well as all headers and footers. 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

4D Ajax Framework Data Grid API Reference 21

Chapter 2 Data Grid API Reference

` This example will make the default row height to be 25 pixels. The
default row height will change for all rows, headers, and footers.
myGrid.setRowHeightInPx(25);

Change header and Use these commands to change the row height of the header or footer.
footer row height
Note These calls must be made immediately after .go():

To set the Header height:

myGrid.setHeaderHeight(row number, height in units);
„ row number - A Data Grid defaults to have 1 header row to contain
the field title names. This first header row that contains field titles is
denoted as header 0. More headers can be added when the Data
Grid is created.
„ height in units - By default headers 1 unit high.

To set the Footer height:

daDataGrid.setFooterHeight(row number, height in
units);
„ row number - You specify the amount of footer rows in
.setFooterRows(). Use the .getFooterRowNumber() command in
.setRowHeight() to reference the footer row you intend to resize. See
example below.
„ height in units - By default footers are 1 unit high.

Note 1 unit = 21 pixels by default. The amount of pixels in 1 unit can be

changed by calling .setRowHeightInPx().

` Here we will create a grid with 2 header rows and 1 footer row. We will
set some of these rows to the height of 2 units:
// Create Data Grid with 2 header rows
var myGrid = new dax_dataGrid('People', null, 2);

// Add one footer row

myGrid.setFooterRows(1);

// Initialize the Data Grid

myGrid.go();

// Set Header Row 1 to a height of 2 Units

myGrid.setHeaderHeight (1,2);

22 4D Ajax Framework Data Grid API Reference

 Presentation

// Set Footer Row to a height of 2 Units

myGrid.setFooterHeight (myGrid.getFooterRowNumber(0),2);

Show & hide

columns
Note These commands should be made after the .go(); call, since columns
are not initialized before then.

Hide column based on column number:

myGrid.hideColumn(colNum);
„ colNum - The number of the column starting from the left side of
the Data Grid. Numbering begins at 0 (zero) so the left-most
column is column 0 (zero).

4D Ajax Framework Data Grid API Reference 23

Chapter 2 Data Grid API Reference

` In this example we will hide column 2. Column 2 is the Last name

field and it usually appears to the right of the First name field.
var myGrid = new dax_dataGrid('People', null);
myGrid.go();
myGrid.hideColumn(2);

Note The Control Column is column 0 because it was set to true by default
when the Data Grid was created.

Show column based on column number:

myGrid.showColumn(colNum);
„ colNum - The number of the column starting from the left side of
the Data Grid. Numbering begins at 0 (zero) so the left-most
column is column 0 (zero).

` After executing the code in the example shown above for

.hideColumn(), call this code at a later time to make the same column
reappear.
myGrid.showColumn(2);

24 4D Ajax Framework Data Grid API Reference

 Presentation

Get and Set Column

width
Note These commands should be made after the .go(); call, since columns are
not initialized before then.

„ To set column width in pixels:

myGrid.setColumnWidth(colNum, width);
„ colNum - The number of the column starting from the left side of
the Data Grid. Numbering begins at 0 (zero) so the left-most
column is column 0 (zero).
„ width - Width to set the column in pixels.

` This example will set the 3rd column from the left to a width of 150
pixels:
myGrid = new dax_dataGrid('People',null);
myGrid.go();
myGrid.setColumnWidth(2, 150);
„ To get column width in pixels:
var myColumnWidth = myGrid.getColumnWidth(colNum);
„ colNum - The number of the column starting from the left side of
the Data Grid. Numbering begins at 0 (zero) so the left-most
column is column 0 (zero).

` In this example will return the width of the 3rd column from the left:
var myColumnWidth = myGrid.getColumnWidth(2);

Allow user resizing This command allows or prohibits user resizing of columns with click
& drag interface:
myGrid.allowColumnResize(allowColumnResize);
„ allowColumnResize - Boolean. Set to True to allow column resizing.
Set to False otherwise.

User resizing is allowed by default.

` This example will allow user resizing of the columns:

myGrid.allowColumnResize(true);

4D Ajax Framework Data Grid API Reference 25

Chapter 2 Data Grid API Reference

Query
Query-related commands reside here.

New Query, Add Create a new query using the following command:
Query, and Run .newQuery();
Query
Then add and define the query conditions using the following
command:
.addQuery(field name, operator, value, and/or flag);
„ field name - String, name of the field to query.

„ operator - String, representing the operator. Examples are:

1) '=' (equal)
2) '#' (not equal)
3) '<' (less than)
4) '>' (more than)
5) '<=' (less than or equal to)
6) '>=' (more than or equal to)
„ value - String, representing the value evaluating the query condi-
tion.
„ and/or flag - String, linking queries with and or or. Values are 'and'
or 'or'.

Finally, when the query is ready to be executed, use the following:

.runQuery();
` This example will display records where the First name is Steve or the
Last name is Atom.
myGrid = new dax_dataGrid('People');
myGrid.showStatusBar(true);
myGrid.go();

// Create, build, and run query

myGrid.newQuery();
myGrid.addQuery('First', '=', 'Steve', 'or');
myGrid.addQuery('Last', '=', 'Atom');
myGrid.runQuery();

26 4D Ajax Framework Data Grid API Reference

 Query

Send custom values Send custom value names and pairs to the back end using the
to 4D following:
myGrid.addCustomValue(name, value);
„ name - String, name of the custom value.

„ value - Value of custom value.

Clear custom values using the following:

myGrid.clearCustomValues();
These values are retrieved by the GET WEB FORM VALUES command in
4D.

` This is a block of code that would perform a query during the user click
of an input button.

JavaScript portion:
// clear all existing values
myGrid.clearCustomValues();

// get values from input fields

var myCity = $('myCity').value;
var myState = $('myState').value;

// add values to the query

myGrid.addCustomValue('myCity', myCity);
myGrid.addCustomValue('myState', myState);

// run query with stored custom values to 4D

myGrid.runQuery();

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

Get custom values Use this command to return information from 4D back to the browser:
from 4D myCustomValues = myGrid.getCustomValuesFrom4D();
Note A set of web variables are passed from 4D to the front end using the 4D
method Dax_Dev_SetCustomVariables. This method can pass variables
to the front end during the following Developer Hooks:
Dax_DevHook_OnQuery (non-DCS support only)
Dax_DevHook_QueryFilter (non-DCS support only)
Dax_DevHook_DCS_SetSelection (DCS support only)

4D Ajax Framework Data Grid API Reference 27

Chapter 2 Data Grid API Reference

Dax_Dev_SetCustomVariables passes two text arrays to the front end:

$1 - Pointer to a Text Array containing variable names
$2 - Pointer to a Text Array containing variable values

Example:
ARRAY TEXT($varNames_at;3)
ARRAY TEXT($varValues_at;3)
$varNames_at{1}:="v1"
$varNames_at{2}:="v2"
$varNames_at{3}:="v3"
$varValues_at{1}:="aaa"
$varValues_at{2}:="bbb"
$varValues_at{3}:="ccc"
DAX_Dev_SetCustomVariables (->$varNames_at;->$varValues_at)

Important:
1. The size of the 2 arrays must be the same, otherwise, the size of the
value array will be adjust to the size of the name array.
2. If the method is called more than once, the one before the last
execution will be used.

On the front end side, the object received has the following 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

` Here is a portion of code where the Data Grid is retrieving custom

values from 4D to process column totals in the footer.
//Fill in the footer row with the custom value returned
from the backend.
myDataGrid.onBeforeDataDisplay = function() {
var custValue = this.getCustomValuesFrom4D();
var len = custValue.length;
for (var i=0; i<len; i++){
this.setCellValue (realRowNumber, i+1, 'Total of<br>'
+ custValue[i].value);
}
};

28 4D Ajax Framework Data Grid API Reference

 Query

Note This example can be further inspected in the Header and Footer example
of the Data Grid sample database,

Query all records Use this command to query all records in the Data Grid.
myGrid.queryAllRecords();
` This call will cause the Data Grid to display all records.
myGrid.queryAllRecords();

Max number of Use the command to set the maximum amount of characters 4D will
characters per field send per field.
myGrid.querySetMaxChar(number of characters);
„ number of characters - Integer, representing the max number of
characters 4D will send per field.

` In this example the maximum number of characters a field can display

is 15.
myGrid.querySetMaxChar(15);

Sort Sort records using the following:

myGrid.sort(field, order);
„ field - field name or id

„ order - (optional) 'asc' for ascending order or 'desc' for descending

order. Default value is 'asc'.

` In this example the First name field is sorted in ascending order.

myGrid = new dax_dataGrid('People');
myGrid.go();

// Sort
myGrid.sort('First', 'asc');

On Before and On Here are two events that can be used before or after sorting occurs.
After Sort
Before sorting:
myGrid.onBeforeSort = function() { };
After sorting:
myGrid.onAfterSort = function() { };

4D Ajax Framework Data Grid API Reference 29

Chapter 2 Data Grid API Reference

Before data display This event occurs when data arrives from 4D, but it's not displayed yet.
This would be an ideal time to perform data manipulation before it
gets displayed on the Grid.
myGrid.onBeforeDataDisplay = function() { };
Here is a recommendation of commands to consider executing during
this event:
„ getParsedDataValue
„ setParsedDataValue
„ getCustomValuesFrom4D

Check values before Get values before they are displayed:

display myGrid.getParsedDataValue(record (row), field
(column));
where record and field are integers that start from 0. Record & field
correspond to row & column number.

Modify values Change values before they are displayed:

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.

` This example will get data back from 4D, and capitalize every true
value in the [Employee]IsManager field. This happens before data is
displayed inside onBeforeDataDisplay handler.
// declare Data Grid variable
var myGrid;

// event that fires when user is successfuly logged in

function dax_loginSuccess() {

// create the grid as a floating window

myGrid = new dax_dataGrid('Employee');

// loop through values of [Employee]isManager field and make text

capitalized if employee is a manager
myGrid.onBeforeDataDisplay = function() {

// find column number for [Employee]isManager field

var fieldId = dax_getField('Employee', 'IsManager').fieldid;
var columnNumber = this.getColumnByFieldId(fieldId);

30 4D Ajax Framework Data Grid API Reference

 Selection

// since this grid has an extra column at the beginning (control

column), subtract one to get right column number for
get/setParsedDataValue
// same should be done if locked columns are present on the left
side
columnNumber--;

// loop through all received records

for (var recordCount = 0; recordCount <
this.getParsedDataRecordCount(); recordCount++) {

// get value
var value = this.getParsedDataValue(recordCount, columnNumber);

// if value is true, make it uppercase

if (value == 'true') {
value = value.toUpperCase();
this.setParsedDataValue(recordCount, columnNumber, value);
}
}
}
// initialize and show grid
myGrid.go();
}

Get number of Use this command to get the number of records returned from 4D.
returned records myGrid.getParsedDataRecordCount();
` This example will get the number of records from 4D and display it in
an alert message. This number should match the number of records
displayed in the Status Bar.
myGrid = new dax_dataGrid('People');
// Show Status Bar to display number records
myGrid.showStatusBar(true);
myGrid.go();

// Get number of returned records during onDataLoad event

myGrid.onDataLoad = function() {
var reCount = myGrid.getParsedDataRecordCount();
alert(reCount);

Selection
Select row by record Highlight a row based on its Record ID.
id myGrid.selectRowByRecordId(recordId);
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

4D Ajax Framework Data Grid API Reference 31

Chapter 2 Data Grid API Reference

` This example will highlight a record with ID [1][2]. The record is

highlighted during the onDataLoad event since records do not exist
until this point in time.
myGrid = new dax_dataGrid('People', null);
myGrid.go();

// Select Record [1][2] during the onDataLoad event

myGrid.onDataLoad = function() {
myGrid.selectRowByRecordId('[1][2]');
}

Select row by Select a row based on its row number.

number myGrid.selectRow(rowNumber);
„ rowNumber - Integer, representing the row number. Numbering
begins at zero so the top-most row (the header) is denoted as row 0
(zero).

Note The header, however, cannot be highlighted by this command.

` In this example row 2 is selected.

var myGrid = new dax_dataGrid('People', null);
myGrid.go();
// Select Row 2
myGrid.selectRow(2);

Add, remove, and Use these commands to add, remove, or clear records to a selection.
clear
„ To add a record to a selection:
myGrid.addRecordToSelection(recordId);
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

32 4D Ajax Framework Data Grid API Reference

 Selection

„ To remove a record from the selection:

myGrid.removeRecordFromSelection(recordId);
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.
„ To clear all records from the selection:
myGrid.removeAllRecordsFromSelection();

Delete selection myGrid.deleteSelectedRecords(skipConfirmation);

` In this example we delete a record with the skipConfirmation parameter
set to False.
var myGrid = new dax_dataGrid('People', null);
myGrid.go();

// Add 1 record to the Selection

myGrid.addRecordToSelection(1,6);

// Delete the Selection. skipConfirmation set to false.

myGrid.deleteSelectedRecords(false);

Selection Mode Defines how many rows can be selected at a time with a row click.
myGrid.setSelectionMode(selectionMode);

4D Ajax Framework Data Grid API Reference 33

Chapter 2 Data Grid API Reference

„ selectionMode - Possible values are 'multi', 'single', or 'none'. 'multi'

is chosen by default.
- multi - Multiple records can be selected at the same time. Use CTRL
key (PC) or CMD key (Mac) to add or remove records from the Sel-
ection.
- single - Only one record can be selected at the time.
- none - No selection is allowed.

Note These values are case sensitive. Thus, they must be lower-case.

` This example sets the Selection Mode to 'multi'.

var myGrid = new dax_dataGrid('People', null);
myGrid.go();
// Set to Multi Selection Mode
myGrid.setSelectionMode('multi');

Drag & drop

Events Three Drag and Drop events are defined for developers:

„ The ondragover event is when a cell is held and is hovering over an

area to be dropped. Use this command to provide a visual indication
that the user's mouse is hovering over a cell. Use CSS style class names
to provide the visual queue.
myGrid.ondragover(cellRef); -> return CSS style class
name to override default, or null to skip visual
indication

34 4D Ajax Framework Data Grid API Reference

 Drag & drop

„ The ondragout event is when the original cell is first grabbed.

myGrid.ondragout(cellRef);
„ The ondragrelease event is when the original cell is dropped into the
target area.
myGrid.ondragrelease(cellRef);
` This is an example of Drag and Drop between two Data Grids. Cells
from gridTwo can be dropped into gridOne. When a cell is hovering
over another, the target cell is highlighted in red. When a cell is
dropped, alerts appear announcing the statistics (row number, column
number, cell value) of the original and target cells.

JavaScript portion of code:

var gridOne;
var gridTwo;

function daxLoginSuccess() {

// create first grid, this will be the target for drag & drop
action
gridOne = new dax_dataGrid ('Employee', $('gridOne'), 1, 0,
false);
gridOne.setSelectionMode('none');
// give custom CSS class to visually show if cell is selectable
gridOne.ondragover = onDragOverEvent;

// process drag & drop

gridOne.ondragrelease = onDragReleaseEvent;

gridOne.go();

// create second grid, cells will be dragged from here

gridTwo = new dax_dataGrid ('Branch', $('gridTwo'), 1, 0, false);
// disable selection
gridTwo.setSelectionMode('none');
gridTwo.go();
// make 6th column draggable
gridTwo.setDragCells(null, 5, true);
}

// 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) {

4D Ajax Framework Data Grid API Reference 35

Chapter 2 Data Grid API Reference

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>

Set cells as drop A Drop Zone is an area where an object can be drag and dropped into.
zone Use this command to set specific rows or columns as a drop zone.
myGrid.setDropCells(row, column, isDroppable)
„ row - Specify row to be set as a drop zone. Pass null for all rows to be
set as a drop zone. Numbering begins at 0 (zero) so the top-most
row (the header) is row 0 (zero).
„ column - Specify column to be set as a drop zone. Pass null for all
columns to be set as a drop zone. Numbering begins at 0 (zero) so
the left-most column is column 0 (zero).
„ isDroppable - Boolean. Enter True to set area as droppable. Enter
False otherwise.

` Row 3 is a drop zone.

myGrid.setDropCells(3, null, True);

` Column 4 is a drop zone.

myGrid.setDropCells(null, 4, True);

` Cell (3,4) is a drop zone.

myGrid.setDropCells(3, 4, True);

` All rows and columns are drop zones.

myGrid.setDropCells(null, null, True);

36 4D Ajax Framework Data Grid API Reference

 Window

Set cell as draggable Set cells, rows, or columns as draggable using this command.
myGrid.setDragCells(row, column, isDraggable);
„ row - Specify row to be set as a draggable. Pass null for all rows to be
set as a drop zone. Numbering begins at 0 (zero) so the top-most
row (the header) is row 0 (zero).
„ column - Specify column to be set as a draggable. Pass null for all
columns to be set as a drop zone. Numbering begins at 0 (zero) so
the left-most column is column 0 (zero).
„ isDraggable - Boolean. Enter True to set area as draggable. Enter
False otherwise.

Draggable cells will not support mouse hover and selection mechanics.
No cells are set as draggable by default.

During the drag & drop process, source cell is also accessible through:
dax_bridge.hoverDragging.dragObjectSource

Set draggable To make any object on the HTML page draggable, call this command.
object dax_setDraggable(draggableObject);
This will not move the actual object, but create a floating copy when
dragged.

Window
Status bar The Status Bar is the bar at the bottom of the Data Grid displaying
status information.

4D Ajax Framework Data Grid API Reference 37

Chapter 2 Data Grid API Reference

By default the Status Bar displays generic information such as the total
number of records or the amount of records currently selected.

Show or hide status bar using the following command.

myGrid.showStatusBar(boolean);
` This example will hide the Status Bar. The status bar is
hideable/showable even after grid is drawn, but hiding it before .go()
phase is more efficient since no redraw is required.
var myGrid = new dax_dataGrid ('Employee');

// hide the Status Bar

myGrid.showStatusBar(false);

myGrid.go();

Show message Use this command to display values in the Status Bar.
myGrid.showStatusMessage(message);
` In this example we will get the value of a cell and display it in the
Status Bar. We get the cell value during the onDataLoad event because
the Data Grid cells do not have values until this event occurs.
var myGrid = new dax_dataGrid('People', null);
myGrid.showStatusBar(true);
myGrid.go();

myGrid.onDataLoad = function() {
var cellValue = myGrid.getCellValue (2, 3);
myGrid.showStatusMessage(cellValue);
}

38 4D Ajax Framework Data Grid API Reference

 Window

Toolbar The Toolbar is a bar above the Data Grid that features the following
capabilities:
„ Create a new record

„ Delete selected record(s)

„ Search based on field

To show or hide the Toolbar use the following commands

myGrid.showToolbar([Toolbar feature]);
myGrid.hideToolbar([Toolbar feature]);
Toolbar feature - Values can be:
„ 'createrecord' - This will display a button that allows users to create
new records.
„ 'deleterecords' - This is will display a button that allows users to
delete the records that are selected.
„ 'search' - This will display the

Note The features are displayed on the Data Grid from left to right in the
order they are listed in the .showToolbar command.

` This example will display all Toolbar features.

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

4D Ajax Framework Data Grid API Reference 39

Chapter 2 Data Grid API Reference

Preset queries
Preset queries are queries created in the control panel via the Query
Manager tab. These queries can be represented as Sidebars or Tabs.

Sidebar The Sidebar is an area on the Data Grid displaying the Preset Queries a
list.

Show and hide Sidebar To show or hide the Sidebar:

myGrid.showQuerySidebar(position);
myGrid.hideSidebar();
„ position - (optional) 'left' or 'right'. The Sidebar appears to the left by
default.

Note Field(s) used for Dynamic Queries must have at least one of the
visibility checkboxes turned on in the control panel.

` This example displays the Sidebar on the left.

myGrid = new dax_dataGrid('People');
myGrid.go();
// Show Sidebar
myGrid.showQuerySidebar();

Tabs Preset Queries can also appear as Tabs above the row and column area
of the Data Grid.

Show and hide Tabs To show or hide the Tabs:

myGrid.showQueryTabs();
myGrid.hideQueryTabs();

40 4D Ajax Framework Data Grid API Reference

 Preset queries

` This example will display Preset Queries as Tabs:

myGrid.showQueryTabs();

Preset queries To run individual Preset Queries by query name:

myGrid.runPresetQuery (name, field);
„ name - String, name given to the Preset Query as denoted in the
Query Manager tab within the Client.
„ field - Field name, needed only for unique value queries.

` This example will run a Preset Query named B which will display all
records in the Last name field which start with the letter B.
myGrid = new dax_dataGrid('People');
myGrid.go();

//
myGrid.runPresetQuery ('B');

Below is a screenshot of the query as seen in the Query Manager Tab in

the Client environment.

4D Ajax Framework Data Grid API Reference 41

Chapter 2 Data Grid API Reference

Editor
The Editor is a sheet that appears that allows users to modify values or
add values for a new record in the Data Grid.

New record Use the new record command to display the Editor sheet for adding a
new record.
myGrid.editorNewRecord();
` This example displays the Editor sheet for a new record:
myGrid = new dax_dataGrid('People');
myGrid.go();

// Display Editor sheet for a new record

myGrid.editorNewRecord();

Edit record Use the following command to modify an existing record using the
Editor sheet, based on its record ID.
myGrid.editorEditRecord(recordId);
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

42 4D Ajax Framework Data Grid API Reference

 Inline editing

` This example will display the Editor sheet for the record with ID [1][2]:
myGrid.editorEditRecord('[1][2]');

Allow editor This command disables or enables the record editor to appear when
users double click on a row. The record editor is enabled by default.
myDataGrid.allowEditor(boolean);
„ boolean - Set true to enable the record editor. Set false otherwise.

Inline editing
Typically, to modify records the user would double click on a record
and an Editor sheet would appear allowing them to edit field values.
Inline Editing, on the other hand, allows the user to modify or add
records in the Data Grid without having to do so in another sheet, but
in the Data Grid itself.

The Inline Editor supports:

„ Choice Lists: Fields that are assigned Choice Lists in 4D automatically
behave in the same way in the Data Grid.
„ Keyboard Shortcuts:
„ Hit the Esc key to Cancel editing a record.
„ Hit the Tab key to go to the next field.

4D Ajax Framework Data Grid API Reference 43

Chapter 2 Data Grid API Reference

„ Hit the Return key to Save the record.

„ A Calendar Picker appears for Date fields.

„ Boolean fields appear as check boxes. The values depend on the for-
matting rules selected in the Control Panel.
„ Callbacks: 4D Callbacks are supported during Inline Editing.

Allow inline editing myGrid.allowInlineEditing(boolean);

„ boolean - Set to true to allow Inline Editing. Set to False otherwise.

` In this example Inline Editing is set to true. Below is a screen shot of a

record being edited.
myGrid.allowInlineEditing(true);

Initiate inline To initiate Inline Editing programmatically use the following

editing command.
myGrid.inlineEdit(editRow, recordId);
Pass one or none of the parameters:
„ editRow - Integer, representing the row number to edit. Number
starts from 0 (zero).
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

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

` Edit 4th row:

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

44 4D Ajax Framework Data Grid API Reference

 Events

` Edit Record ID [3][4]:

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

` Create a new record through Inline Editing:

myDataGrid.inlineEdit();

Save edited record Use this command to programmatically save the current record that is
being edited through Inline Editing.
myGrid.inlineEditSave();

Cancel inline editing Use this command to programmatically clear the current record that is
being edited through Inline Editing.
myGrid.inlineEditClear();

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

Each time a column is clicked use:

myGrid.onDataColumnClick = function myFunction(column,
fieldReference);
Each time a row is clicked use:
myGrid.onDataRowClick = function myFunction(row,
recordId);
Each time a cell is clicked use:
myGrid.onDataCellClick = function myFunction(row,
column, recordId, fieldReference);
Parameters:
„ column and row are integers, starting from 0.
„ fieldReference - field object, with fieldid, fieldalias, etc attributes.
„ recordId - String. Unique value defined for each record denoted by
two values x and y in the format '[x][y]'.

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

4D Ajax Framework Data Grid API Reference 45

Chapter 2 Data Grid API Reference

` In this example data in each cell is being converted to UPPERCASE

each time it is clicked. The onDataCellClick event is used to catch the
user clicks.
var myGrid = new dax_dataGrid('People');
myGrid.go();

// when cell is clicked, show the value in status bar

myGrid.onDataCellClick = function(row, column) {

// get cell value

var myCellValue = myGrid.getCellValue(row, column);

// convert value to upper case

myCellValue = myCellValue.toUpperCase();

// place the value back into the cell

myGrid.setCellValue(row, column, myCellValue);
}

On data load This is the time when data populates the Data Grid. Note that many
other Data Grid commands are data dependent, so in many cases
onDataLoad would be the only appropriate time to use them.
myGrid.onDataLoad = function() { };
` In this example we will get the value of a cell and display it in the
Status Bar. We get the cell value during the onDataLoad event because
the Data Grid cells do not have values until this event occurs.
var myGrid = new dax_dataGrid('People', null);
myGrid.showStatusBar(true);
myGrid.go();

myGrid.onDataLoad = function() {
var cellValue = myGrid.getCellValue (2, 3);
myGrid.showStatusMessage(cellValue);
}

46 4D Ajax Framework Data Grid API Reference

 Events

Before and After When the mouse hovers over a 'View Image' link for a picture field, a
Hover preview of that image appears. The following two events fire for this
action, onBeforeHover and onAfterHover. They are shown below.

This event fires when the mouse first hovers over the link.
myGrid.onBeforeHover = function() { };
This event fires when the mouse hovers away from the link.
myGrid.onAfterHover = function() { };
` In this example, a blank image in a separate <div> displays the image
that is previewed when it is being hovered over. When the mouse
leaves the link, the <div> becomes blank again.
This is the JavaScript code in onAfterInit:
myGrid = new dax_dataGrid('Contacts', $('mydiv'), 1, 0,
false);
myGrid.enablePicturePreview(true);
myGrid.go();
myGrid.allowEditor(false);

// Display the contents of the image being hovered into the

image element
// on the page with ID "mypreview"
myGrid.onBeforeHover = function(athis){
var imgcontainer = document.getElementById('mypreview');
imgcontainer.src = athis.aContent;
imgcontainer.width = athis.parent.picWidth;
imgcontainer.height = athis.parent.picHeight;
}

// Display nothing in the image element that has the ID

"mypreview" when
// the mouse hovers away from the link.
myGrid.onAfterHover = function(athis){
var imgcontainer = document.getElementById('mypreview');
imgcontainer.src = 'blank.png';
}

This is the HTML with the <div> containing the image element with
ID "mypreview".
<div style="float: right; width: 213px; margin-left: 35px;
margin-top: 35px;">
<img id="mypreview" src="blank.png" width="0" height="0"/>
</div>

4D Ajax Framework Data Grid API Reference 47

Chapter 2 Data Grid API Reference

CSS Styling
Change the look of the Data Grid's rows, columns, and cells using CSS.
There are two ways of approaching this:
„ Override the framework's existing styling

„ Use JavaScript to dynamically assign styling

Override Styling To override the framework's CSS styling, it helps to know the following
CSS classes available based on data type:
„ .datanumeric - Numeric fields
„ .datatext - Text fields
„ .datatime - Time fields
„ .datadate - Date fields
„ .databoolean - Boolean fields
„ .dataheader - Headers

Note The point here is that the framework already has CSS styling defined
for .dax_datagrid. To override the existing styling, define CSS classes
prefixed with .dax_datagrid.

` To override the 'text-align' attributes for the Data Grid add this CSS
code:
<style type="text/css">

.dax_datagrid .datanumeric, .dax_datagrid .datatext{

text-align:center;
}

</style>

Note .dax_datagrid is prefixed before these data types are specified.

This code would override the text-align attributes for all numeric and
text fields in the grid.

Set entire grid class This command appends the class name to the grid. This means that
any style that starts with .myClassName can be applied for this specific
grid.
myGrid.setGridClass(className);

48 4D Ajax Framework Data Grid API Reference

 CSS Styling

` Following the same example attempted above, setGridClass can be used

if you prefer to define your own styling instead of overriding the fra-
mework's CSS styling for .dax_datagrid.

CSS portion:
<style type="text/css">
.style1 .datatext, .style1 .datanumeric {font-size: 11pt;
text-align:center; font-weight:bold;}
</style>

JavaScript portion:
myDataGrid.setGridClass('style1');

Like the previous example, this sample will make numeric and text
fields center aligned (as well as having bolder text and a modified font
size).

Assign classes to The following commands change CSS styling more dynamically (for
Rows, Columns, and example, on a user click).
Cells
„ Change CSS for a row:
myGrid.setRowStyle(row, styleName,
alternateRowStyleName, useAsDefault);
„ row - Integer, row number.

„ styleName - String, name of CSS style to be applied.

„ alternateRowStyleName - (optional) String, name of CSS style to be
applied to alternate row.
„ useAsDefault - (optional)
„ Change CSS for a column:
myGrid.setColumnStyle(column, styleName,
alternateRowStyleName, useAsDefault);
„ column - Integer, column number.

„ styleName - String, name of CSS style to be applied.

„ alternateRowStyleName - (optional) String, name of CSS style to be
applied to alternate row.
„ useAsDefault - (optional)

4D Ajax Framework Data Grid API Reference 49

Chapter 2 Data Grid API Reference

„ Change CSS for a cell:

myGrid.setCellStyle(row, column, styleName,
alternateRowStyleName, useAsDefault);
„ row - Integer, row number.

„ column - Integer, column number.

„ alternateRowStyleName - String, name of CSS style to be applied to
alternate row.
„ useAsDefault - (optional)

` This example will set CSS styling for row, column, and cell based on a
user click. Event onDataCellClick is used to catch the user clicks.
Buttons are also used to change grid class using .setGridClass()

JavaScript code for dax_loginSuccess():

function dax_loginSuccess() {
var lastSelectedRow = 0;
var lastSelectedColumn = 0;

var myGrid = new dax_dataGrid('People', $('DataGridDiv'));

myGrid.go();

myGrid.setSelectionMode('none');

myGrid.onDataCellClick = function(row, column) {

// clear previous styles

myGrid.setRowStyle(lastSelectedRow, '');
myGrid.setColumnStyle(lastSelectedColumn, '');
myGrid.setCellStyle(lastSelectedRow, lastSelectedColumn, '');

//update values
lastSelectedRow = row;
lastSelectedColumn = column;

// set values
myGrid.setRowStyle(row, 'redColor');
myGrid.setColumnStyle(column, 'greenColor');
myGrid.setCellStyle(row, column, 'blueColor');
}

function button_changeGridStyle1() {
// check if grid exists. If it doesn't, skip the rest of the method
if (!myGrid)
return false;

// Set the Data Grid's CSS class to style inverseStyle.

myGrid.setGridClass('inverseStyle');
}

50 4D Ajax Framework Data Grid API Reference

 CSS Styling

function button_changeGridStyle2() {
// check if grid exists. If it doesn't, skip the rest of the method
if (!myGrid)
return false;

// The empty space here will equate to nothing, setting the Data
Grid's // CSS class to default settings.
myGrid.setGridClass(' ');

// Assign events to the buttons

$('changeGridStyle1').onclick = button_changeGridStyle1;
$('changeGridStyle2').onclick = button_changeGridStyle2;

CSS code. Default Data Grid CSS class .dax_datagrid and CSS class
.inverseStyle are defined here:
<style type="text/css">
.dax_datagrid .redColor {
background-color: red;
}
.dax_datagrid .greenColor {
background-color: green;
}
.dax_datagrid .blueColor {
background-color: blue;
}
.inverseStyle .redColor {
background-color: purple;
}
.inverseStyle .greenColor {
background-color: yellow;
}
.inverseStyle .blueColor {
background-color: silver;
}
</style>

Code within <Body>. The buttons used to change the Data Grid's CSS
class as a whole are defined here:
<input class="myButton" type="button" id="changeGridStyle1"
value="Change style" />

4D Ajax Framework Data Grid API Reference 51

Chapter 2 Data Grid API Reference

<input class="myButton" type="button" id="changeGridStyle2"

value="Restore style" />

Based on a user click, we see:

„ Cell style background color set to blue.
„ Row style background color set to red.
„ Column style background color set to green

52 4D Ajax Framework Data Grid API Reference

 CSS Styling

Hitting the Change Style button uses the .setGridClass() command to

do the following:
„ Cell style background color set to silver
„ Row style background color set to purple.
„ Column style background color set to yellow.

Hitting the Restore Style button will then use .setGridClass() to restore
the CSS to it's default settings.

4D Ajax Framework Data Grid API Reference 53

Chapter 2 Data Grid API Reference

54 4D Ajax Framework Data Grid API Reference