The DataEntryGrid control

The DataEntryGrid control

The DataEntryGrid control

It is a datagrid with which a user can enter, edit or delete information. The control operates in two modes: 

1) Single list mode, where it stores the detail information into a column of type multiple lines of text (note: the column must use Plain Text format). In this case, the data are saved in XML format.

2) Multiple list mode, where the data are stored in a separate list (using list query to load data and then save them).  See master detail using DataEntryGrid control tutorial for details.


 

Designer Properties

Type : DataEntryGrid

Name

Provides a unique name for the control.

Binding

Indicates if the control is :

1) Unbound. This should be the case the control stores its data in a separate list. See master detail using DataEntryGrid control tutorial for details.

2) Bound to a list column: When bound to a multiline text column (plain text), it will save the detail rows in XML format.


Enabled for new records

Sets if the control will be enabled or disabled when the forms handles a new record

Enabled for existing records

Sets if the control will be enabled or disabled when the forms handles an existing record



Required

Marks the cotnrol as Required.

By default, the system recognizes required fields and marks them with this flag. Additionaly, controls can be marked as required event if the bound column is not.



Enabled Formula

Set an expression then will be evaluated during run-time and enable or disable the control.

The expression must be in javascript and should return a boolean value.

Dependencies between controls are automatically identified and the expression is re-calculated every time a control affecting the formula changes.

Example :


Code


form.GetControl("c_Status").GetValue() != "Open" && form.UserInGroup("Administrators")





Visibility Formula

Define a valid formula (using javascript) that will be evaluated during runtime to show or hide the control.

The expression should return a boolean value.

For example :


Code


form.FieldValue("c_Status") != "Rejected" || form.UserID() == "1"




 

Value Properties

Value provided by the user

With this choice made, the dataentrygrid is not bound to another list but its data are saved within the same list in a multiple line plain text column.

List Query

A predefined list query is bound to the value of the control. So during form initialization, the specified list query is executed and binds the dataentry grid






 

Layout Properties



Width

Defines the width of the control.

When the value is zero, the maximum allowed width will be used.



Height

Defines the control height.

If the value is zero, the height property will not be set. 



H.Alignment

Defines the horizontal alignment of the parent cell (values : left, right, center)

V.Alignment

Defines the vertical alignment of the parent cell (values : top, bottom, center)


Fore Color

Not applicable

Back Color

Not applicable 


Cell Color

Defines the color of the parent cell.



Font Size

Declares the font size of the text



Margin

Sets the margin applied to the control, that is, the spacing between the control and the cell borders.



Font Bold

Changes the weight of the font used

Italics

Changes the font style for the control text

 



 

Extra Configuration

AllowInsert


Allows new records to be added in the grid


AllowUpdate

Allows users to update records

AllowDelete

Allows users to delete records from the grid

UseKeyNavigation

This property (true/false) provides the user with the ability to jump forward from cell to cell using the TAB key, or the SHIFT+TAB for backward way.  

ButtonsHorizontalPosition

Sets the Horizontal positioning of the New/Delete buttons in relation to the grid.

ButtonsVerticalPosition

Sets the Vertical positioning of the New/Delete buttons in relation to the grid.

ButtonsPositioningMode

Sets the positioning mode of the New/Delete buttons. 'Inline' means that the buttons will be displayed in an absolute positioning mode without taking extra space on the bottom (or top depending on the alignment) of the grid. Useful when you want to add extra controls next to the buttons.

InsertButtonImageURL

Render an image instead of a button for the 'New Record' button.

DeleteButtonImageURL

Render an image instead of a button for the 'Delete Record' button.

DataItemChangedScript



You can write a script that will be executed once a dataitem value is changed. The event is only raised when using existing controls. The 'fieldName' parameter contains the property name that raised the change. You can get the underlying dataitem using the control.InputControl.GetSelectedItem() method and you can change the value of a property in the item using the item.SetValue(fieldName, value) method.

