> For the complete documentation index, see [llms.txt](https://docs.silkbuilder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkbuilder.com/js_object/dataprovider.js.md).

# DataProvider

The DataProvider Class provides properties, methods, and events to interface with JSON data returned by data Outlet services. The [silk:DataProvider](https://github.com/silkbuider/documentation/tree/master/tags/DataProvider.md) component creates the DataProvider object with a name as the component's ID.

```xml
<silk:DataProvider id="dataDP" servicePath="..." autoSelect="false" />
<silk:JQcode>
	dataDP.select();
</silk:JQcode>
```

**Kind**: global class

## Constructor

### new DataProvider(id, options)

Returns a DataProvider instance.

| Param                  | Type      | Default | Description                                                                                                                                                                                         |
| ---------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | `String`  |         | Unique identifier.                                                                                                                                                                                  |
| options                | `Object`  |         | Object containing the DataProvider configuration options.                                                                                                                                           |
| \[options.servicePath] | `String`  |         | The URL to the Outlet Service providing the data.                                                                                                                                                   |
| \[options.selectName]  | `String`  |         | The ORM's selectName used to extract the data.                                                                                                                                                      |
| \[options.treeData]    | `Boolean` | `false` | Indicates if the data will be treated as a hierarchical structure.                                                                                                                                  |
| \[options.markDeleted] | `Boolean` | `false` | Indicated that records will display like a deletion, but marked deleted in the database.                                                                                                            |
| \[options.isPublic]    | `Integer` | `0`     | Indicates if the service is publicly available. Use when accessing public Outlets from a private environment.                                                                                       |
| \[options.debugLevel]  | `Integer` | `0`     | Defines the debugging level.                                                                                                                                                                        |
| \[options.pkColumn]    | `String`  |         | The primary key column of the table accessed.                                                                                                                                                       |
| \[option.linkedDP]     | `String`  |         | The name of a related DataProvider that will be loaded after the local loading process ends. This could be a list of DataProvider’s names separated by commas.                                      |
| \[option.recordSync]   | `Boolan`  |         | The SELECT name used during the record sync process. If provided, it indicates that the DataProvider will automatically trigger the record sync method when a row is selected in a table component. |
| \[option.dpSort]       | `Boolean` | `false` | Indicates if the sorting will happen in the data provider.                                                                                                                                          |

## Methods

### addComponent(component)

Adds a component to the list of components that will be notified of changes in the DataProvider.\
The component must have a load() function.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param     | Type     | Description                           |
| --------- | -------- | ------------------------------------- |
| component | `Object` | The name of the component to be added |

### batch()

Submits multiple operations loaded into the *operationsObject,* performing a batch request.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### clean()

Cleans the data from the *selectObject*.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### cleanOperations(init)

Cleans the loaded operation action in the *operationObject* before adding operations programmatically. If the provided parameter is *true,* it will initialize an empty select action, which is used to initialize the request object as a select. Submitting an empty operation list will trigger an error.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param | Type      | Description                  |
| ----- | --------- | ---------------------------- |
| init  | `boolean` | (optional) Default is false. |

### cleanParameters()

Cleans the parameter list from the *requestObject*.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### delete(recordIndex)

Executes a DELETE request. Operation items should be added before calling this method.\
If the DataProvider's property *markDeleted* is *true*, it will perform a delete in the local data for visual effect, but an update in the database.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param       | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| recordIndex | `Integer` | (optional) The index of the item to be deleted |

### exec(operation)

Executes an ORM's SQL Operation. If the operation requires parameters that are not added in the "beforeLoad" or "beforeExec" events, they should be added before this method is executed.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param     | Type     | Description                      |
| --------- | -------- | -------------------------------- |
| operation | `String` | The operation name from the ORM. |

### getChildren(pkValue) ⇒ `Array`

Returns an array containing the generational children of a record.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param   | Type      | Description                        |
| ------- | --------- | ---------------------------------- |
| pkValue | `pkValue` | The primary key value to evaluate. |

### getComponents()

Returns the array containing the components which will be notify of changes in the data provider.\
The component must have a load() function.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getID()

Returns the component's unique identifier.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getIndex(pkValue)

Returns the index of the provided primary key value in the *selectObject*'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param   | Type     | Description                          |
| ------- | -------- | ------------------------------------ |
| pkValue | `String` | The primary key value to search for. |

### getIndexItem(pkValue)

Returns the item object of the provided primary key value in the *selectObject*'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param   | Type     | Description                          |
| ------- | -------- | ------------------------------------ |
| pkValue | `String` | The primary key value to search for. |

### getIndexItemOf(columnName, value)

Returns the item object of the entity matching the provided column and value in the *selectObject*'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param      | Type     | Description                   |
| ---------- | -------- | ----------------------------- |
| columnName | `String` | The column name use to filter |
| value      | `Object` | The value use to filter.      |

### getIndexOf(columnName, value)

Returns the index of the entity matching the provided column and value in the *selectObject*'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param      | Type     | Description                   |
| ---------- | -------- | ----------------------------- |
| columnName | `String` | The column name use to filter |
| value      | `Object` | The value use to filter.      |

### getItem(column)

Gets the object item of the first item in the *selectObject*'s data. If the column is provided, it returns the value of the column in the first position.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type     | Description                                         |
| ------ | -------- | --------------------------------------------------- |
| column | `String` | (optional) Column name whose value will be returned |

### getItemAt(index, column) ⇒ `Object`

Gets the object item from *selectObject*'s data at the provided index position. If a column is provided, it returns the value of the column at the provided position.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type      | Description                                             |
| ------ | --------- | ------------------------------------------------------- |
| index  | `Integer` | The object item's index position                        |
| column | `String`  | (optional) The column name whose value will be returned |

### getJSON() ⇒ `JSON`

Return the data provider data in JSON format

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getLangID() ⇒ `String`

Get the langID if it has been replaced.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getOperationIndex()

Return the value of the operation index. This is usually synchronized with the selected index value.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getOperationItem(index)

Returns the operation Item from the *operationObject*. If the index is not provided, return the first one. If the DataProvider does not have data, it returns an empty object.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param | Type      | Description                     |
| ----- | --------- | ------------------------------- |
| index | `integer` | The operation index (optional). |

### getPkColumn()

Returns the name of the primary key column.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getPKValue()

Returns the primary key's value of the selected data item.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getSelectedItem(columnName)

Returns the *selectObject's* item using the *selectedIndex* property. By default, the *selectedIndex* is 0;

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param      | Type     | Description                                                   |
| ---------- | -------- | ------------------------------------------------------------- |
| columnName | `String` | The column to return. If not provided return the item object. |

### getSelectName()

Returns the selected name to be used to load the data.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getService()

Returns the service path.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### getSortColumn() ⇒ `String`

Returns the name of the column used for data sorting.

**Kind**: instance method of [`DataProvider`](#DataProvider)\
**Returns**: `String` - - Column name<br>

### getSortDirection() ⇒ `Integer`

Gets the sorting direction. 1 is an ancestor, and -1 is a descendant.

**Kind**: instance method of [`DataProvider`](#DataProvider)\
**Returns**: `Integer` - - Sorting Direction<br>

### getSQLSortColumn() ⇒ `String`

Returns the column used for sorting with added SQL keywords 'asc' or 'desc' based on the sorting direction. If the sorting column is composite ("column, column"), the SQL direction keyword will be added to each column.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### insert()

Executes an INSERT request. Operation items should be added before calling this method.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### isTreeData()

Return a boolean indicating if the data is set to be tree structured

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### length()

Returns the number of records in the data array. This is similar to the *size()* method.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### load(internalCall)

Submits the operations from the *requestObject* and loads the response from the Outlet service into the *selectObject*. The parameter is only for the frame's work internal use.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param        | Type      | Description                                                |
| ------------ | --------- | ---------------------------------------------------------- |
| internalCall | `boolean` | (Optional) True if call internally within the DataProvider |

### loadJSON(json)

Load data from a JSON string into the \*selectObject"'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param | Type     | Description                      |
| ----- | -------- | -------------------------------- |
| json  | `String` | The JSON structure to be parsed. |

### on

Load events to respond to the DataProvider's interactions. To set an event, use this code: `DataProvider.on(<eventName>, function(){<code>})`.

**Kind**: instance property of [`DataProvider`](#DataProvider)

| Param         | Type       | Description                   |
| ------------- | ---------- | ----------------------------- |
| eventName     | `String`   | The event's name.             |
| eventFunction | `function` | The function to be triggered. |

### operationObject

An object containing the returned Outlet Service data after insert, update, delete, exec, or batch.

**Kind**: instance property of [`DataProvider`](#DataProvider)<br>

### recordSync(syncSelectName)

Executes the SELECT name provided in the recordSync intialization parameter to sync the loaded record with the new database record data. This will only affect the selected item. If the parameter syncSelectName is provided it overwrites the default select. If the SELECT requires query parameters, these should be added using the "beforeRecordSync" event.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param          | Type     |
| -------------- | -------- |
| syncSelectName | `String` |

### select(selectName)

Executes a SELECT request. By default, it uses the select's name configured in the DataProvider. If a different request needs to be executed, it has to be provided as a parameter. Query parameters should be added before calling this method.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param      | Type     | Description                                              |
| ---------- | -------- | -------------------------------------------------------- |
| selectName | `String` | (optional) (optional) The name of a select from the ORM. |

### selectObject

An object containing the data returned from the Outlet Service after a select operation.

**Kind**: instance property of [`DataProvider`](#DataProvider)<br>

### setItem(column, value)

Sets the column's value of the first item in the *selectObject*'s data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type     | Description        |
| ------ | -------- | ------------------ |
| column | `String` | The target column. |
| value  | `String` | The value.         |

### setItemAt(index, column, value)

Sets the column's value of the *selectObject*'s data at the provided index.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type      | Description         |
| ------ | --------- | ------------------- |
| index  | `Integer` | Array index target. |
| column | `String`  | The target column.  |
| value  | `String`  | The value.          |

### setLangID((String})

Set the langID, it is used to overwrite the session's loaded *langID* variable.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param    | Description                |
| -------- | -------------------------- |
| (String} | newLangID - The new langID |

### setOperationAction(action, operation)

Sets an action in the *operationObject*. After setting an operation action, it becomes the active action and is ready to receive operation items.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param     | Type     | Description                                                         |
| --------- | -------- | ------------------------------------------------------------------- |
| action    | `String` | The action to execute: select, insert, update, delete, exec, batch. |
| operation | `String` | (optional) The name of the operation when action is set to exec.    |

### setOperationItem(column, value)

Sets an operation item to the current operation action. The item contains the column and value to be operated on.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Description     |
| ------ | --------------- |
| column | The column name |
| value  | The value       |

### setParameter(column, value, type, secure)

Sets a parameter in the *requestObject*. If the parameter exists, it gets updated.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type      | Description                                                                                       |
| ------ | --------- | ------------------------------------------------------------------------------------------------- |
| column | `String`  | The column name                                                                                   |
| value  | `Object`  | The value                                                                                         |
| type   | `String`  | (optional) One character value (S,I,N,D,T) to force data convertion                               |
| secure | `booelan` | (optional) To inndicates if the value is encrypted. To overwrite what has been define in the ORM. |

### setSelectedIndex(index1, index2)

Changes the internal data index to the provided value. By default, the selected index should be synchronized with the operation index. The selected index is connected to the view, such as a table, which could display the rows in a different order than the DataProvider order.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param  | Type      | Description                        |
| ------ | --------- | ---------------------------------- |
| index1 | `Integer` | Index to the view.                 |
| index2 | `Integer` | Index to the operation (Optional). |

### setSelectName(newSelectName)

Set the name of the select from the ORM, which will be used to load the data.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param         | Type     | Description          |
| ------------- | -------- | -------------------- |
| newSelectName | `String` | The new select name. |

### setSortColumn(column, direction)

Initializes the sorting column and/or direction before the DataProvider loads the data. The direction is optional. If the sorting happens in the database, then before executing a select, the sort column has to be set up to match the select order.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param     | Type      | Description                                       |
| --------- | --------- | ------------------------------------------------- |
| column    | `String`  | Column name                                       |
| direction | `Integer` | Sorting direction. 1 - accedant, -1 is descendant |

### setTimeout()

The number of milliseconds before triggering a timeout error. The default value is 30 seconds.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### size()

Returns the number of records in the data array. This is similar to the *length()* method.

**Kind**: instance method of [`DataProvider`](#DataProvider)<br>

### sort(column, changeOrder)

Sorts, or orders, the data by the provided column. This does not work if the DataProvider is set to *treeData="true"*.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param       | Type      | Description                                      |
| ----------- | --------- | ------------------------------------------------ |
| column      | `String`  | Column to sort                                   |
| changeOrder | `Boolean` | (Optional) If set to false cancels order switch. |

### sourceType

Indicates the type of data source. These could be:\
SQL : From SQL database\
Local : Loaded using the loadJSON method. This JSON structure is provided as part of the DataProvider content.\
JSON : Data from file containing JSON.

**Kind**: instance property of [`DataProvider`](#DataProvider)<br>

### update(recordIndex)

Executes an UPDATE request. Operation items should be added before calling this method.

**Kind**: instance method of [`DataProvider`](#DataProvider)

| Param       | Type      | Description                                    |
| ----------- | --------- | ---------------------------------------------- |
| recordIndex | `Integer` | (optional) The index of the item to be updated |

## Events

### on:afterBatch

This event is triggered after the batch action is executed. It is created with the `DataProvider.on("afterBatch", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:afterDelete

This event is triggered after the delete action is executed. It is created with the `DataProvider.on("afterDelete", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:afterExec (operation)

This event is triggered after the exec action is executed. It is created with the `DataProvider.on("afterExec", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param     | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| operation | `String` | The operation to be executed. |

### on:afterInsert

This event is triggered after the insert action is executed. It is created with the `DataProvider.on("afterInsert", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:afterLoad (action, operation)

This event is triggered after the load action is executed. It is created with the `DataProvider.on("afterLoad", function(action,operation){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param     | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| action    | `String` | The action to be executed.    |
| operation | `String` | The operation to be executed. |

### on:afterRecordSync (selectName)

This event is triggered after the record sync action is executed. It is created with the `DataProvider.on("afterRecordSync", function(selectName){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param      | Type     | Description                                            |
| ---------- | -------- | ------------------------------------------------------ |
| selectName | `String` | The name of the select with in the ORM to be executed. |

### on:afterSelect (selectName)

This event is triggered after the select action is executed. It is created with the `DataProvider.on("afterSelect", function(selectName){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param      | Type     | Description                                            |
| ---------- | -------- | ------------------------------------------------------ |
| selectName | `String` | The name of the select with in the ORM to be executed. |

### on:afterUpdate

This event is triggered after the update action is executed. It is created with the `DataProvider.on("afterUpdate", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:beforeBatch

This event is triggered before the batch action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeBatch", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:beforeDelete

This event id triggered before the delete action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeDelete", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:beforeExec (operation)

This event is triggered before the exec action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeExec", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param     | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| operation | `String` | The operation to be executed. |

### on:beforeInsert

This event is triggered before the insert action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeInsert", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:beforeLoad (action, operation)

This event is triggered before the load action is executed. If the event function returns *false* the process is canceled. It is created with the `DataProvider.on("beforeLoad", function(action,operation){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param     | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| action    | `String` | The action to be executed.    |
| operation | `String` | The operation to be executed. |

### on:beforeRecordSync (selectName)

This event is triggered before the record sync action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeRecordSync", function(selectName){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param      | Type     | Description                                     |
| ---------- | -------- | ----------------------------------------------- |
| selectName | `String` | (Optional) The name of the select to be called. |

### on:beforeSelect (selectName)

This event is triggered before the select action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeSelect", function(selectName){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param      | Type     | Description                          |
| ---------- | -------- | ------------------------------------ |
| selectName | `String` | The name of the select to be called. |

### on:beforeUpdate

This event is triggered before the update action is executed. If the event function returns *false* the process is canceled. Created with the `DataProvider.on("beforeUpdate", function(){})` method.

**Kind**: event emitted by [`DataProvider`](#DataProvider)<br>

### on:error (error)

This Event is triggered when an error has occurred. It is created with the `DataProvider.on("error", function(errorObject){})` method. If the event returns an object, this will replace the existing operationObject.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param | Type     | Description                |
| ----- | -------- | -------------------------- |
| error | `Object` | The returned error object. |

### on:markDeleted (requestObject)

This event is triggered before a delete action is processed. Created with the `DataProvider.on("markDeleted", function(requestObject){})` method. The event is triggered before the event "beforeDelete", so the data changes are considered part of the original submission process and not affected by other internal actions.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param         | Type     | Description                         |
| ------------- | -------- | ----------------------------------- |
| requestObject | `Object` | The return objected to be operated. |

### on:processLoadedData (returnObject) ⇒ `Object`

This event is triggered when the received data is being processed. It is created with the `DataProvider.on("processLoadedData", function(returnObject){})` method. If the event returns an object, this will replace the existing *selectObject*. This event can process the received data before loading it into the *selectObject*.

**Kind**: event emitted by [`DataProvider`](#DataProvider)

| Param        | Type     | Description                         |
| ------------ | -------- | ----------------------------------- |
| returnObject | `Object` | The return objected to be operated. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.silkbuilder.com/js_object/dataprovider.js.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.