=====
apply
=====

.. js:function:: apply(callback, params, async) 

**domain**: client 

**language**: javascript

**class** :doc:`Item class </refs/client/item_api>`

Description
===========

Sends all updated, inserted, and deleted records from the item dataset to the 
application server for writing to the database.

The ``apply`` method can have the following parameters:

* ``callback``: if the parameter is not present, the request to the server is 
  sent synchronously, otherwise, the request is executed asynchronously and 
  after the responce is received, the callback is executed

* ``params`` - an object specifying user defined params, that can be used 
  on the server in the
  :doc:`on_apply </refs/server/item/on_apply>`
  event handler for some additional processing

* ``async``: if its value is true, and callback parameter is missing, the request 
  is executed asynchronously 

The order of parameters doesn't matter.

The ``apply`` method

* checks whether the item is a detail, and if it is, returns 

* checks whether the item is in edit or insert 
  :doc:`state <at_item_state>`
  , and if so, posts the record
  
* checks if the change log has changes, and if not, 
  triggers the 
  :doc:`on_before_apply <on_before_apply>`
  event handler if one is defined for the item, 
  triggers the 
  :doc:`on_after_apply <on_after_apply>`
  event handler if one is defined for the item, 
  executes callback if it is passed and then returns

* triggers the 
  :doc:`on_before_apply <on_before_apply>`
  event handler if one is defined for the item 

* sends changes to the server 

* server on receiving the request checks whether
  :doc:`on_apply </refs/server/item/on_apply>`
  event handler is defined for the item, and if it is, executes it, otherwise   
  generates and executes SQL query to write changes to the database
  
* when generating an SQL query, checks whether a user, that send the request, has 
  rights to make these changes, if not raises an exception
  
* writes changes to the database  

* after writing changes to the database, server sends to the client results
  of the execution

* if exception was raised during the operation on the server and the callback 
  parameter is not present (synchronous execution), the client throws an exception

* the client, based on the results, updates the change log   

* triggers the 
  :doc:`on_after_apply <on_after_apply>`
  event handler if one is defined for the item 
 
* if the callback parameter is passed, it is called. If exception was raised 
  during the operation on the server the the error is passed as callback 
  parameter

.. note::
    The server, before writing new records to the database table, generates 
    values for the primary fields. The client updates these fields, based on 
    information received from the server. If you change values of some other 
    fields in the 
    :doc:`on_apply </refs/server/item/on_apply>`
    event handler, these changes will not be reflected on the client. You must
    update them yourself.
    
See also
========

:doc:`Modifying datasets </programming/data/modifying_datasets>`