SelectionChangedScript

You can write a script that will be executed once the selection is changed. The 'item' variable is available containing the item selected or null if the grid has no item selected.

Example:


Code


if(item != null)
{
 alert(item.Title);
} 


 


DataLoadedScript

You can write a script that will be executed once the data inside the datagrid is loaded (when the control is bound in a List Query). The 'items' variable is available containing the items retrieved.

This is the perfect time to make changes to the data loaded, before they are finally placed inside the DataEntryGrid control. 


Code


for (var i=0; i < items.length; i++)
{
   items[i].KPILookup = GetNameFromLookup(items[i].KPILookup);
}


 


LoadCompletedScript

Occurs AFTER the data has been placed inside the grid (assuming the control is bound to a List Query). The 'items' variable is available, containing the items retrieved.

 

CellEnteringEditScript

You can write a script that will be executed when a grid cell enters edit mode, providing the ability to close the cell and cancel the edit process. 

The 'e' object contains the event parameters, and you can set e.Cancel to true in order to cancel editing

 

e.FieldName is the name of the column that is currently being edited.

e.DataItem contains the currently selected record's data.

 

Example:  


Code
 


if (e.FieldName == 'Title' && e.DataItem.Description == 'Skip editing') {

   e.Cancel=true;

} 



 

ExistingControlCreatedScript  

You can write a script that will be executed once an existing control is created within an edit cell of the grid (applicable only in case you have fields with Type = Existing). This is useful when we want add extra manipulation on the control that is used to edit the data item.
The 'e' object contains the event parameters :

 

e.FieldName is the name of the column that is currently being edited.

e.DataItem is the actual record.

e.Control is the form control that is created within the cell.

 


Example:  

Code

if (e.FieldName == 'Title' && e.DataItem.ItemColor == 'Red') {
   e.Control.SetBackColor('red');
}

 

 

Fields

Add the fields of the data entry grid

Properties

Name : The name of the field. It should begin with a letter and only contain letters, numbers and the underscore character

Header : The field header

Type : The control type. Possible values are Textbox, DatePicker, Combobox, Checkbox, Existing, NoEdit (to make a non-editable, read-only field) 

ExistingControlName : When the control type is 'Existing' you can set the name of an existing control on the form (should normally be hidden and dedicated for this purpose). That control will be used in the data entry form.

Width :  The grid column width. Leave blank for Auto sizing.

DisplayFormat : Indicates the way the value will be presented inside the data grid. Possible values are:

- (denotes no formatting, displaying the value as-is),

