# Table

## Overview

A **Table** object represents an individual table in a [Database Server](https://docs.servoy.com/reference/servoycore/object-model/database-server).

## File Structure

The properties for a Table are stored under in the [resources](https://docs.servoy.com/reference/servoy-developer/project-file-structure/workspace-folder/resources-directory) directory in a [Database Information (.dbi) File](https://docs.servoy.com/reference/servoy-developer/project-file-structure/workspace-folder/resources-directory/database-information-.dbi-files).

## Properties Summary

The following properties can be configured for a Table object

| Property                                | Summary                                                                   |
| --------------------------------------- | ------------------------------------------------------------------------- |
| [hiddenInDeveloper](#hiddenindeveloper) | Use this property to hide the table from the Servoy Developer environment |
| isMetadataTable                         | Returns whether table was flagged as metadata table                       |

## Events Summary

The following events can be handled for a Table object.

| Property                                                            | Summary                                                                                 |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [onRecordInsert](#onrecordinsert)                                   | occurs prior to a new record being inserted into the table                              |
| [onRecordUpdate](#onrecordupdate)                                   | occurs prior to an existing record being updated in the database                        |
| [onRecordDelete](#onrecorddelete)                                   | occurs prior to an existing record being deleted from the database                      |
| [afterRecordInsert](#afterrecordinsert)                             | occurs subsequent to a new record being inserted into the table                         |
| [afterRecordUpdate](#afterrecordupdate)                             | occurs subsequent to an existing record being updated in the database                   |
| [afterRecordDelete](#afterrecorddelete)                             | occurs subsequent to an existing record being deleted from the database                 |
| [onFoundSetRecordCreate](#onfoundsetrecordcreate)                   | occurs prior to a new record being created in the foundset                              |
| [onFoundSetFind](#onfoundsetfind)                                   | occurs prior to the foundset going into find mode                                       |
| [onFoundSetSearch](#onfoundsetsearch)                               | occurs prior to executing a search on the foundset                                      |
| [onFoundSetBeforeSelectionChange](#onfoundsetbeforeselectionchange) | occurs before the foundset selection changes                                            |
| [afterFoundSetRecordCreate](#afterfoundsetrecordcreate)             | occurs subsequent to the creation of a new record                                       |
| [afterFoundSetFind](#afterfoundsetfind)                             | occurs subsequent to entering find mode                                                 |
| [afterFoundSetSearch](#afterfoundsetsearch)                         | occurs subsequent to performing the search for a foundset                               |
| [onValidate](#onvalidate)                                           | occurs before an insert operation, it can block the insert operation by returning false |

## Properties Details

The following properties can be configured for a **Table** object

### hiddenInDeveloper

Use this property to hide the table from the Servoy Developer environment. When set to true, the table will be skipped when loading information about the database schema.

Type: [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string)

Required: `false`

## Events Details

### onRecordInsert

This event is a pre-trigger for a record insert. It is fired during a save event and gives the developer a chance to validate the record or make changes. Return false or assign error markers to prevent the insert.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be inserted
* **recordMarkers:** [JSRecordMarkers](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecordmarkers) - The object where all the problems can be reported
* **stateObject:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) - An object that a user can give to validateRecord for extra state (optional, can be null).

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the record from being inserted.

**Example**

```javascript
function onRecordInsert(record, recordMarkers, stateObject) {
	// TODO Auto-generated method stub
	var valid = true;
	if (record.mynumber > 10) {
		recordMarkers.report("mynumber must be greater then 10", "mynumber", LOGGINGLEVEL.ERROR);
		valid = true; // keep the valid on true if you just report through the recordMarkers and want to also execute other oninsert methods.;
	}

	// return boolean to indicate success
	return valid;
}
```

### onRecordUpdate

This event is a pre-trigger for a record update. It is fired during a save event and gives the developer a chance to validate the record to be updated. Return false or assign error markers to prevent the update.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be updated
* **recordMarkers:** [JSRecordMarkers](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecordmarkers) - The object where all the problems can be reported
* **stateObject:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) - An object that a user can give to validateRecord for extra state (optional, can be null).

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the record from being update.

**Example**

```javascript
function onRecordUpdate(record, recordMarkers, stateObject) {
	// TODO Auto-generated method stub
	var valid = true;
	if (record.mynumber > 10) {
		recordMarkers.report("mynumber must be greater then 10", "mynumber", LOGGINGLEVEL.ERROR);
		valid = true; // keep the valid on true if you just report through the recordMarkers and want to also execute other oninsert methods.
	}

	// return boolean to indicate success
	return valid;
}
```

### onRecordDelete

This event is a pre-trigger for a record deletion. It is fired during a save event and gives the developer a chance to validate the record to be daleted. Return false or assign error markers to prevent the record to be deleted.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be deleted

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the record from being deleted.

**Example**

```javascript
function onRecordDelete(record) {
	// TODO Auto-generated method stub
	var valid = true;
	// test if it is valid.

	// throw exception to pass info to handler, will be returned in record.exception.getValue() when record.exception is a DataException
	if (!valid) throw 'cannot delete'

	// return boolean to indicate success
	return true
}
```

### afterRecordInsert

This event is a record after-insert trigger. This is an ideal mechanism to update the data model after data is known to have been inserted.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be inserted

**Example**

```javascript
function afterRecordInsert(record) {
    if(record.projects_to_projects_users.newRecord()){              // create a link record
        record.projects_to_projects_users.user_id = globals.currentUserID;  // associate to current user
        databaseManager.saveData();
    }
}
```

### afterRecordUpdate

This event is a record after-update trigger. This is an ideal mechanism to update the data model after data is known to have been updated.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be updated

**Example**

```javascript
function afterRecordUpdate(record) {
    if(record.projects_to_projects_users.newRecord()){              // create a link record
        record.projects_to_projects_users.user_id = globals.currentUserID;  // associate to current user
        databaseManager.saveData();
    }
}
```

### afterRecordDelete

This event is a record after-delete trigger. This is an ideal mechanism to update the data model after data is known to have been deleted.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that will be deleted

**Example**

```javascript
function afterRecordDelete(record) {
	if (record.orders_to_order_details.getSize()>0)
	{
		record.orders_to_order_details.deleteRecord();
		databaseManager.saveData();
	}
}
```

### onFoundSetRecordCreate

This event is a pre-trigger for a new record being created in the foundset. The event handler has the opportunity to prevent the operation to take place. This is an ideal place to set fail-safe data rules. When false is returned the record will not be created in the foundset.

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the record from being created in the foundset.

**Example**

```javascript
function onFoundSetRecordCreate() {
	// TODO Auto-generated method stub
	// return true so that the record can be created
	var valid = false;
	if (orders_to_order_details.getSize()>0)
	{
		valid = true;
	}
	return valid;
}
```

### onFoundSetFind

This event is a foundset pre-find trigger. The event handler has the opportunity to prevent the operation to take place. This is an ideal place to set fail-safe data rules. When false is returned the foundset will not go into find mode.

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the foundset to enter find mode.

**Example**

```javascript
function onFoundSetFind() {
	// TODO Auto-generated method stub
	// return true so that the record can be created
    if(record_count == 0) // record_count is an aggregation defined for the table, which counts the records
        return false;
    return true;
}
```

### onFoundSetSearch

This event is a foundset pre-search trigger. The event handler has the opportunity to prevent the operation to take place. This is an ideal place to set fail-safe data rules. When false is returned the search will not be executed and the foundset will stay in find mode.

**Parameters**

* **clearLastResults:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - tells whether or not to clear previous search
* **reduceSearch:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - tells to reduce (true) or extend (false) previous search results

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) - Return false to prevent the foundset to enter find mode.

**Example**

```javascript
function onFoundSetSearch(clearLastResults, reduceSearch) {
	// TODO Auto-generated method stub
	// return true so that the search will go on.
	if(record_count == 0) // record_count is an aggregation defined for the table, which counts the records
    	return false;
    return true;
}
```

### onFoundSetBeforeSelectionChange

This event is triggered before the foundset updates its selected record(s). It provides an opportunity to:

* Validate selection changes before they happen.
* Prevent selection changes if certain conditions are not met (e.g., data validation rules, restricted records).
* Implement custom logic before selecting new records. If the method returns `true` or nothing, the selection change proceeds.\
  If it returns `false`, the selection change is **blocked**, keeping the current selection.

**Parameters**

* **oldSelection:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The currently selected record(s)
* **newSelection:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record(s) that will become selected

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean):

* `true` (or no return value): Selection change proceeds.
* `false`: Selection change is blocked.

**Example**\
The following example prevents a selection change if the new record has a specific customer ID:

```javascript
function onFoundSetSelectionChange(oldSelection, newSelection) {
	// TODO Auto-generated method stub
	var valid = true;
	// test if it is valid.
	
    if (newSelection && newSelection.customerid === 100) {
        application.output("Selection blocked: Customer ID 100 cannot be selected.");
        valid = false; // Prevent selection change
    }

    // Allow selection change
	return valid;
}
```

### afterFoundSetRecordCreate

This event is a record after-create trigger. It occurs immediately following the operation executed on the foundset.

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that is created

**Example**

```javascript
function afterFoundSetRecordCreate(record) {
	// TODO Auto-generated method stub
	record.comment_text = "Some predefined comment text.\n" //every new record added to the foundset will have a predefined text on the comment_text column.
}
```

### afterFoundSetFind

This event is a foundset post-find trigger. When false is returned the foundset will not go into find mode.

**Example**

```javascript
function afterFoundSetFind() {
	// TODO Auto-generated method stub
	orders_to_order_details.loadAllRecords();
}
```

### afterFoundSetSearch

This event is a foundset post-search trigger. When false is returned the foundset will not go into find mode.

**Example**

```javascript
function afterFoundSetSearch() {
	// TODO Auto-generated method stub
	var current = foundset.getSelectedIndex();  //gets the current record index in the current foundset
	foundset.setSelectedIndex(current+1); //sets the next record in the foundset
}
```

### onValidate

Record validation method, will be called by databaseManager.validateRecord() and when databaseManager.saveData() is called.\
It validates changes or state of the record. All errors need to be reported in the recordMarkers that is then returned by databaseManager.validateRecord() and is also placed on the record itself (record.recordMarkers).

**Parameters**

* **record:** [JSRecord](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecord) - The record that must be validated
* **recordMarkers:** [JSRecordMarkers](https://docs.servoy.com/reference/servoycore/dev-api/database-manager/jsrecordmarkers) - The object where all the problems can be reported
* **stateObject:** [Object](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/object) - An object that a user can give to validateRecord for extra state (optional, can be null).

**Example**

```javascript
function onValidate(record, recordMarkers, stateObject) {
	// TODO Auto-generated method stub
	if (record.mynumber < 10) recordMarkers.report("mynumber must be greater then 10", "mynumber", LOGGINGLEVEL.ERROR);
}
```