ValueField or DisplayField for lookup controls (ID;#TITLE),

Date for date fields (can be used in conjunction with the FormatString property),

DateTime for date-time fields (can be used in conjunction with the FormatString property),

Number (can be used in conjunction with the FormatString property).


FormatString :  Sets the format for Date, DateTime and Number fields. For example #,##0.00 or MM/dd/yyyy

Required : Defines if the field is required

BackColor : The cell background color

ForeColor : The cell foreground color

FontBold :  The text weight

FontSize : The size of the font used

HAlign :  Sets the text's Horizontal Alignment. Possible values: - (default alignment), Left, Right, Center

Values :  Array of string values that will be used as the data source of the control when the type is ComboBox

DefaultFieldValue : Specifies the default value to be given to the field in new items. The value can contain expression that refers to another control, for example {c_Title} in order to retrieve text from the control named c_Title.

CustomCellTemplateFormula : You can define a custom javascript formula that is going to be evaluated on runtime to produce the cell content. Use data field names as variables, for example: '<b>' + Title.toUpperCase() + </b>'

ColumnFiltering : If selected, then the grid displays a drop-down menu when the user clicks this column, used for filtering purposes.

Values

Add Name/Value pairs to update item properties when the control is bound to a list. Values could be either static or calculated. (i.e. Name=Priority, Value=High or Name=Customer, Value={value:c_ID}. You can use the {ParentID} keyword for the value property to set the ID of the parent record (event if not saved yet).

Properties

Name : The column internal name

Value : The default value of the column. Set either static values or calculated values based on form controls (i.e. {value:Field1}). You can use the {ParentID} keyword for the value property to set the ID of the parent record (event if not saved yet).

 



 

RecordListQueries

Define additional List Queries that will be executed for each item record retrieved. These can be used to retrieve additional information, even from other lists, for each record in the DataEntryGrid.

 

Properties

 

ListQuery : The list query name.

SearchTargetField :  The internal column name of the query that we want to apply criteria.

SearchSourceField :  A field defined on the DataEntryGrid control, whose value will be used as a criteria to filter the list query results.

SearchOperator :  The criteria operator. Possible Values: BeginsWith, Contains, Equals, NotEquals, Greater, GreaterOrEqual, Less, LessOrEqual, IsNull, IsNotNull

SearchType :  The criteria type. Possible Values: Text, Counter, Lookup, DateTime, Number

InitScript :  This script will be executed for each item before executing the list query. The variable 'item' is available, containing the current record. You can write custom JS code, to possibly change a value in the record, before performing the actual list query.

CallbackScript : The script that will be executed, once the list query returns the results. The variables 'item' and 'result' are available. The item represents the current record and the result represents the list query results, based on the current record. Available properies : result.ErrorMessage, result.ListItems 

 

 

 


Script

Sets the script that will be executed at the value-change event of the control.

Example :


Code


var value = form.GetControl("c_Title").GetValue();

if (value == "Open") form.HideSection("Details");

else form.ShowSection("Details");



 



 

Extra Methods

 

ExportToExcel


As the name suggests, this function will export the data to an Excel file, ready to be saved or opened. The function accepts three parameters, described below:

ExportToExcel(array of columns, string file name, string sheet name) 

 

Columns should be an array of objects with "field" and "title" properties. If no columns are provided, all of the grid's visible columns will be exported.

Example:

Code


var grid = form.GetControl("c_Cases").InputControl;
 

var cols = [];
cols.push({field:"CaseNumber", title:"Case Number"});
cols.push({field:"Title", title:"Title"});
cols.push({field:"CaseType", title:"Case Type"});
cols.push({field:"CType", title:"Case Category"});
 

grid.ExportToExcel(cols, "Cases.xls", "Cases");

 



SelectRowByIndex

 


As the name suggests, this function will select a row on the DataEntryGrid. The function accepts one parameter, as described below:

SelectRowByIndex(integer theIndex) 

 

Example:

Code


form.GetControl("c_DataEntryGrid").InputControl.SelectRowByIndex(1);

 


RefreshGrid 

This method refreshes the grid's content.


Code


form.GetControl("c_GridName").InputControl.RefreshGrid();


  


AddNewRow(item)


As the name suggests, this function will add a new row on the DataEntryGrid. The function accepts one parameter (a new Object), as described below:

 

Example:

Code

 var item = new Object();

 item.Title = "TestTitle";

 item.Bank = "TestBank"; 


 form.GetControl("c_DataEntryGrid").InputControl.AddNewRow(item);



RunListQueries()


This function will run all the list queries that have been declared at the property of the DataEntryGrid named RecordListQueries. It works as described below:

 

Example:

Code


 form.GetControl("c_DataEntryGrid").InputControl.RunListQueries();

 


 

GetAllItems()

This function returns all items currently shown on the DataEntryGrid Control. You can also use SetValue, to programmatically change column values.

 

Example:


Code


// retrieving all items in the DataEntryGrid control
var thecvDset = form.GetControl("yourDataEntryGrid").InputControl.GetAllItems();

// looping through each item in the array
for (var i = 0; i < thecvDset.length; i++) {

    var theTitle = thecvDset[i].Title;

    // changing the Title column value in every row
    thecvDset[i].SetValue("Title", theTitle + "123");

}